Status: Foundational (codified before production UI in
180.C.21). Scope: theapps/bellona/control-roomoperator 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,
and the theme axes (high-contrast / reduced-motion resolution) live in
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/darkare colour palettes;high-contrastandreduced-motionare independent axes resolved bya11y/theme.tsfrom 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:
sm16px (inline with caption),md20px (default control / nav),lg24px (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 anonRetryhandler 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.