feat: chapters 17–25 — finish Part 2 + Part 3 case studies

[mehdibha]

Completes the curriculum: chapters 17–25 (9 chapters, ~49 new playgrounds). The diff against main is exactly these chapters — 1–16 already landed via #3.

Chapters

Part 2 — Building a color system (finished)

• 17 · semantic-tokens — tiers, naming grammar, the pairing promise, mode aliasing
• 18 · states-alpha-status — states as ramp-step vs alpha overlay, focus/disabled, status families
• 19 · data-viz-palettes — categorical/sequential/diverging; the ramp is wrong for all but sequential; CVD + the ~8-hue ceiling
• 20 · shipping-color — baked hex vs computed CSS (color-mix / relative color / light-dark), priced on support/bytes/theming/auditability

Part 3 — How the greats did it (case studies)

• 21 · radix-colors — the 12-job contract, step-9 solid, separate dark design, alpha
• 22 · tailwind — OKLCH palette + @theme; numeric names, no pairing floor
• 23 · material-hct — Tone = L* as the contrast lever, tone-delta pairing, contrast levels
• 24 · spectrum-leonardo — contrast as input; modes for free; which meter's flaws you bake in
• 25 · geist — capstone: designed vs generated, ending on the rewrite-spec pointer

Each chapter keeps the house shape: flagship Playground + inline Demos, an engine "decision this unlocks" / "steal — and reject" section, Check-yourself questions, and primary-source Further reading.

How they were drafted

Each chapter ran through a multi-agent workflow: web research → 3 independent Opus writers → synthesis → 3 adversarial reviewers (facts / code / pedagogy) → revision. The review pass caught real errors before commit (e.g. a fabricated Leonardo wcag2|wcag3 API, an inverted tone-gap-contrast claim, an Okabe–Ito misattribution).

Verification

• pnpm typecheck clean; pnpm build prerenders all 26 pages (home + 25 chapters).
• pnpm check (oxlint + oxfmt) clean.
• Dev-server hydration checked on all 9 chapters — zero console errors; flagships compute live (culori runs client-side).
• Fixed a dev-only crash: ch18's Switch hit the "Invalid hook call" optimizeDeps gotcha (build passed, dev crashed on first visit) — added react-aria-components/Switch + Label to optimizeDeps.

Review notes (publish gate)

These are drafted and marked published on the branch, but not yet through the human publish gate — questions → revisions, voice pass, and answering each Check-yourself. The case studies especially warrant a factual re-read against primary sources; a few workflow runs lost a writer to output-size limits, so scrutiny varied. Merge when you're satisfied, not before.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dotui-colors	Ready	Preview, Comment	Jul 11, 2026 3:56pm