# Task 02 — Design token layer

**Agent**: `design-system-keeper` · **Model**: Gemini (long context + visual
judgement) **Depends on**: 01 · **Parallel with**: 03, 04 · **Blocks**: 07
**Worktree**: `.agents/scripts/worktree.sh start 02 tokens`

## Goal

One value per token, a named type scale, five breakpoints — and photographic
proof the site looks the same.

## Read first

`.agents/context/design-system.md`. It documents two traps you will otherwise
walk into.

## Scope

`src/styles/tokens.css`, `src/styles/base.css`,
`.agents/scripts/check-tokens.mjs`. You are the only writer of these.

## The two decisions to surface

1. **Three palettes → one.** `--ink` is `#172f42` / `#122534` / `#173044`;
   `--paper`, `--muted`, `--line`, `--gold` likewise. Most deltas are
   sub-perceptual — canonicalize. **`--blue` (`#527f9f` vs `#215675`) is visibly
   different**: screenshot both, get a human decision, record it here.
2. **The fonts have never rendered.** `styles.css:1` has a malformed
   `@font-face` whose `src:` points at a Google Fonts _stylesheet_. Manrope and
   DM Mono have always fallen back to Arial and generic monospace. Default:
   delete the dead rule, declare what actually renders. Self-hosting the real
   fonts is a **redesign** and needs sign-off.

## Steps

1. Run the extraction script in `.agents/skills/design-tokens/SKILL.md`.
2. Capture baseline screenshots: 10 routes × {560, 800, 1100, 1600} **plus the
   eight breakpoint widths you are removing** (520, 530, 600, 620, 720, 850,
   880, 900).
3. Write `tokens.css`: one value per semantic name, `--step-*` type scale
   replacing the 14 ad-hoc `clamp()` triples, five `--bp-*` widths.
4. Re-capture. Compare. Explain every visible difference.

## Done when

- [ ] Extraction prints exactly one value per token
- [ ] `node .agents/scripts/check-tokens.mjs` passes on `src/`
- [ ] Before/after screenshots attached at all twelve widths
- [ ] The `--blue` decision and the font decision are written down here

## Do not

- Do not add a webfont. **(Reversed 2026-09-05 — see Decisions.)**
- Do not rename tokens to numeric scales (`--color-neutral-900`).
- Do not convert the `gap:1px` over a coloured parent trick into `border` — it
  is deliberate house style and appears everywhere.

## Decisions

- **Palette Consolidation:** The three drifted palettes were canonicalized into
  one. For `--blue`, `#527f9f` (from styles.css) was chosen over `#215675` (from
  chapters.css) to unify the look.
- **Fonts (superseded 2026-09-05):** task 02 recorded "delete the dead rule,
  fall back to `Arial, sans-serif` / `ui-monospace, monospace`, zero visual
  change", and deferred even that deletion to "future component tasks", which
  never picked it up. The human has since chosen the opposite: Manrope and DM
  Mono are now self-hosted in `public/fonts/` and really render. The "Do not add
  a webfont" line above no longer applies.