# Chain Runner — Design Systems That Build Themselves

> Paste this file into **Claude Code** (recommended — file-write access enables auto-save) or Claude.ai (manual save instructions will be provided at each step).
>
> The chain runner orchestrates the full design system generation pipeline via Q&A. It detects your current state, collects all branching decisions upfront, runs prompts in sequence, saves every output, and pauses for your review at each checkpoint.
>
> **Prefer to run one prompt at a time?** See `README.md` → Ad-hoc Mode. Each individual prompt in `prompts/` is self-contained.

---

## STEP −1 — CONFIGURE A CLAUDE PROJECT (optional but recommended)

If you plan to run this chain across multiple sessions, or work on this design system repeatedly, configure a Claude Project before starting. This eliminates repasting the spec at every prompt step.

**Setup (one-time, ~10 minutes):**
1. Go to claude.ai → Projects → New Project
2. Name it after your product or design system
3. In Project Settings → Knowledge, upload:
   - `specs/governance.spec.md`
   - `specs/[archetype].spec.md` (after Q1 below confirms your archetype)
   - `output/tokens.css` (once generated at Step 1)
4. Paste the Project setup prompt from Ch17 into Project Instructions

**If running ad-hoc or in Claude Code:** Skip this step. The chain runner will include paste reminders at each prompt step.

> **After completing this step:** proceed to STEP 0.

---

## STEP 0 — DETECT ENVIRONMENT

First, check whether you have file-write access to the project folder.

**If Claude Code / IDE context:** You can read and write files directly. Confirm the project root and proceed. All outputs will be saved automatically.

**If Claude.ai chat:** You cannot write files directly. At each save point, I will provide clear copy-paste instructions with the exact filename and path.

---

## STEP 1 — ASSESS CHAIN STATE

