--- chain-id: 1 name: Token cascade path: A · Quick / B · Standard / C · Deep status: live prompts: [01, 02, 10] inputs: governance.spec.md + archetype.spec.md (+ brand hex if BYOC) outputs: output/tokens.css (complete — colors, spacing, radii, motion, typography) documented-in: Ch03 — Token Architecture · Ch04 — Colors & WCAG --- # Chain 1 — Token Cascade Generates the full token layer for your design system: color system, spacing scale, radii, motion, and typography. Produces `output/tokens.css` ready for all subsequent component prompts to consume. **When to use:** Always the first chain in any path. Run before any component generation. **Expected runtime:** 10–20 minutes total (Prompt 01: ~8 min, Prompt 02: ~5 min, Prompt 10: ~5 min if run). **Prerequisites:** Choose an archetype (run Prompt 00 if unsure). Have brand hex codes ready if using BYOC. --- ## Step table | Step | Prompt | What lands | Checkpoint | |---|---|---|---| | 1 | `01-tokens-from-spec.md` | `output/tokens.css` — surfaces, borders, text, accent, semantic, spacing, radii, motion | Review palette + WCAG table | | 2 | `02-typography-scale.md` | `output/tokens.css` updated with type scale and font families | Review type scale rendering | | 3 (optional) | `10-layer-3-extraction.md` | `output/tokens-layer-3.css` — component-level tokens from repeated values | Run after components stabilise | --- ## Step-by-step walkthrough ### Step 1 — Token generation (Prompt 01) **What to paste:** 1. `specs/governance.spec.md` — universal quality gates (or load from Project knowledge) 2. `specs/[archetype].spec.md` — your chosen archetype's rules **BYOC branching (Q1 in the prompt meta-header):** - **No brand colors:** answer "No" — the prompt derives the full palette from the archetype spec. Accent color, surface ramps, semantic colors all follow archetype defaults. - **Yes, brand colors:** answer "Yes" and supply: - Primary hex (required): your brand's primary color. The prompt validates it against WCAG and derives light/dark variants via oklch ramp derivation. - Accent hex (optional): if your brand has a secondary accent. If omitted, the prompt derives one from the primary. - The BYOC path is fully integrated into Prompt 01 — no separate 01b paste required. **Font branching (Q2):** - **No brand fonts:** archetype defaults apply (e.g., Inter + JetBrains Mono for Lattice). - **Yes, brand fonts:** provide display family, body family, and optional mono family with Google Fonts or CDN URLs. Note: fonts are applied in Step 2 (Prompt 02), not here. **What to check at the checkpoint:** - WCAG contrast table: every text/background pair must pass AA (4.5:1 for body text, 3:1 for large text and non-text UI). Any FAIL rows must be resolved before proceeding — the prompt flags alternatives. - Dark mode tokens: confirm `:root` (dark or light depending on archetype) and the override block both exist. - Token naming: confirm token names follow the archetype's naming convention (semantic-only for Harbor/Current/Meridian; primitive+semantic for Sentinel/Lattice). **Common failures:** - *Brand color fails WCAG:* The prompt suggests an adjusted shade. Accept it — shipping a contrast failure is a liability, not a style choice. - *Archetype spec paste incomplete:* If output feels generic, re-paste the full spec block. Partial pastes produce partial output. - *BYOC accent clashes with status colors:* Common with red or green brand primaries. The prompt flags this and proposes an offset chrome accent. Accept or override with a different accent hex. --- ### Step 2 — Typography scale (Prompt 02) **What to paste:** - `output/tokens.css` from Step 1 - `specs/governance.spec.md` and `specs/[archetype].spec.md` again (or from Project) **Brand fonts (if Q2 was "Yes" in Step 1):** Provide font URLs here. The prompt adds `@import` declarations and updates `--font-sans`, `--font-display`, `--font-mono` to your brand families. If using variable fonts, provide the `font-variation-settings` axes. **What to check at the checkpoint:** - Search the updated `output/tokens.css` for `--text-` tokens. Confirm the scale matches your archetype: fixed px for Lattice/Sentinel (12px base), fluid `clamp()` for Harbor. - Confirm `--font-sans` is correctly set to your brand font or archetype default. - Confirm `--leading-normal` and `--tracking-normal` are present — required by all component prompts. **Common failures:** - *Brand font 404 at runtime:* Check the CDN URL. Google Fonts URLs require `?display=swap` to prevent render-blocking. - *Scale conflicts with archetype density:* If your brand wants a larger base than the archetype allows (e.g., 16px base in Lattice), flag it as a BYOC override — the prompt will annotate the deviation. --- ### Step 3 — Layer 3 extraction (Prompt 10, optional) **When to run:** After Chain 3 (component generation) is complete and stable. Do not run before components exist. **What it does:** Scans `output/foundation.css`, `output/composite.css`, and `output/patterns.css` for hardcoded values that repeat across 3+ components. Proposes new component-level semantic tokens (e.g., `--button-padding-x`, `--card-radius`) in `output/tokens-layer-3.css`. **What to check:** Each proposed token should be a genuine pattern — a value that appears in multiple components and carries semantic meaning. Reject coincidentally equal values. --- ## Two-paste workflow Every prompt in this chain requires two pastes before running: 1. `specs/governance.spec.md` — universal quality gates 2. `specs/[archetype].spec.md` — archetype-specific rules **In a Claude Project:** load both spec files into Project knowledge once. No paste required per session. --- ## What to do with the output `output/tokens.css` is the foundation every subsequent chain depends on: - **Chain 3** (component generation) reads it to apply correct spacing, color, and typography - **Chain 7** (spec page) uses it for the live token browser and WCAG contrast table - **Chain 9** (greenfield end-to-end) runs this chain as its first two steps automatically Keep `tokens.css` in version control. When the spec evolves, re-run this chain and run Chain 4 (drift audit) against any components that may have inherited old values. --- *Chain 1 · Token Cascade · Design Systems That Build Themselves · © 2026 Ishdeep S Sahni*