---
name: design-tokens
description:
  Extract, name, and enforce the design token layer for the ai-for-dummies site.
  Use when touching any colour, font size, spacing value, or breakpoint, when
  consolidating the three drifted palettes, or when a check-tokens failure needs
  resolving.
---

# Design tokens

## Before anything

Read [`../../context/design-system.md`](../../context/design-system.md). This
site has **three drifting palettes** and a **broken `@font-face`**. Both are
traps. If you have not read that file, you will "preserve the styles" by copying
a bug.

## Extracting

```bash
python3 - <<'PY'
import re
files=['styles.css','chapters.css','landing.css','rules/styles.css','skills/styles.css',
       'skills-review/styles.css','hands-on/starter/styles.css','hands-on/rules/styles.css']
seen={}
for f in files:
    for m in re.finditer(r'--([a-z-]+):\s*([^;}]+)', open(f).read()):
        seen.setdefault(m.group(1),{}).setdefault(m.group(2).strip(),[]).append(f)
for k,v in sorted(seen.items()):
    print(f"--{k}:")
    for val,fs in v.items(): print(f"    {val:12} <- {', '.join(fs)}")
PY
```

Re-run this after any consolidation. Every token should print exactly one value.

## Consolidating a drifted token

1. List every value and where it is used (above).
2. Compute the perceptual delta. Sub-perceptual (a few units per channel) →
   canonicalize freely. Visible (`--blue`: `#527f9f` vs `#215675`) → screenshot
   both, get a human decision, record it in the task file.
3. Pick the canonical value. Prefer the one used on the most-visited surface.
4. Replace, then screenshot every affected page at 560/800/1100/1600 px.
5. Attach before/after images to the task report. "It looked fine to me" is not
   evidence.

## Naming

Semantic, matching the existing vocabulary — `--ink`, `--paper`, `--muted`,
`--line`, `--accent`, `--gold`, `--blue`, `--deep`. Never numeric scales. New
surfaces extend semantically: `--surface-lab`, `--ink-inverse`.

## Type scale and breakpoints

Collapse the 14 ad-hoc `clamp()` triples to named steps and the 16 breakpoints
to five, per [`../../rules/theming.md`](../../rules/theming.md). When collapsing
a breakpoint, **screenshot at the old value** — that is where the regression is.

## Enforcing

```bash
node .agents/scripts/check-tokens.mjs   # fails on raw hex outside tokens.css
```

Wire it into `pnpm run verify`. A rule nobody checks is a suggestion.

## The font decision

Do not self-host Manrope/DM Mono as part of a refactor task. The intended fonts
have never rendered, so adopting them is a visual redesign. Default to matching
what renders today (Arial / generic monospace) and delete the dead `@font-face`.
If a human wants the real fonts, that is its own task with its own screenshots.