UX Design Guidelines¶

This document is the single source of truth for all v0.5.0 dashboard page implementations. It codifies the decisions from the design exploration (#765, Warm Ops winner) and page structure (#766) into concrete, implementable specifications.

Prerequisite reading: Brand Identity & UX Design System for rationale behind each decision. This document covers the what; brand-and-ux.md covers the why.

1. Brand Identity¶

1.1 Color System¶

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

Semantic Color Tokens¶

All hex values are WCAG AA verified (see Section 5.1).

Dynamic Color Assignment¶

Metric cards, sparklines, and trend indicators assign color by data direction:

Dark Mode Only¶

The dashboard is dark-mode only (confirmed in #762). All color tokens assume dark backgrounds. No light mode is planned. WCAG AA ratios are validated against bg-base, bg-surface, bg-card, and bg-card-hover.

1.2 Typography Scale¶

Font Families¶

All fonts self-hosted via @fontsource -- no external CDN dependencies.

Type Scale¶

Rule: Numbers and data always use monospace. Labels and descriptions always use sans-serif.

1.3 Spacing Grid¶

Base unit: 8px. All spacing values follow a 4px sub-grid (half the 8px base unit).

1.4 Logo and Wordmark Usage¶

1.5 Visual Signatures¶

These 3 elements create instant "this is SynthOrg" recognition:

1. Warm soft blue accent (#38bdf8) -- brand-neutral so state colors dominate, but present in links, focus rings, active nav, and sparkline defaults
2. Dark cards with subtle borders -- bg-card (#13131f) with 1px border (#1e1e2e), 8px border-radius. Cards float above bg-base without heavy shadows
3. Monospace data values -- Geist Mono for all numbers, metrics, agent names, and timestamps creates a "control room" feel where data is always legible and aligned

2. Component Patterns¶

2.1 Card Anatomy¶

All cards share a consistent structure:

+----------------------------------------------+
|  [icon]  Title                     [status *] |  <- Header (12px vertical padding, 16px horizontal)
|----------------------------------------------|  <- 1px border-bottom (border token)
|                                              |
|  Content area                                |  <- 14-16px padding (density-dependent)
|  (metrics, text, charts, or mixed)           |
|                                              |
|----------------------------------------------|  <- Optional: 1px border-top
|  Footer: secondary info        timestamp     |  <- 10-12px vertical padding
+----------------------------------------------+

Card specs:
  Background:    bg-card (#13131f)
  Border:        1px solid border (#1e1e2e)
  Border-radius: 8px (--radius-lg)
  Padding:       16px (balanced density)
  Hover:         bg-card-hover (#181828), translateY(-1px),
                 box-shadow: 0 4px 24px accent/8%

Card states¶

2.2 Status Encoding Rules¶

Status is never communicated by color alone. The encoding hierarchy:

Status dot spec¶

2.3 Data Display Specs¶

Sparkline¶

Progress bar¶

Gauge (arc)¶

Change badge¶

2.4 MetricCard Layout¶

+----------------------------------------------+
|  TASKS TODAY              [sparkline 60x28]  |  <- Label: 11px uppercase, 0.06em spacing
|  24                                          |  <- Value: 26px mono, weight 700
|  ========== (progress bar, optional)         |  <- 2px height, full width
|  of 30 completed               +12%         |  <- Sub: 12px / Change badge: 11px mono
+----------------------------------------------+

2.5 AgentCard Layout¶

+----------------------------------------------+
|  [avatar]  Agent Name              [* dot]   |  <- Name: 13px sans weight 600
|            Software Engineer                 |  <- Role: 12px, text-secondary
|----------------------------------------------|
|  Dept: Engineering     Task: Fix auth bug    |  <- 12px, text-secondary
|                                   2m ago     |  <- 10px mono, text-muted
+----------------------------------------------+

The AgentCard layout must be identical across the Agents page, Org Chart nodes, Dashboard agent list, and any other surface showing agents.

3. Interaction Design¶

3.1 Progressive Disclosure Levels¶

Rules:

• L0 must be scannable in < 1 second (3-5 data points maximum per card)
• L1 tooltips must never contain interactive elements (links, buttons)
• L2 panels are URL-addressable for deep linking (e.g. /agents/{name})
• L3 navigation always creates a browser history entry

3.2 Hover Behavior¶

3.3 Inline Editing¶

For settings values, agent names, and editable fields:

3.4 Drag-and-Drop¶

For task board kanban columns and org chart hierarchy view:

3.5 Command Palette (Cmd+K)¶

Built with the cmdk library.

Scope behavior¶

Keyboard navigation¶

4. Animation Language¶

4.1 Framer Motion Presets¶

All animation values are defined in web/src/lib/motion.ts and imported as constants. Never hardcode animation values in components.

Spring presets¶

Tween presets¶

4.2 Page Transitions¶

4.3 Card Entrance¶

Cards stagger their entrance when a page loads or data first arrives.

4.4 Status Change Animation¶

When a value updates in real-time (via WebSocket):

No animation on initial page load -- only on subsequent real-time updates after the page is settled.

4.5 Real-Time Update Feedback¶

4.6 What NOT to Animate¶

4.7 Reduced Motion¶

When prefers-reduced-motion: reduce is active:

• All spring animations become instant (duration: 0)
• Tween durations halve (200ms -> 100ms)
• Infinite animations (pulse, shimmer) are disabled
• Page transitions reduce to simple opacity fade (150ms)
• Card entrance stagger is removed (all cards appear simultaneously)

5. Accessibility¶

5.1 WCAG AA Contrast Matrix¶

All foreground/background combinations verified with scripts/wcag_check.py. Thresholds: normal text >= 4.5:1, large text >= 3.0:1.

Result: All 32 foreground/background combinations pass WCAG AA for both normal and large text.

Closest to threshold: danger on bg-card-hover at 4.65:1 (threshold 4.5:1). This is safe but should not be used at font sizes smaller than 11px.

5.2 Focus Indicators¶

5.3 ARIA Requirements¶

5.4 Status Encoding¶

Status must never be color-only. Every status indicator includes:

1. Color -- semantic state color (success/warning/danger/accent)
2. Shape -- dot (6px circle) or icon (Lucide icon set)
3. Text label -- explicit text for critical states ("Active", "Error", "Idle")

For non-critical contexts where space is limited (e.g. compact table rows), color + shape is acceptable, but an aria-label must provide the text equivalent.

5.5 Touch and Click Targets¶

6. Responsive Breakpoints¶

Scope inherited from Page Structure & IA. Desktop-first with minimal tablet support.

Breakpoint Definitions¶

Layout Adaptations¶

Sidebar Behavior by Breakpoint¶

Sidebar state is persisted in user preferences. When resizing from >= 1280px into the 1024-1279px range, the sidebar auto-collapses to the icon rail. The user's theme preference is not mutated -- the effective mode is computed locally by combining the preference with the current breakpoint. At tablet (768-1023px), the sidebar renders as a 240px overlay via the shared Drawer component (role="dialog", aria-modal="true") with a blurred semi-transparent backdrop. It is triggered by a hamburger button (Menu icon) in the StatusBar, with aria-expanded tracking. The overlay closes on: backdrop click, X button, Escape key, or navigation (clicking a nav item). Below 768px, a MobileUnsupportedOverlay shows "Desktop Required" with a CLI hint (synthorg status).

Exported Artifacts¶

Tailwind @theme Snippet¶

The following @theme block contains all design tokens for Tailwind v4. This replaces the existing color definitions in web/src/styles/global.css (to be integrated in #775).

Note: The @theme block uses Tailwind's native property naming (--color-*, --spacing-*), while design-tokens.css uses the --so-* prefix for non-Tailwind contexts. Both define the same underlying values.

@theme {
  /* Brand colors */
  --color-accent: #38bdf8;
  --color-accent-dim: #0ea5e9;

  /* State colors */
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;

  /* Text colors */
  --color-text-primary: #e2e8f0;
  --color-text-secondary: #94a3b8;
  --color-text-muted: #8b95a5;

  /* Background colors */
  --color-bg-base: #0a0a12;
  --color-bg-surface: #0f0f1a;
  --color-bg-card: #13131f;
  --color-bg-card-hover: #181828;

  /* Border colors */
  --color-border: #1e1e2e;
  --color-border-bright: #2a2a3e;

  /* Typography */
  --font-sans: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'Geist Mono Variable', ui-monospace, monospace;

  /* Spacing (8px base) */
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-3: 12px;
  --spacing-4: 16px;
  --spacing-5: 20px;
  --spacing-6: 24px;
  --spacing-8: 32px;
  --spacing-10: 48px;
  --spacing-12: 64px;

  /* Radii */
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 8px;
  --radius-xl: 12px;
}

CSS Custom Properties¶

Exported to web/src/styles/design-tokens.css for non-Tailwind contexts (e.g. inline styles, third-party library theming, SVG styling).

Framer Motion Config¶

Exported to web/src/lib/motion.ts as TypeScript constants. Import and use:

import { springDefault, tweenDefault, cardEntrance, staggerChildren } from "@/lib/motion";

<motion.div variants={cardEntrance} initial="hidden" animate="visible">
  ...
</motion.div>

Reference Materials¶