Brand Identity & UX Design System¶

This page carries two things: the words SynthOrg uses about itself, which every other page inherits, and the visual system the dashboard is built from. The voice comes first, because a page can be accurate about the code and still be wrong about the product.

What SynthOrg Is¶

Where one agent stops, an organisation starts. SynthOrg is a synthetic one: it staffs the roles, splits the work into jobs that stand alone, builds them in parallel, each in its own workspace, and sends each one to a reviewer who had no hand in it. On your hardware, against models you choose.

The order is load-bearing: problem, then mechanism, then where it runs. Never lead with the mechanism. The product name carries the answer rather than the problem, so the opening line has to supply what that answer is an answer to, and the line after it says what a synthetic organisation does rather than leaving a reader to infer it from a name they have just met.

The binding constraint is decomposition quality, not agent supply. The parallel tree is not a speed feature and must never be sold as one. A single agent does one thing at a time, so the twentieth damages the first; a tree does not have that failure mode, provided the merges hold. Making the parts genuinely independent is the hard problem.

The Three Claims, and How Far Each Goes¶

It fans out. Work is decomposed recursively into units that can be built independently, built concurrently, each in its own git worktree, and assembled bottom-up. Never state a size the system handles: the decomposition ceiling is being measured and has no answer yet. The isolation to name is the workspace, never a container per part: the shipped sandbox default is subprocess (tools/sandbox/sandboxing_config.py), and where an operator selects Docker a container belongs to an agent and is reused across every command and task that agent runs (tools/sandbox/lifecycle/config.py).

Each part is checked by something that did not write it. The reviewer is structurally prevented from being the author, in the service layer, the model binding, and a database constraint. The claim stops there. It does not mean the work is correct, and nothing binds the two to different model families, so a blind spot they share is one the pair cannot see. The narrow version is the true one and it is worth more than the broad one.

It runs on your hardware. Self-hosted and provider-agnostic, local models included, with no SynthOrg service in the path. State it as a property, never as a boast.

What Is Not Sold¶

Organisational realism as the reason the output is good. That position is closed (see Research and Prior Art). Roles, departments, staffing and the approval gate are shipped, working machinery, pages documenting them must stay accurate, and the vocabulary is the product's own, so a headline may use it. What no page may do is argue that simulating an organisation is why the work comes out well, or describe the org as something to watch rather than something that decides who builds and who checks.

Voice Rules¶

A page that breaks one of these is wrong, not merely off-tone.

House rules on every word: British English; no em-dashes; current state only; no unverified number; and no LLM vendor privileged where a provider or model is configured, dispatched to or illustrated (example-provider, example-{basic,capable,expert}-001).

Design Direction¶

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

Why this direction: warmth makes an operations dashboard approachable without losing professionalism. Tying colour 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 colours dominate the visual hierarchy. Orange and amber mean "attention needed", not "this is SynthOrg".

What was rejected and why: a cool blue-cyan palette (data centre aesthetic) was too generic to tell apart from any other monitoring dashboard. A neutral grey palette (no hue) lacked enough identity to be recognisable. A high-energy violet/purple palette was visually fatiguing over a long working session. Each scored well on individual criteria and failed the combination of distinct identity plus sustained usability.

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

Colour System¶

Semantic Colour Tokens¶

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

Dynamic Colour Assignment¶

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

This ensures operators instantly understand system state from colours 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 Colour Palette¶

Every colour in the dashboard resolves through a --so-* custom property declared in web/src/styles/design-tokens.css. Warm Ops is :root; each other palette is a class on <html> that overrides only the properties it changes. To add one:

1. Add a .theme-<name> block to design-tokens.css overriding the --so-* properties that differ from :root
2. Add <name> to the ColorPalette union and the COLOR_PALETTES array in web/src/stores/theme.ts, which derives the class list from it
3. Give it a label in the THEME_META.PALETTE map in web/src/components/layout/AppLayout.tsx, which is what the command palette and theme popover show

No component code changes. The five palettes (Warm Ops, Ice Station, Stealth, Signal, Neon) each override the accent pair and a handful of surfaces; everything else inherits from :root.

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 colours.

Self-Hosted Fonts¶

