1.0.5.5 Write `/docs/design-system.md` — tokens, primitives, voice/tone, examples

Estimate: 20m · Depends on: 1.0.5.1, 1.0.5.2, 1.0.5.3

Write the canonical design-system reference document at /docs/design-system.md. This file is the single most-referenced artifact in Epic 4's prompt-generation — every design-type Subtask prompt will inject it as context. The quality of this document directly determines the visual consistency of every later UI Subtask.

Why coding-agent-executed (corrected from earlier "human" assignment — see notes.html mistake #21): this is a synthesis document. It pulls together what 1.0.5.1–3 produced (tokens in app/globals.css, primitives in components/ui/* with rich JSDoc, patterns in EmptyState.tsx + ErrorState.tsx, and the architectural spec in docs/DESIGN.md) and recombines them into a single user-manual-style reference. That synthesis is a coding-agent strength: deterministic recombination of existing source files into prose. The earlier "human writes this faster and better" rationale was wrong on every axis (see mistake #21 for the full breakdown).

What you'll do: Write a single Markdown file with these sections in order: (1) Tokens — the color palette as a swatch table, type scale, spacing scale, with code snippets for each; (2) Primitives — each component from 1.0.5.2 with its variant matrix, a code sample, and a one-line "when to use this"; (3) Patterns — empty + error states from 1.0.5.3 with screenshots; (4) Voice & tone — 4-6 principles with do/don't examples (confident not corporate, warm not cute, specific not vague, honest about AI limitations); (5) Don'ts — common anti-patterns to avoid. Total length: ~1500-2000 words. Include screenshots from the specimen page.

Acceptance criteria

• File exists at /docs/design-system.md.
• Has all 5 sections: Tokens, Primitives, Patterns, Voice & tone, Don'ts.
• Tokens section: color swatches as a Markdown table, type scale, spacing scale, with the relevant CSS variable name + Tailwind class for each.
• Primitives section: each of the 9 primitives has its variant matrix + a minimal code sample + a 1-line "when to use this" guideline.
• Patterns section: empty state + error state, with screenshots embedded from the specimen page.
• Voice & tone section: 4-6 numbered principles, each with a do / don't example pair.
• Don'ts section: 5-8 common anti-patterns ("don't introduce new colors outside the palette," "don't put primary buttons in destructive places," etc.).
• Length: 1500-2000 words.
• Tone of the doc itself models the project's voice (confident, specific, honest).
• Linked from README.md in the docs section.

Context refs

• /app/globals.css (from 1.0.5.1) — the actual tokens to document
• /components/ui/* (from 1.0.5.2 and 1.0.5.3) — the primitives + patterns to document
• /app/_tokens/page.tsx — the live specimen page for screenshots
• vision.html principle 13 (design-first) — to inform the "Voice" section