Brand Identity & UX Design System¶

Design Direction¶

Chosen direction: Warm Ops -- a warm, approachable aesthetic with balanced density and spring-physics interactions, combined with semantic state-driven color encoding where every color communicates system status rather than serving as decoration.

Why this direction: Warmth makes an AI operations tool feel approachable without losing professionalism. Tying color exclusively to state (green = rising, amber = attention, red = critical) gives operators instant comprehension of system health. The brand accent is a warm soft blue -- deliberately neutral so that semantic state colors dominate the visual hierarchy. Orange/amber means "attention needed," not "this is SynthOrg."

What was rejected and why: A cool blue-cyan palette (data center aesthetic) was too generic -- indistinguishable from Grafana/Datadog screenshots. A neutral gray palette (no hue) lacked enough identity to be recognizable. A high-energy violet/purple palette was visually fatiguing for sustained 8-hour use. These directions scored well on individual criteria but failed the combination of identity distinctiveness + sustained usability.

Design influences: Linear (clean layout, balanced density), Vercel (status-first design), Dust.tt (warm approachability), Grafana (data density as a user preference).

Color System¶

Semantic Color Tokens¶

Colors are state-driven, not decorative. Every colored element answers: "what is the system telling me?"

Dynamic Color Assignment¶

Metric cards, sparklines, and trend indicators use colors dynamically based on direction of change:

This ensures operators instantly understand system state from colors alone, without reading values. The same metric card shows green when tasks are completing faster and amber when they are slowing down.

How to Add a New Color Theme¶

Each theme is a single configuration object (~50 lines). All colors are CSS custom properties consumed via var(--theme-*) tokens. To add a new theme:

1. Create a new theme config (e.g. themes/midnight.ts) with all color tokens
2. Register it in the theme index
3. Done -- all components automatically pick up the new palette

No component code changes required. The 5 exploration themes (Ice Station, Warm Ops, Stealth, Signal, Neon) demonstrate this pattern -- each theme is ~50 lines of color token definitions with zero component changes.

Typography¶

Chosen Pairing¶

Rationale: Geist was designed by Vercel specifically for developer dashboards. Excellent readability at small sizes, clean number rendering in mono, professional but not clinical in sans.

Typography is a theme axis: other pairings (JetBrains Mono + Inter, IBM Plex Mono + IBM Plex Sans) are available and can be selected independently of colors.

Self-Hosted Fonts¶

All fonts are bundled via @fontsource packages. No external CDN (Google Fonts) dependencies. This ensures: - No GDPR/privacy issues from third-party font loading - Consistent rendering regardless of network - Faster first contentful paint (no font fetch waterfall)

Density¶

Density is an independent user preference, not tied to theme colors.

Token usage: Components must use density-aware token classes (p-card, space-y-section-gap, gap-section-gap, gap-grid-gap) instead of the raw Tailwind utilities shown above. The raw values are what each token resolves to at each density level.

How to Add a New Density Level¶

Create a new ThemeDensity object with padding, gap, and font size values. Register it in the density index. Components read density from the theme context -- no component changes needed.

Animation¶

Animation is an independent user preference, controlling motion intensity.

Recommended default: Status-driven. Animation should communicate state change, not decoration. Static elements stay still; only things that changed move.

Sidebar¶

Sidebar mode is an independent user preference.

Persistence¶

Sidebar collapse state is persisted in user preferences. If a user collapses the sidebar, it stays collapsed across sessions until they expand it again.

Theme Architecture¶

Independent Axes¶

The theme system has 5 orthogonal axes that users can configure independently:

Color Palette  x  Density  x  Typography  x  Animation  x  Sidebar Mode

This gives users full control without combinatorial explosion in theme definitions. A user can run "warm blue colors + dense layout + IBM Plex fonts + minimal animation + compact sidebar" without any custom theme code.

Implementation Pattern¶

