Eve library

Bellona Control Room — Design System

Guide

Revision 1

On this page

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, 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/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.