# Bellona Control Room — Design System

> **Status:** Foundational (codified before production UI in `180.C.21`).
> **Scope:** the `apps/bellona/control-room` operator app.
> **Task:** `180.C.31.09` — document the icon, color, typography, and spacing
> system before production UI work begins.

This document is the single reference for the Control Room's visual language. It
is **not** aspirational prose: every value below is the real token shipping in
code. The machine-readable source of truth is
[`apps/bellona/control-room/src/design-system/tokens.ts`](../../../../../apps/bellona/control-room/src/design-system/tokens.ts),
and the theme axes (high-contrast / reduced-motion resolution) live in
[`apps/bellona/control-room/src/a11y/theme.ts`](../../../../../apps/bellona/control-room/src/a11y/theme.ts).
The token snapshot test
(`src/design-system/theme-registry.test.ts`) pins these exact values, so this
doc and the code cannot silently diverge — a change to a token fails that test
until both are updated.

## How the foundation is enforced

| Concern | Token source | Gate / test |
| --- | --- | --- |
| Colour (per theme) | `CONTROL_ROOM_THEME_PALETTES` | `contrast.test.ts` — WCAG 2.1 AA contrast over every text/background pair, per theme |
| Typography | `CONTROL_ROOM_TYPOGRAPHY` | `theme-registry.test.ts` snapshot (font families + role scale + large-text classification) |
| Spacing / radius / icon | `CONTROL_ROOM_SPACING` / `_RADIUS` / `_ICON_SIZE` | `theme-registry.test.ts` snapshot |
| Motion (+ reduced motion) | `CONTROL_ROOM_MOTION_DURATION_MS` | `theme-registry.test.ts` snapshot (full vs. reduced columns) |
| RTL layout | `CONTROL_ROOM_LOGICAL_PROPERTIES` | `rtl-layout.test.ts` — logical edges mirror under `dir="rtl"` |
| Keyboard / focus | `CONTROL_ROOM_FOCUS_RING`, `CONTROL_ROOM_SKIP_LINKS` | `keyboard.test.tsx` — focus-trap cycle, skip-link targeting, focus-ring tokens |
| Empty/loading/error | `design-system/states.tsx` | `states.test.tsx` — error state always surfaces a retry |
| Cost display | `cost-visibility.ts` | `cost-abstraction.test.ts` — single rate card, five dimensions |
| Notifications | `remote-protocol/notification-channels.ts` | `notification-channels.test.ts` — one routing pipeline (12.13 + 28.11) |

---

## 1. Color

The Control Room ships **three themes** — `light` (default), `dark`, and
`high-contrast`. Each is a complete palette over the same closed set of semantic
roles, so a component never hard-codes a hex value; it references a role and the
active theme supplies the colour. Every role pairing is validated against
**WCAG 2.1 AA**: body/metadata/status text ≥ **4.5:1**, and the focus ring and
accent-fill component boundaries ≥ **3:1** (SC 1.4.3 / 1.4.11).

### Roles

| Role | Meaning |
| --- | --- |
| `surface` | Page / app background |
| `surfaceRaised` | Raised panel / card background |
| `surfaceBorder` | Hairline divider (decorative; not contrast-gated) |
| `textPrimary` | Primary body text |
| `textSecondary` | Secondary / metadata text (still ≥ 4.5:1 on `surface`) |
| `accent` | Brand / primary accent (selection rails, progress fills) |
| `onAccent` | Text colour on the accent fill |
| `focusRing` | Keyboard focus indicator |
| `success` / `warning` / `danger` | Status colours |

### Light theme (default operator surface)