ThemeProvider (React context)
  |-- sets CSS custom properties on wrapper div (--theme-accent, --theme-bg-base, etc.)
  |-- Tailwind @theme block maps --theme-* to Tailwind utility classes
  |-- Components use Tailwind classes (text-accent, bg-bg-card, border-border)
  |-- Density/animation read from theme context object
  |-- Sidebar mode selects which sidebar component to render

Critical Implementation Note: Tailwind v4 CSS Layers¶

When using Tailwind v4 with @import "tailwindcss", all custom CSS resets MUST be inside @layer base. Tailwind v4 uses CSS cascade layers, and unlayered styles (like * { margin: 0; padding: 0; }) have higher priority than layered utilities, silently overriding all spacing, padding, margin, and gap utilities.

/* WRONG -- breaks all Tailwind spacing utilities */
* { margin: 0; padding: 0; }

/* CORRECT -- respects Tailwind cascade layers */
@layer base {
  * { margin: 0; padding: 0; }
}

This was discovered during the design exploration (#765) and caused layout breakage that was difficult to diagnose because the utilities appeared in the generated CSS but had no visual effect.

Dark Mode¶

Dark mode only (confirmed in #762 research). No light mode planned. All color tokens assume dark backgrounds. WCAG AA contrast ratios are validated against dark card/surface backgrounds.

Accessibility¶

• WCAG AA contrast minimum on all text (4.5:1 on backgrounds, 3:1 for large text)
• prefers-reduced-motion supported: AnimatedPresence uses reducedPageVariants (opacity-only fade), skeleton shimmer disabled via CSS media query, Framer Motion's useReducedMotion() hook used for runtime detection
• Keyboard navigation for all interactive elements
• aria-hidden="true" on decorative icons
• Escape key closes overlays/drawers
• Storybook a11y enforcement: parameters.a11y.test: 'error' set globally in .storybook/preview.tsx -- all stories fail on WCAG violations, catching regressions at component development time

Storybook Tooling (v10)¶

The component development environment uses Storybook 10 with native type-safe configuration:

• Config: defineMain (from @storybook/react-vite/node) and definePreview (from @storybook/react-vite) for full TypeScript inference
• Addons: @storybook/addon-docs (autodocs) and @storybook/addon-a11y (WCAG testing). Essentials (backgrounds, controls, viewport, actions) and interactions are built into core
• Backgrounds: Selected via initialGlobals.backgrounds.value = 'dark', which references our --so-bg-base token (#0a0a12) through backgrounds.options.dark.value, ensuring stories render against the actual brand dark background
• Decorator: Global dark-mode wrapper (div.dark.bg-background.p-4.text-foreground) applies our design tokens to all stories
• API mocking: MSW (Mock Service Worker) via msw-storybook-addon. Global mswLoader in preview.tsx intercepts API calls. Stories declare handlers via parameters.msw.handlers using pre-built handler arrays from web/src/mocks/handlers/. All responses use the ApiResponse<T> envelope via apiSuccess() helper

Component Inventory¶

The following shared components live in web/src/components/ui/ and form the building blocks for all dashboard pages. Always compose pages from these -- never recreate equivalent functionality inline.

Core Components¶

Interaction Components¶

Utility Functions¶

Design System Hooks¶

Types¶

When to Create a New Shared Component¶

Create a new component in web/src/components/ui/ when:

1. The same UI pattern appears (or will appear) on 2+ pages
2. It represents a semantic concept (not just a styled div)
3. It has configurable behavior via props (variants, states, sizes)

Every new shared component must have:

• A .stories.tsx file with all states (default, hover, loading, error, empty)
• A TypeScript props interface
• Design token usage exclusively (no hardcoded colors/fonts/spacing)
• cn() for conditional class merging

Enforcement¶

A PostToolUse hook (scripts/check_web_design_system.py) runs automatically on every Edit/Write to web/src/ files. See CLAUDE.md "Web Dashboard Design System" section for the full rule set.

Reference Materials¶