# Design tokens application

How a print-ready HTML artefact consumes the project's design-tokens spec.

## Source of truth

Project keeps `<project-site>/.docs/design-tokens.md` as the canonical tokens spec. Three tiers:

- **Tier 1 — Global tokens.** Raw hex values (e.g. `--teal-900: #0E1418`). Never reference directly from a component.
- **Tier 2 — Semantic aliases.** Maps Tier 1 to roles (e.g. `--text-primary: var(--teal-900)`).
- **Tier 3 — Component tokens.** Per-component variables that reference Tier 2 aliases.

Components consume Tier 2 or Tier 3, never Tier 1 directly. This isolation lets a token-value update propagate without touching component CSS.

## Premium register defaults (the reference project)

| Token | Value | Role |
|---|---|---|
| `--teal-900` | `#0E1418` | Primary ink |
| `--teal-950` | `#06080A` | Deepest dark surface |
| `--teal-700` | `#2A3036` | Secondary ink |
| `--gold-300` | `#C9B07A` | Champagne flourish |
| `--gold-500` | `#A4884C` | Antique gold rule |
| `--gold-700` | `#7A6235` | Bronze accent |
| `--paper-0` | `#FFFFFF` | Pure white (elevated cards) |
| `--paper-25` | `#FBFAF6` | Near-white page surface (default) |
| `--paper-50` | `#F4EFE5` | One step warmer |
| `--paper-100` | `#ECF1F2` | Cool mist (callout / tinted-band surface) |
| `--slate-400` | `#8A8E96` | Tertiary text |
| `--slate-600` | `#5C6470` | Secondary text |
| `--rule-fine` | `#E2D5BD` | Champagne sand divider |

## Tier 2 aliases

```css
--surface-page:     var(--paper-25);    /* default page background */
--surface-elevated: var(--paper-0);     /* cards, panels */
--surface-warm:     var(--paper-100);   /* tinted band; in premium register this is cool mist */
--surface-deep:     var(--teal-950);    /* full-bleed dark sections */
--text-primary:     var(--teal-900);
--text-secondary:   var(--slate-600);
--text-tertiary:    var(--slate-400);
--text-on-deep:     var(--paper-25);
--text-accent:      var(--gold-700);
--text-accent-on-deep: var(--gold-300);
--border-fine:      var(--rule-fine);
--border-accent:    var(--gold-500);
--font-display:     var(--serif);       /* Cormorant Garamond */
--font-editorial:   var(--body-serif);  /* Lora */
--font-ui:          var(--sans);        /* Inter */
```

## Hard rules

- **Never hard-code a hex value inside component CSS.** Audit by `grep -E '#[0-9A-Fa-f]{3,6}' <artefact>/index.html` — every match must be inside the `:root` block.
- **Page background is `--paper-25`, never pure `#FFFFFF`.** Pure white is reserved for elevated cards (`--surface-elevated`).
- **Gold is reserved for accent, never primary CTA.** Primary action buttons sit on `--teal-900` with `--gold-700` hover.
- **All-caps eyebrows always use `--font-ui` + letter-spacing ≥ 0.24em.**
- **Cool mist (`--paper-100 #ECF1F2`) replaced warm cream (`#EFE7D8`) in the premium register.** Tinted bands / callouts read as pale steely blue, not light brown.

## When the user says "I don't like this colour"

The pattern from the reference project: the user identifies a token whose value is off. The fix is:

1. Update the value in `<project-site>/.docs/design-tokens.md` Tier 1 table.
2. Mirror the value in every consuming artefact's `:root` block (business plan HTML, prospectus HTML, deck HTML).
3. Re-render PDFs.

Keep the token NAMES stable. Updating values is non-breaking; renaming is.

## Logo assets

Project ships icon variants in `<project-site>/public/<brand>/`:

- White-mono variant for dark backgrounds (cover, backpage).
- Dark variant for light content pages.
- Colour variant for general use.

Copy the needed variants into the artefact directory (e.g. `html/business-plan/logo-light.png`) for relative-path reference inside the HTML.
