UI component system [SPEC]

Version: 2.0.0 Last Updated: 2026-03-14 Package: packages/ui/

Reader orientation: This document specifies @bardo/ui, the shared React component library for all Bardo web surfaces (Portal dashboard, debug UI, browser SPA). It belongs to the interfaces layer and implements the ROSEDUST design language (rose on violet-black surfaces with restrained bone accents). This is NOT the Golem’s primary interface; that is the TUI (bardo-terminal), a separate Rust/ratatui application. Key concepts: Golem (a mortal autonomous DeFi agent), the Portal (web dashboard for agent setup and analytics, see 00-portal.md), and the bardo-sprites WASM module for creature rendering. For unfamiliar terms, see prd2/shared/glossary.md.

Overview

@bardo/ui is the shared React component library for all Bardo web surfaces. It implements the ROSEDUST design language – rose on violet-black surfaces with restrained bone accents that communicate safety, precision, and sophistication.

This library serves the Portal (web dashboard), debug UI, and browser SPA. It is not the Golem’s primary UI. The Golem’s primary interface is the TUI (bardo-terminal), a separate Rust/ratatui application. The React components here are for web surfaces where TypeScript and React are the right tools: onboarding wizards, analytics dashboards, reputation profiles.

The package is internal (no npm publish), consumed via direct TypeScript source imports.

Scope boundaries

The web Portal can render creatures by embedding the bardo-sprites WASM module in an HTML5 Canvas – same procedural generation as the TUI, different rendering target. But the creature interaction model (pet, steer, dream visualization, death cinematic) lives in the TUI, not the web components.

Design philosophy

Core principles

1. ROSEDUST – Near-black surfaces (bg_void #060608) with rose as the primary color and restrained bone accents. Bone is earned, not decorative. Every bone element signals something meaningful: the single most important element on screen.

2. Engineering aesthetic – PCB traces, hexagonal connectors, octagonal clip-paths, monospaced data. Hardware metaphors ground abstract financial concepts.

3. Glass over void – Layered transparency creates depth without color. Glass cards float above the void-dark base. Backdrop blur separates content layers.

4. Typography as hierarchy – Three fonts, three purposes. Serif for authority. Mono for data and truth. Sans for comfortable reading.

5. Motion as meaning – Luxury-eased animations with deliberate pacing. Nothing snaps. Nothing bounces. Elements glide into position.

6. Restraint – Dark surfaces need empty space. Gold loses its power when overused.

Color system

Foundation palette

Never use pure #000000. The 0A0A0A black has enough warmth to prevent the “hole in the screen” effect.

Gold system

Tier color system

Debug UI adaptations

The debug UI (developer-facing) uses a blue-shifted color variant:

Typography

Scale

Glass morphism system

Three elevation levels:

Component library

Layout

Data display

Input

Feedback

Hooks

Animation system

Timing functions

Motion patterns

• Page fade-in: 250ms opacity transition on mount
• Stagger delays: 50ms per item in lists
• Card hover: 200ms scale(1.01) + border color transition
• Scroll reveal: IntersectionObserver with 100px threshold, 400ms fade-up

Tech stack

Package configuration

{
  "name": "@bardo/ui",
  "private": true,
  "type": "module",
  "exports": {
    ".": { "types": "./src/index.ts", "default": "./src/index.ts" },
    "./*": { "types": "./src/*.ts", "default": "./src/*.ts" }
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

Internal package – no build step. Consumers import TypeScript source directly. Test environment uses happy-dom.

Context-specific adaptations

Accessibility

• All interactive elements have visible focus indicators (gold ring)
• Color contrast ratio >= 4.5:1 for text, >= 3:1 for large text
• Radix UI primitives provide keyboard navigation and ARIA attributes
• prefers-reduced-motion disables all animations except opacity transitions
• Screen reader text provided for icon-only buttons