diff --git a/docs/03-design/design-tokens.md b/docs/03-design/design-tokens.md
new file mode 100644
index 0000000..89f130e
--- /dev/null
+++ b/docs/03-design/design-tokens.md
@@ -0,0 +1,113 @@
+# Design tokens
+
+The complete token table used across mockups and (eventually) production console.
+
+## Color palette
+
+```css
+:root {
+  /* Backgrounds */
+  --bg:        #000000;
+  --cell:      #0A0E12;
+  --cell-2:    #141a20;
+  --cell-3:    #1d2630;
+
+  /* Primary navigation chrome */
+  --ink:       #66CCFF;   /* dominant cyan */
+  --ink-2:     #99CCFF;   /* secondary text/hint */
+  --bar:       #66CCFF;
+  --bar-dim:   #224466;
+
+  /* Domain colors (per VLAN / per AI type) */
+  --cam:       #6699FF;   /* cameras / VLAN-10 — royal blue */
+  --hai:       #CC99CC;   /* compute / VLAN-20 — mauve */
+  --iot:       #99CC99;   /* health / OK — green */
+  --mgmt:      #CCCC99;   /* management / VLAN-30 — olive */
+  --wan:       #66CCCC;   /* WAN / external — turquoise */
+
+  /* Semantic */
+  --warn:      #99FFFF;   /* warnings — bright cyan */
+
+  /* Brand (isolated from semantic UI) */
+  --brand:     #9FCB3A;   /* Blocao green — logo only */
+
+  /* Text on ink-colored backgrounds */
+  --hai-text:  #000;
+}
+```
+
+## Typography
+
+| Use | Font | Weight | Size range |
+|---|---|---|---|
+| Primary sans (titles, buttons, labels) | Antonio | 400, 500, 600, 700 | 9-26px |
+| Mono (data, timestamps, code, IDs) | JetBrains Mono | 400, 500, 700 | 8-13px |
+
+Both fonts loaded from Google Fonts. Antonio chosen for its compressed letterforms (LCARS-like), JetBrains Mono for its clarity at small sizes.
+
+## Spacing
+
+LCARS-style asymmetric padding. Common values:
+
+- Pill height: 36-40px.
+- Card border-radius: 12-14px (asymmetric corners on chrome elements: `border-radius: 0 28px 28px 0` etc).
+- Content padding: 12-18px inside cards.
+- Section gap: 6-12px.
+
+## Border treatments
+
+- **Chrome elements** (rail, topbar): solid color blocks with asymmetric rounded corners.
+- **Content cards**: rounded corners (12-14px), border-left accent in domain color.
+- **Dotted dividers**: `border-bottom: 1px dashed var(--cell-3)` for sections within a card.
+
+## Animation patterns
+
+- **Pulse** (status dots, "live" indicators): 2s ease-in-out, opacity 0.4 → 1.
+- **Flow lines** (SCADA connections): `stroke-dasharray: 4 8; animation: 1.6s linear` shifting `stroke-dashoffset`.
+- **Cursor blink** (input fields): 1.1s.
+- **Panel transitions**: avoid. View switches are instant.
+
+## Iconography
+
+Symbols used as text glyphs (no icon font, no SVG sprite):
+
+- `▸` / `◂` — section chevrons, "open"/"close".
+- `◆` — emphasis, brand moment, identified marker.
+- `●` / `◯` — running / paused indicators.
+- `✓` / `✗` — pass / fail.
+- `⊕` — secure / encrypted.
+- `↑` / `↓` — bridge direction (out / in).
+- `↑↑` / `↓↓` — fast-forward / rewind in player.
+
+Custom SVG only for: Blocao logo (the blockhouse mark), the SCADA component renderings in SYNOPSIS.
+
+## Domain color usage
+
+| Color | Use cases |
+|---|---|
+| `--ink` (cyan) | Default text, active rail pill, chrome accents |
+| `--cam` (royal blue) | CAMS view, VLAN-10 references, camera-related events |
+| `--hai` (mauve) | FRIGATE view, Cell device, edge AI inference |
+| `--iot` (green) | OK status, health passing, "good" states |
+| `--mgmt` (olive) | GITOPS view, VLAN-30, system management, deferred topics |
+| `--wan` (turquoise) | WAN view, external connections, hub references |
+| `--warn` (bright cyan) | Warnings, alerts, attention-needed |
+| `--brand` (lime green) | Logo, brand chip, brand moments only |
+
+Pattern: when navigating to a view, the chrome of the topbar shifts to that domain's color. CAMS makes the topbar accent royal blue; FRIGATE makes it mauve. Reinforces "what mode am I in".
+
+## Accessibility considerations
+
+- All foreground text against `--bg` or `--cell` meets WCAG AA at the size used.
+- Status is never communicated by color alone — always paired with shape (✓/✗) or text label.
+- Animations respect `prefers-reduced-motion: reduce` (currently CSS-only; full implementation in production).
+
+## Tooling
+
+Tokens will be exported to:
+
+- `tokens.css` — CSS custom properties (current).
+- `tokens.json` — for design tools and JS imports (planned).
+- `tokens.figma.json` — for Figma library sync (planned).
+
+These live in `packages/design-tokens/` of the future code monorepo.