# COLOUR_SYSTEM.md

## 1. Palette philosophy

Near-monochrome surfaces + **one** accent ("aurora" teal-green — a nod to Norway without cliché flags/fjords) + **one** functional secondary (amber, status-only). The accent behaves like a **status LED**: it marks liveness, focus, and action — it is never decoration or large fills.

## 2. Core tokens

### Dark theme (design lead)
| Token | Value | Contrast vs surface-0 | Use |
|---|---|---|---|
| `surface-0` | `#0B0E14` | — | Page bg (blue-black, not pure black) |
| `surface-1` | `#11151D` | — | Cards |
| `surface-2` | `#171C26` | — | Nested panels, TL;DR |
| `ink` | `#E8ECF2` | 15.4:1 | Headings, body |
| `ink-muted` | `#9AA4B2` | 7.1:1 | Secondary text, captions |
| `ink-faint` | `#5C6675` | 3.4:1 | Disabled, decorative only (never body) |
| `border` | `#E8ECF2` @ 8% | — | Hairlines |
| `accent` | `#3ECFAE` | 9.8:1 | Links, primary buttons (dark text on it), status dots, trace motif, focus rings |
| `accent-ink` | `#062A22` | 12:1 on accent | Text on accent fills |
| `amber` | `#E5A93D` | 8.3:1 | `IN DEVELOPMENT` chips, form warnings only |
| `danger` | `#E5606B` | 5.6:1 | Form errors only |

### Light theme
| Token | Value | Contrast vs surface-0 | Use |
|---|---|---|---|
| `surface-0` | `#FAFAF8` | — | Warm paper white |
| `surface-1` | `#FFFFFF` | — | Cards |
| `surface-2` | `#F1F2EF` | — | Nested panels |
| `ink` | `#171A20` | 15.9:1 | Text |
| `ink-muted` | `#555E6B` | 6.8:1 | Secondary |
| `border` | `#171A20` @ 10% | — | Hairlines |
| `accent` | `#0E8C72` | 4.9:1 | Links, buttons (white text: 5.1:1), focus |
| `amber` | `#8A6114` | 5.6:1 | Status text (paired w/ `#F5E5C2` chip bg) |
| `danger` | `#B3323E` | 6.2:1 | Errors |

**Note:** the accent is *perceptually the same identity* in both themes but shifted per theme to hold WCAG AA (dark uses the luminous `#3ECFAE`; light uses the deepened `#0E8C72`). This is deliberate — never reuse the dark accent on white (2.1:1, fails).

## 3. Usage rules

1. **Accent budget:** ≤ 3 accent moments per viewport (e.g. hero: trace line + primary CTA + one chip dot). If a screen feels flat, fix hierarchy with type/spacing — not more accent.
2. **Large fills:** accent may fill only buttons and chips; never section backgrounds or headings-as-blocks.
3. **Text on accent:** always `accent-ink`/white per table; never accent-on-accent.
4. **Status semantics (fixed):** accent dot = active/live · amber dot = in development · muted dot = archived. Consistent across chips, timeline, project cards.
5. **Charts/diagrams:** surfaces + border + ink-muted, accent for the *one* flow being explained, amber for external systems (e.g. Gmail API node). Max 4 hues in any diagram.
6. **Duotone photo treatment (dark):** shadows → `#0B0E14`, highlights → warm neutral; accent never tints skin.
7. **Never colour-only meaning:** every status pairs dot + text label; errors pair colour + icon + message.

## 4. Gradients

Exactly one permitted gradient: hero background halo — radial, accent @ 6% → transparent, anchored behind the trace motif. Everything else flat. (The Stripe lesson: one identity moment, not a gradient system.)

## 5. Accessibility audit summary

- All body/secondary text ≥ 4.5:1 in both themes (see tables).
- UI components/borders on interactive elements ≥ 3:1 against adjacent colours.
- Focus ring `accent` at 2px passes 3:1 against both surface-0 values.
- `ink-faint` is documented decorative-only. High-contrast/forced-colors mode: dot-grid and halo disabled, hairlines → CanvasText.