All fonts are bundled via @fontsource packages. No external CDN (Google Fonts) dependencies. This ensures:

• No privacy concerns 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 colours.

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¶

Same shape as a palette. Balanced is :root; each other level is a .density-<name> class in design-tokens.css overriding the --so-density-* properties, registered in the Density union and DENSITIES array in web/src/stores/theme.ts and labelled in THEME_META.DENSITY. Components consume the density tokens (p-card, gap-section-gap, gap-grid-gap), so no component changes.

Animation¶

Animation is an independent user preference, controlling motion intensity.

Each profile resolves to one config in useAnimationPreset(): a primary transition (spring, used for modals, panels and card interactions, which need not be a spring), a tween for hover and colour changes, a stagger delay, and whether layout animations run at all. Components read the hook rather than reaching into lib/motion.ts directly.

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

Page transitions are deliberately outside this axis. Every profile gets the same short opacity cross-fade, because on a dense dashboard any horizontal slide reads as a layout shift rather than a transition.

Sidebar¶

Sidebar mode is an independent user preference.

Rail is the only mode that is always icon-only; collapsible also hides labels at full desktop width whenever the user collapses it. The desktop-sm breakpoint pins every mode collapsed regardless of preference, so compact and persistent render the icon rail there too, at the collapsed width rather than their own. Above that breakpoint the two keep labels and differ by column width alone; neither renders the collapse toggle, which belongs to collapsible. Notification badges render in every mode that shows labels, not only persistent.

Persistence¶

Every appearance preference is backend-owned. The five theme axes live in the appearance settings namespace and the sidebar collapse state in dashboard.sidebar_collapsed; the stores hydrate from the API on mount and write each change straight back. The stores hold the hydrated values in memory for the session and nothing else keeps a copy, because the dashboard is a pure API consumer and a preference persisted only in the browser is a preference no other client can see.

Theme Architecture¶

Independent Axes¶

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

Colour 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 colours + dense layout + IBM Plex fonts + minimal animation + compact sidebar" without any custom theme code.

Implementation Pattern¶

flowchart TD
    TS["Theme store (Zustand, hydrated from the appearance settings namespace)"]
    TS --> P1["Applies one class per axis to the html element (theme-*, density-*, typography-*, animation-*, sidebar-*)"]
    P1 --> P2["Each class overrides the --so-* custom properties it changes; the defaults live on :root"]
    P2 --> P3["global.css maps --so-* onto Tailwind theme variables with @theme inline"]
    P3 --> P4["Components use the resulting utilities (text-accent, bg-card, p-card, gap-section-gap)"]
    TS --> P5["Animation preference is read through useAnimationPreset; sidebar mode selects the sidebar rendering"]

Because the mapping is @theme inline, the compiled utilities resolve as var(--so-*) references rather than baked values, which is what lets a class swap on <html> restyle the whole dashboard at runtime.

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; }
}

An unlayered reset is hard to diagnose because the utilities still appear in the generated CSS and simply have no visual effect.

Dark Mode¶

Dark mode only. There is no light mode. All colour tokens assume dark backgrounds, and WCAG AA contrast ratios are validated against the dark card and 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, 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), @storybook/addon-a11y (WCAG testing) and msw-storybook-addon. Essentials (backgrounds, controls, viewport, actions) and interactions are built into core
• Backgrounds: initialGlobals.backgrounds.value = 'dark' selects the single backgrounds.options.dark entry, whose value is the same #0a0a12 the --so-bg-base token carries, so stories render against the real brand 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, registered in preview.tsx with an explicit worker whose onUnhandledRequest is bypass, so a story that mocks nothing stays silent instead of warning on every request. 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 the 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¶

Conversational Components¶

Used by the Chat surface and the other places the organisation speaks.

Utility Functions¶

Design System Hooks¶

Types¶

Every enum above sourced from api/types/enums is re-exported from web/src/api/types/enum-values.gen.ts, generated from the backend's own API surface by scripts/generate_dto_types_ts.py and held in step by a pre-push drift check. A value is added by changing the backend and regenerating, never by editing the generated file. The types sourced from utils/ are UI-local and have no backend counterpart, so they are hand-written and generated from nothing.

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 behaviour 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 colours/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¶