| Role | Value | Notes |
| --- | --- | --- |
| `surface` | `#f5f3ed` | The shipping shell background |
| `surfaceRaised` | `#fffdf7` | Cards, inputs |
| `surfaceBorder` | `#d8d0bf` | Hairline only |
| `textPrimary` | `#111814` | ~16.3:1 on `surface` |
| `textSecondary` | `#52584f` | ~6.6:1 on `surface` (darkened after axe flagged the prior `#686f67`) |
| `accent` | `#4f6122` | Olive; ~6.2:1 on `surface` |
| `onAccent` | `#ffffff` | ~6.9:1 on `accent` |
| `focusRing` | `#3c4a1a` | ~8.7:1 on `surface` |
| `success` | `#2f6f56` | |
| `warning` | `#9a5526` | |
| `danger` | `#9a352d` | |

### Dark theme (the live-stream panel palette, promoted)

| Role | Value | Notes |
| --- | --- | --- |
| `surface` | `#151a18` | Matches the stream-stage base |
| `surfaceRaised` | `#1f2723` | |
| `surfaceBorder` | `#3a443d` | Hairline only |
| `textPrimary` | `#f7f3e8` | ~15.9:1 on `surface` |
| `textSecondary` | `#c7ccc2` | ~10.8:1 on `surface` |
| `accent` | `#b6c98a` | |
| `onAccent` | `#111814` | ~10:1 on `accent` |
| `focusRing` | `#cde08f` | ~12.3:1 on `surface` |
| `success` | `#7fd0a8` | |
| `warning` | `#e3b277` | |
| `danger` | `#e98a82` | |

### High-contrast theme (`prefers-contrast: more` / operator toggle)

Pure black/white with a bright amber focus ring — the exact palette the
`.control-room[data-contrast='high']` CSS repaints to. Every text pair is 21:1.

| Role | Value |
| --- | --- |
| `surface` / `surfaceRaised` | `#000000` |
| `surfaceBorder` | `#ffffff` |
| `textPrimary` / `textSecondary` | `#ffffff` |
| `accent` | `#ffffff` |
| `onAccent` | `#000000` |
| `focusRing` | `#ffd400` (~14.7:1 on black) |
| `warning` | `#ffd400` |
| `danger` | `#ff8f8f` |

> **Theme axes.** `light`/`dark` are colour palettes; `high-contrast` and
> `reduced-motion` are independent *axes* resolved by `a11y/theme.ts` from the
> operator preference (`'system' | 'on' | 'off'`) and the OS media queries
> (`prefers-contrast: more`, `prefers-reduced-motion: reduce`). `'system'`
> follows the OS; an explicit toggle overrides it.

---

## 2. Typography

- **Sans family:** `Inter, ui-sans-serif, system-ui, -apple-system,
  BlinkMacSystemFont, 'Segoe UI', sans-serif`
- **Mono family:** `'SFMono-Regular', Consolas, 'Liberation Mono', monospace`
  (command names, payloads, keycaps)
- **Root size:** 16px. The rem scale below converts against it.

| Role | Size (rem) | Weight | Line height | Tracking (em) | WCAG large text? |
| --- | --- | --- | --- | --- | --- |
| `display` | 2.6 | 800 | 1.0 | 0 | yes |
| `heading` | 1.6 | 800 | 1.05 | 0 | yes |
| `subheading` | 1.05 | 800 | 1.1 | 0 | no |
| `body` | 1.0 | 400 | 1.55 | 0 | no |
| `bodyStrong` | 0.92 | 700 | 1.45 | 0 | no |
| `caption` | 0.8 | 600 | 1.35 | 0 | no |
| `eyebrow` | 0.76 | 700 | 1.2 | 0.08 | no |

"WCAG large text" is **computed** from the token (≥ 24px, or ≥ 18.66px bold) by
`isLargeTextRole()`, not hand-tagged — so the contrast gate picks the right
threshold (3:1 vs 4.5:1) automatically.

---

## 3. Spacing & radius

A **4px base step**. Every spacing token is a multiple of it, which keeps
rhythm consistent and makes ad-hoc magic numbers obvious in review.

| Token | px | Token | px |
| --- | --- | --- | --- |
| `xs` | 4 | `xl` | 24 |
| `sm` | 8 | `2xl` | 32 |
| `md` | 12 | `3xl` | 48 |
| `lg` | 16 | | |

