UX Design Guidelines¶

This document is the single source of truth for all 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 Colour System¶

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

Semantic Colour Tokens¶

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

Dynamic Colour Assignment¶

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

Dark Mode Only¶

The dashboard is dark-mode only (confirmed in #762). All colour 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 colours 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 colour 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.

2.6 Names, Never Ids (MANDATORY)¶

An identifier is a database key. It is not memorable, not comparable by eye, and it crowds out the name it stands in for, so no dashboard surface ever renders one: not an agent id, not a task id, not a project or plan id, and not "as a fallback" when a lookup misses.

Where the name comes from. The backend resolves it, once per response, and sends it beside the id it stands for (assigned_to + assigned_to_name, owner + owner_name, lead + lead_name, task_id + task_title). The browser never resolves a reference a row carries: a client-side lookup has to fetch the roster first, which means an id renders on the first paint of every cold load and renders forever for anyone the fetched page did not cover. That is not a timing bug to tighten; it is the wrong place for the question.

A page reading the entity it is about is a different thing and stays in the browser. useProjectName and useWorkflowName each take a route parameter and read that one row; no response could carry the answer, because the page's own content is what the request is for. Two rules still hold there: the key never renders (the hook answers Unknown project while unresolved, never the identifier from the URL), and the resolved name is stored with the id it was read for. A name held on its own outlives its route, so moving between two projects labels the new one with the previous one's name until the next read lands, and permanently if that read fails.

What to show when there is no name. The surface's own words, never the key: Unassigned for nobody assigned, Unknown agent for an actor the roster no longer covers, Task no longer available for a reference whose row is gone. A resolved name of null is the backend saying it has no name to give, which is a fact worth printing plainly.

Where the id still belongs. In the row, in the URL, in a key prop, and in a link's href: correlation, routing and React identity all need the key and none of them are read by a person. A link is labelled by the name and navigates by the id.

Where a leak actually happens. At three boundaries, and a rule that watches only one of them is theatre, because all three shipped: the render itself; the mapping layer that fills a name-shaped field (agentName: event.related_ids.agent_id, whose render site reads perfectly); and the backend prose an event carries in its own description, which survives even once the name beside it is resolved.

Enforced by scripts/check_no_raw_id_in_ui.py at all three. It fails a JSX text child or an aria-label / title whose expression ends in an identifier, a *name / *title / *label field assigned one, and a *Event description f-string interpolating one. A name is judged an identifier by its _id / Id suffix, so a field added next year is refused until somebody writes down why it is a word; the handful carrying no suffix (owner, lead, assigned_to and their kin) are declared. Prose sitting beside the expression does not exempt it.

A lone name is read too (<div>ID: {nodeId}</div>), but only once its container is established as an element's child and nothing in front of it makes it a destructure, an import specifier, a guarded object literal, or a block. That distinction needs the surrounding text rather than the expression, which is why it was left out at first, and the omission cost a real leak: a properties drawer printed a node id the editor mints from a UUID. Comments are blanked before any of this, so a route documented as PATCH /agents/{id} is read as documentation.

A genuine exception takes a marker on the line above, written in the comment syntax of the boundary it sits at:

The JSX form is a block comment in expression position because a comment placed inside the text it annotates would become a child node of that text. The reason is mandatory at every boundary: every legitimate case is a claim that the value is something a person reads (a model id, an author-chosen slug, a support reference), and the marker is the only place that claim gets written down.

2.7 A Row Is Named By What It Is, Not What Kind It Is¶

A list exists so a person can pick one row out of it. A row labelled by its category cannot be picked: every row of that category reads identically, and the list degrades into a column of timestamps. The conversation history drawer titled every row from its ConversationKind, so a run that filed twenty work requests showed twenty rows reading "Request work".

The rule is that the row's primary line carries whatever distinguishes this one, and the category, if it earns a place at all, moves to the secondary line beside the timestamp where it informs instead of repeating:

• Derive, do not store. A conversation is named from its opening turn, at read time. A stored title is a second copy of something the transcript already holds, and the two disagree the moment the turn is edited or purged. Deriving it also names every row recorded before the feature existed.
• Resolve it beside the row. Same rule as 2.6: the backend answers it in the response, one query for the whole page, never a per-row lookup the browser makes after the fact.
• Trim, never rewrite. What a person typed is what labels their conversation: whitespace collapses, a Markdown marker goes, a long sentence is cut on a word boundary with an ellipsis. No summarisation and no model.
• Keep the fallback honest. When nothing names the row (a retention purge took the opening turn), the category label is what renders. It was never wrong, only insufficient.

The same shape covers a status that hides a question: a plan waiting on an operator decision renders "Awaiting your decision" beside its raw status, because executing is true and leaves the operator no wiser about what the initiative is actually waiting for.

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/{agentId})
• L3 navigation always creates a browser history entry

3.2 Hover Behaviour¶

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-base library (cmdk port on Base UI Dialog).

Scope behaviour¶

Keyboard navigation¶

4. Animation Language¶

4.1 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 colour-only. Every status indicator includes:

1. Colour: semantic state colour (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), colour + 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 Behaviour 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 colour 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).

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¶