Scan the `output/` folder (relative to this file's location). Report what exists and what the current chain state is:

| File | Prompt that created it | State |
|---|---|---|
| `output/chain-state.md` | (chain runner) | Resume log |
| `output/tokens.css` | Prompt 1 / 1b | Done if present |
| `output/tokens.css` (updated) | Prompt 2 | Done if typography tokens present |
| `output/foundation.css` | Prompt 03 | Done if present |
| `output/composite.css` | Prompt 04 | Done if present |
| `output/patterns.css` | Prompt 05 | Done if present |
| `output/chrome.css` | Nav/Header/Footer prompt | Done if present |
| `output/domain.css` | Prompt 07 | Done if present |
| `output/design-system-spec.html` | Prompt 08 | Done if present |

Also read `output/chain-state.md` if it exists — it contains previous session decisions (archetype, BYOC, fonts, framework) that carry forward automatically.

Report the assessment to the user before asking questions. Example:
> "Found: `output/tokens.css` ✓, `output/foundation.css` ✓. Missing: `output/composite.css` and beyond. Resuming from Prompt 04 — Composite components."

If nothing exists: "Starting fresh. Let me ask a few questions before we begin."

---

## STEP 2 — GATHER INPUTS UPFRONT

Ask these questions **once** before any prompt runs. Store answers — they carry forward through every subsequent prompt automatically.

```
Q1. Which archetype?
    Harbor (editorial/marketing) / Sentinel (enterprise/product) /
    Current (mobile-first consumer) / Lattice (data-dense terminal) /
    Meridian (long-form reading/docs)

    If unsure, say "help me pick" — I'll run the archetype-from-adjectives
    prompt first (takes ~2 min, asks for 3 brand adjectives).

Q2. Brand colors (BYOC)?
    Do you have specific brand colors to honour?
    - No → palette interpreted from archetype spec + adjectives
    - Yes → provide:
        Primary hex: [e.g. #FF5733]
        Accent hex (optional): [e.g. #1ABC9C]
    I will validate these against WCAG before generating tokens.

Q3. Brand fonts?
    Do you have brand fonts to substitute for the archetype defaults?
    - No → archetype defaults apply
    - Yes → provide:
        Display family: [name + Google Fonts / CDN URL if web-font]
        Body family: [name + URL]
        Mono family (optional): [name + URL]
    Note: fonts are applied in Prompt 2, not Prompt 1.

Q4. Framework target?
    What will consume the generated CSS?
    React / Vue / Svelte / Web components / Plain CSS (no framework)

Q5. Component scope?
    How far through the chain do you want to run this session?
    A. Foundation only (tokens + Prompt 03)
    B. Foundation + composite (+ Prompt 04)
    C. Foundation + composite + patterns (+ Prompt 05)
    D. Full chain including chrome, domain components, spec page
    E. Tokens only (Prompts 1 + 2) — ship code later

Q6. Domain components? (skip if scope is A–C)
    If D: list up to 5 product-specific components with a 1–2 sentence
    description each (e.g. "Policy editor with rule grid and approval
    timeline"). These go to Prompt 07.
```

After answers: summarise the full run plan and ask for confirmation before generating anything.

Example summary:
> "Plan: Sentinel archetype · BYOC primary #1B2A4A · GT America body font · React · Full chain. Will generate: tokens.css → foundation.css → composite.css → patterns.css → domain.css → design-system-spec.html. Ready to start?"

---

## STEP 3 — SEQUENTIAL EXECUTION WITH CHECKPOINTS

Run prompts in the order defined by the chain. At each checkpoint, pause and report:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHECKPOINT — [Prompt name] complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Saved: output/[filename]
Summary: [1–2 sentence summary of what was generated]

Next: Prompt [N+1] — [name]
[Brief description of what it will produce]

Options:
  "next"    → continue
  "review"  → show me the file contents before continuing
  "preview" → generate HTML preview of output so far
  "skip"    → skip this step and continue
  "stop"    → end session (progress is saved; resume anytime)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Chain order (Path A · Quick / Greenfield)

| # | Prompt | Output file | Notes |
|---|---|---|---|
| 0 | archetype-from-adjectives | (decision only) | Skip if archetype already confirmed in Q1 |
| 1 | 01-tokens-from-spec | output/tokens.css | BYOC activated automatically if Q2 = yes |
| 2 | 02-typography-scale | output/tokens.css (updated) | Brand fonts from Q3 applied here |
| 3 | 03-foundation-components | output/foundation.css | |
| 4 | 04-composite-components | output/composite.css | |
| 5 | 05-pattern-components | output/patterns.css | |
| 6 | 06-chrome | output/chrome.css | |
| 7 | 07-domain-components | output/domain.css | Skip if scope A–C |
| 8 | 08-spec-page | output/design-system-spec.html | Assembles all CSS into rendered page |
| 9 | 10-layer-3-extraction | output/tokens-layer-3.css | Run after components stabilise |

### For Path B (Figma MCP extract)

Replace step 1 with: read Figma file via Dev Mode MCP → extract tokens → `output/tokens.css`. Steps 2–9 continue as above.

### For Path B production code (Chain 10 — Three-Phase workflow)

When Path B requires production code that matches Figma byte-for-byte, run **Chain 10** as an alternative to the standard component generation flow:

1. `prompts/16-phase-1-study.md` — extract design spec from Figma (no code)
2. `prompts/17-phase-2-generate.md` — generate code from the Phase 1 spec
3. `prompts/18-phase-3-refine.md` — surgical corrections per drift list

See `chains/chain-10-three-phase-path-b.md` for the full walkthrough. Optionally close the round-trip with Chain 8 (Figma write-back) after Phase 3 if token values were materially updated.

---

## STEP 4 — CHAIN STATE LOG

After each completed prompt, append a line to `output/chain-state.md`:

```
# Chain State — [project name or "unnamed"]

## Session inputs
Archetype: [name]
BYOC: [no | yes — primary #hex, accent #hex]
Brand fonts: [no | yes — display: X, body: Y]
Framework: [React/Vue/Svelte/Web components/Plain CSS]
Component scope: [A/B/C/D/E]

## Completed steps
[timestamp] Prompt 1 — tokens.css generated. Archetype: [name]. BYOC: [yes/no].
[timestamp] Prompt 2 — tokens.css updated with typography. Fonts: [default/brand].
[timestamp] Prompt 03 — foundation.css generated.
...

## Next step
Prompt [N] — [name]
```

This file is how the chain runner resumes if you stop and restart.

---

## STEP 5 — FINAL WRAP-UP

When the selected scope completes:

1. List all generated files with sizes and a one-line description each.
2. Offer: "Would you like me to open `output/design-system-spec.html` in a browser? It renders every component live with theme switcher."
3. Announce: "For ongoing maintenance, run Prompt 11 (drift audit) against any PR that touches component code. Prompt 11 is in `prompts/11-drift-audit.md`."
4. If Layer 3 extraction wasn't run: "Once components stabilise (usually after 2–3 sprints), run `prompts/10-layer-3-extraction.md` to discover component-level tokens from repeated values."

---

*Chain Runner v1.0 · Design Systems That Build Themselves · © 2026 Ishdeep S Sahni · Confidential & proprietary*