| Radius | px |
| --- | --- |
| `sm` | 4 |
| `md` | 8 |
| `lg` | 12 |
| `pill` | 999 |

---

## 4. Icons

- Single **inline-SVG** system on a fixed **24-unit viewBox**
  (`CONTROL_ROOM_ICON_VIEWBOX = 24`).
- Sized by token: `sm` 16px (inline with caption), `md` 20px (default control /
  nav), `lg` 24px (section headers).
- Icons inherit **`currentColor`** (`CONTROL_ROOM_ICON_COLOR_MODE`), so a glyph
  always matches its text colour and therefore inherits the theme's contrast —
  no separate icon-colour audit is needed.

---

## 5. Motion

Durations (ms): `instant` 0, `fast` 120, `base` 180, `slow` 280.

Under **reduced motion** (`data-motion='reduced'` or
`prefers-reduced-motion: reduce`) every duration collapses to ~0.001ms via
`resolveMotionDurationMs(token, true)`, and the shell CSS forces all
`animation`/`transition` durations to ~0 — vestibular-safe by default.

---

## 6. RTL (right-to-left) layout

Layout is authored against **CSS logical properties**
(`margin-inline-start`, `padding-inline-end`, `border-inline-start`,
`inset-inline-start`, logical `start`/`end` text alignment) which mirror
automatically under `dir="rtl"`. The shell root sets `dir` from the active
locale (`directionForLocale`: `ar` → `rtl`, `en-US`/`de-DE` → `ltr`). A
`start`-anchored offset lands on the left in LTR and the right in RTL — see
`resolvePhysicalEdge` / `resolveLogicalInset` and the `rtl-layout.test.ts` flip
test.

---

## 7. Keyboard & focus

- **Focus ring** (`CONTROL_ROOM_FOCUS_RING`): 2px solid outline, 2px offset
  (3px under high contrast). Every interactive control shows it (WCAG 2.4.7).
- **Skip links** (`CONTROL_ROOM_SKIP_LINKS`): the first focusable controls —
  "Skip to main content" (`#control-room-main`) and "Skip to workspace
  navigation" (`#control-room-workspace-nav`) — visually hidden until focused.
- **Modal focus trap** (`useFocusTrap`): focus moves into the dialog on open,
  Tab/Shift+Tab cycle within it (wrapping last↔first), Escape closes it, and
  focus is restored to the trigger on close (WAI-ARIA APG dialog contract).

---

## 8. Empty / loading / error states

Three components (`EmptyState`, `LoadingState`, `ErrorState`) share one prop
contract (`title` + optional `description` + optional `action`) so every view
renders these states identically:

- `EmptyState` — `role="status"`, optional primary action.
- `LoadingState` — `role="status"` + `aria-busy`, deterministic shimmer rows.
- `ErrorState` — `role="alert"`; **always** surfaces a retry button when an
  `onRetry` handler is given (a failed surface is never a dead end).

`resolveViewState({ isLoading, error, itemCount })` picks the state with
precedence `error > loading > empty > ready`.

---

## 9. Cost display

One abstraction — `cost-visibility.ts` — is the single source of truth for the
five spend dimensions: **token**, **gateway-compute**, **turn-bandwidth**,
**render-minute**, **build-minute**. Amounts are priced from one documented rate
card × measured usage; a single locale-aware formatter
(`formatControlRoomCostCurrency`) renders them. No surface re-defines a rate.

---

## 10. Notifications

One pipeline — `remote-protocol/notification-channels.ts` — routes an event to a
single channel set (`webhook`, `slack`, `discord`, `email-digest`,
`in-app-toast`, `desktop`, `mobile-push`). External sinks delegate to the
`180.C.28.11` builders; operator surfaces (`180.C.12.13` desktop + in-app toast +
mobile push) build their payloads from the same event. `dispatchNotification`
is the shared entry point, so 12.13 and 28.11 never fork.
