What ships with this book

This is not a survey of the field. It is a working system — copy-paste-ready, production-grade, fully documented. Below is everything that lands in your hands the moment you open the kit.

Every artifact in this book exists as a downloadable file you can run today. The chapters explain why each piece exists and how to remix them; the kit is the runnable version. Open kit/README.html to start.

What this book is not: a magic generator. The system requires your inputs (three brand adjectives, optional brand colours, optional Figma file), your judgment at every checkpoint (archetype confirmation, BYOC palette review, drift triage), and an AI tool to drive (Claude in this book — see Ch17). What it does provide: a tested contract between human decisions and AI output, so the same inputs produce the same recognisable system every time.

Five archetypes — pick the one that matches your product

Each archetype is a complete design language: tokens, components, layout vocabulary, banned patterns, voice rules, governance overrides. Click Spec for the rendered HTML preview; click .md for the raw paste-ready spec block.

Plus a sixth, universal: Governance — the spec that every archetype inherits. View HTML · Download .md.

How the system governs itself

Three feedback loops keep generated output aligned with the spec:

The audits do not require human review of every line — they read against the canonical tokens.css and the archetype's banned patterns, and surface only what diverged. The output is a severity-ranked report, not a wall of warnings.

Who this is for

Ch01 makes the case for why this matters. The chapters from Ch02 onward are the system itself.

How to use this book

Three reading paths, depending on where you start:

• Path A — Greenfield. No Figma file. Three brand adjectives in, a published design system out. Chapter 20 is your chapter — run Chain 9.
• Path B — Standard. Existing Figma file. Use Chapters 15–19 for the Figma + MCP workflow. Run Chain 2 first.
• Path C — Deep / audit. Existing work to reconcile against the spec. Run Chain 4 + Chain 5.

Or read in chapter order, top to bottom — that's the original sequence and it works for any path.

The 2026 AI design landscape

Three paradigms exist right now. Until a spec binds them, all three drift. This chapter establishes the difference — and points at the substrate the rest of the book builds on.

Since Figma AI shipped at Config 2024 and Anthropic's vision-capable Claude landed the same month, three distinct AI tracks have emerged in the design and engineering workflow. From the outside they look similar — all three generate UI faster than a human can sketch it. From the inside they solve different problems entirely. Picking one without understanding the difference is like choosing a database before knowing whether you need a spreadsheet.

This chapter establishes the difference. The next chapter establishes why none of them produces a system on its own. The rest of the book is about the substrate — the spec — that turns any of the three paradigms into a system.

Three paradigms

The substrate that binds them

None of the three paradigms produces consistency on its own. The shared dependency is the spec — a structured, copy-pastable contract documenting an archetype's tokens, components, layouts, voice, banned patterns, and governance overrides. Two pages, paste-it-in, run anywhere.

Five archetypes exist — Harbor, Sentinel, Current, Lattice, Meridian (Ch9–11). Each has its own spec. Each spec runs about a thousand lines of structured text. The reader picks an archetype, copies its spec into a prompt, and gets back tokens, components, patterns, and a published spec page that match the spec exactly.

What the spec is, concretely

A spec is a fenced text block — copy-pastable, machine-consumable. It declares THEME, TOKEN NAMING, COLOR TOKENS, TYPOGRAPHY, DENSITY, ACCENT STRATEGY, ELEVATION, ICONOGRAPHY, SECTION TEMPLATES (or layout vocabulary per archetype), COMPONENT LIBRARY (in priority order), VOICE RULES, BANNED PATTERNS, WHEN TO PICK criteria, FAILURE MODES, GOVERNANCE OVERRIDES, and a closing PHILOSOPHY callout. Universal gates live in a separate governance.spec.md that pastes alongside the archetype spec.

Two pastes per prompt. That's the full workflow. The rest of the book is what the pastes contain, why those contents are the right contents, and how to extend or evolve them when your product needs something the canonical archetypes don't cover.

Three workflows, three paths

Because the spec is the substrate, three workflows compose around it. Each path uses a different starting point but lands at the same destination: production code that respects the spec's contract.

Path B is what the bulk of this book teaches because it covers the largest reader audience. Paths A and C are equally complete — Ch20–22 covers each path's full pipeline. Use the path chooser at the top of every chapter to filter content for your path.

Run the system

Two artifacts the book points at — both already exist, both runnable today.

What this book does not cover

You'll do best with this book if you know your way around Figma and have used an AI coding tool at least once. You don't need to be an engineer — but reading CSS and understanding what a component is should feel comfortable.

The AI design consistency crisis

AI can build a UI in minutes. It just builds a different UI every time.

Shipping speed is no longer the bottleneck — generation is effectively free. The new bottleneck is whether screen 47 belongs to the same product as screen 3. That gap, between "fast" and "cohesive", is the consistency crisis. This chapter pins down where the drift comes from, why prompting harder does not fix it, and the shape of the fix the rest of the book delivers.

The drift, in five layers

Same prompt, two days apart, returns two clean outputs that fail the side-by-side test. Each layer below would pass review on its own. All five together read as "different teams built these."

Why drift happens

Drift is not a prompting failure. It is the predictable behaviour of a generator with no visual memory of its prior runs. Four root causes, in the order they bite.

Specification ≠ artifact

The two words look interchangeable. They are not. A pasted token file is a specification — a snapshot, open to interpretation. A Figma file read via MCP, or a fenced spec block consumed inline by the prompt, is the artifact — canonical, shared, current.

The fix shape — five self-actions

"A design system that builds itself" is shorthand for five repeating loops. Each loop is run by the AI; each loop is gated by the spec; you decide six things and watch.

Your role vs AI's role

Six decisions for you, in maybe thirty minutes of thinking. Hours of mechanical execution for the AI. The split is not negotiable — handing AI taste decisions produces template-AI ("Unlock the Power of…"); handing yourself mechanical decisions produces a six-week sprint that should have been an afternoon.

Who this book is for

Four readers, different starting points, the same destination. If you don't see yourself in one of these, the rest of the book will probably frustrate you — and that's fair.

What this book gives you

Five concrete deliverables. Everything between Ch02 and Ch24 reduces to one of them.

Chapter 24 closes the loop with the five chains running end-to-end. Everything between this chapter and that one is the vocabulary, the reference systems, and the individual prompts that compose into those chains. The Kit and the Flow Map sit alongside the book as the runnable surfaces.

What's next

The first fork in the road is the one that compounds the hardest if you take it wrong: which archetype of design system are you actually building? Picking the wrong archetype costs more than not picking — every downstream decision inherits the mismatch. Chapter 02 walks the five-way decision tree and lands you on one of Harbor, Sentinel, Current, Lattice, or Meridian.

Five archetypes of design systems

Most "design system" advice treats the term as one thing. It is not — and the choices the five archetypes make are often the opposite of each other.

This chapter does three things, in order. It introduces the five archetypes I work with — Harbor, Sentinel, Current, Lattice, Meridian — and links to the live spec for each. It dismantles the popular framing that "three brand adjectives" deterministically produce a design system, and replaces it with an honest narrowing-then-evaluating loop. And it lands the reader on a single archetype via a three-question decision tree, which becomes the primary input to every prompt for the rest of the book.

The five — at a glance

Each card opens a live working preview — what running Prompts 1, 45–47, and 49 actually produces when fed that archetype. The paste-able spec text — the fenced block you copy into Prompt 1 — is embedded as a <spec-card> with a COPY button in Ch03 (alongside the prompt that consumes it) and again in each archetype's deep-dive chapter (Ch09–11). The preview shows you what to expect; the spec-card gives you what to paste.

^* Lattice, the archetype name, is unrelated to Lattice the HR product — used here as a categorical label for data-dense analytics surfaces.

Harbor and Sentinel together cover roughly 60–70% of real products in my experience. Current, Lattice, and Meridian are the specialist edge cases. The shared dependency, regardless of which you pick, is the universal governance spec — non-negotiable gates that paste alongside the archetype-specific spec.

Twelve dimensions, opposite choices

The reason archetype choice compounds is that they make opposite calls on almost every dimension. Forcing one archetype's choices onto another's use case produces a system that fights itself — a Sentinel-density dashboard rendered in Harbor's fluid serif, or a Current mobile flow rendered with Lattice's 12px tables.

Adjectives: narrowing, not determining

The most cited shortcut for picking among the five is "describe your brand in three words and the AI will infer the archetype." That shortcut works — but the popular framing is wrong about what it does. Adjectives do not determine a design system. They narrow the space the AI generates inside.

Adjective dictionary

A reference for what each adjective pre-commits before you even press run. Mix and match three from the list — the AI's interpretation will land in roughly the territory described.

This dictionary is a starting position, not a contract. The AI may interpret warm as #C9A961 on one run and #D4A853 on the next; both are warm. The category is reproducible; the specific hex is not. Generate once, evaluate, lock the output as your canonical tokens.css, never re-run from scratch.

The archetype-from-adjectives prompt

Cascade step 2 in the workflow below runs this prompt. Three adjectives in; one archetype recommendation out, with explicit per-dimension reasoning so you can confirm or override before downstream prompts inherit the choice. The prompt is interpretive, not deterministic — its job is to surface a defensible recommendation from a narrowed option space, not to produce the same answer twice. If the recommendation feels wrong, sharper adjectives change the result more reliably than re-running the prompt.

PROMPT — ARCHETYPE FROM ADJECTIVES

YOUR ROLE
You map three brand adjectives to one of five archetypes — Harbor,
Sentinel, Current, Lattice, Meridian — and surface your reasoning per
design dimension so the user can confirm or override. You do NOT generate
any tokens, components, or specs in this step. Your only output is an
archetype recommendation with explicit per-dimension reasoning and a
brief case for the runner-up.

STEP 0 — RECEIVE INPUTS
  THREE BRAND ADJECTIVES: [adjective 1], [adjective 2], [adjective 3]
  PRODUCT TYPE (optional): [e.g. "marketing site", "data terminal", "mobile app"]
  USE CASE NOTES (optional): [e.g. "users sit for 4-hour sessions", "thumb-zone primary"]

If fewer than three adjectives are supplied, stop and ask. If the
adjectives are obvious filler ("modern", "clean", "intuitive", "innovative",
"powerful"), apply the elimination test in STEP 1 and ask for sharper
words before proceeding.

STEP 1 — APPLY THE ELIMINATION TEST
For each adjective, ask: could a competitor design system also claim this
adjective without lying? If yes, flag it as low-signal.

If two of three adjectives flag as low-signal, stop and request sharper
adjectives. Do not proceed to a recommendation — the input doesn't narrow
the option space enough to justify one.

If exactly one adjective is low-signal, note it and proceed; the other two
will carry the inference.

STEP 2 — INFER PER-DIMENSION TENDENCIES
Output ONE sentence per dimension, naming the value the adjectives
narrow toward and the adjective(s) driving that inference:

  - Theme: dark-first | light-first | both first-class | reading-comfortable
  - Density: generous | compact | maximum | reading-comfortable (Meridian's 72ch cap)
  - Type personality: serif-display + sans-body | sans-throughout | native-system | sans + mono-numerics
  - Accent strategy: single-hue | multi-ramp + semantic | bold-multi-accent | minimal | two-systems (chrome + data)
  - Elevation: warm-shadows | flat + hairlines | soft mobile | grid-based | almost-flat
  - Iconography: Phosphor | Lucide | Phosphor + native | Tabler | Heroicons
  - Implied session length: short brand visit | desktop work session | mobile bursts | long terminal | reading session

STEP 3 — SCORE AGAINST THE FIVE ARCHETYPES
Score each archetype against the inferred tendencies. Reference the
archetype profiles below:

  - HARBOR — dark-first, generous, serif-display + sans-body, single-hue,
    warm-shadows, Phosphor, short brand visit. Editorial / marketing.
  - SENTINEL — light-first, compact, sans-throughout, multi-ramp + semantic,
    flat + hairlines, Lucide, desktop work session. Enterprise / product.
  - CURRENT — both first-class, generous (touch zones), native-system,
    bold-multi-accent, soft mobile, Phosphor + native, mobile bursts. Mobile.
  - LATTICE — dark-first, maximum, sans + mono-numerics, two-systems,
    grid-based, Tabler, long terminal. Data-dense.
  - MERIDIAN — reading-comfortable, reading-comfortable density, serif-body
    + sans-display, minimal, almost-flat, Heroicons, reading session. Long-form.

Pick the closest match. If a second archetype scores within one or two
dimensions of the closest, name it as a secondary fit and explain what
would tip the choice (e.g., "Sentinel if dashboard-heavy; Lattice if data
density matters more than approachability").

STEP 4 — DELIVER THE RECOMMENDATION
Output the recommendation in EXACTLY this shape:

  ADJECTIVES: [restated, exactly as provided]
  ELIMINATION TEST: pass | flagged: [adjective] is low-signal because [reason]

  PER-DIMENSION INFERENCE:
  - Theme: [value] (driven by [adjective])
  - Density: [value] (driven by [adjective])
  - Type personality: [value] (driven by [adjective])
  - Accent strategy: [value] (driven by [adjective])
  - Elevation: [value] (driven by [adjective])
  - Iconography: [value]
  - Implied session length: [value]

  RECOMMENDED ARCHETYPE: [Harbor | Sentinel | Current | Lattice | Meridian]
  ONE-SENTENCE REASONING: [why this archetype, not another]
  SECONDARY FIT (if applicable): [other archetype] — [one-sentence tipping condition]

  NEXT STEP: confirm or override the recommendation. Then proceed to
  Prompt 1 (or Prompt 1b for BYOC) in Ch03 with the chosen archetype's
  spec from kit/specs/.

CONSTRAINTS
- Do NOT generate any tokens, components, or specs in this step. Output
  the recommendation block above and stop.
- Do NOT pick an archetype outside the five named.
- If you genuinely cannot fit the adjectives to any archetype (e.g., they
  describe a hybrid use case like "marketing site + data dashboard"), say
  so explicitly and propose a layered approach: name the primary archetype
  for the dominant surface and the secondary archetype for the other
  surface (Ch11 covers hybrid patterns).
- Do NOT paraphrase the adjectives in STEP 4's "ADJECTIVES" line. Restate
  them verbatim so the user can verify what you parsed.
- If the user's product type or use case notes contradict the adjective
  inference (e.g. adjectives lean Harbor but product is "internal admin
  tool"), surface the contradiction explicitly and recommend the archetype
  that fits the use case, not the adjectives.

The cascade — generation with checkpoints

The popular cascade diagram shows a clean linear pipeline: adjectives in, design system out. The honest cascade has explicit human gates between each stage so the interpretive nature of generation is visible — and correctable. In Chain Mode (kit/chain.md), the orchestrator collects steps 1–3 as upfront Q&A before any generation starts — archetype, BYOC colors, and brand fonts are all decided before the first prompt runs. In ad-hoc mode, Prompt 1's meta-header asks the same questions the moment you paste it.

Picking the archetype — a three-question tree

If the adjectives feel forced, the decision tree gets you to one of the five faster than any taste exercise. Three questions, eliminations along the way.

Archetype and palette are separable

A common pushback at this point: "What if I have my own brand colors but I don't want to invent the structure?" The structural decisions (density, type scale, naming, elevation, motion) and the cosmetic decisions (which hues, which saturation level) are independent. The book treats them as one decision by default — but Ch03 ships a Bring-Your-Own-Colors variant, Prompt 1b, that lets you keep the archetype and substitute your palette.

What's locked vs what's yours

The natural follow-up: "if Sentinel's spec is fixed, won't every product that picks Sentinel ship the same UI?" No — and not by accident. The archetype locks structural decisions; six named seams let you personalize within that structure. Two readers, both Sentinel, ship products that look visibly different. That's the design — Sentinel is the bones, not the skin.

Vectors 1–3 substitute values within the archetype's structural rules. Vector 4 picks scope. Vectors 5–6 add net-new tokens and components that are unique to your product. None of them rewrite the archetype; all of them produce a system that is recognisably yours.

Worth flagging: substitution has limits. Within the archetype's role rules, you have wide latitude — Inter, GT America, IBM Plex, Söhne all work as Sentinel's body sans. Across the role rules, substitution breaks the archetype — swapping Sentinel's body sans for a serif breaks Sentinel's reading rhythm; swapping Harbor's display serif italic for a geometric sans breaks Harbor's editorial signature. The same is true for colors: Sentinel handles a wide palette, but Harbor's single-hue rule means BYOC accepts one primary, not five.

Failure modes — forcing the wrong archetype

Every archetype I've identified has a predictable failure mode when applied to the wrong use case. The symptom always shows up at the system level, not the screen level — so spotting these early is the difference between a one-prompt fix (re-pick the archetype) and a two-week refactor.

What's next

The archetype is now your primary input. Adjectives are a first-pass aid for picking it, not a separate decision. The next chapter takes the chosen archetype's spec and runs it through Prompt 1 (or Prompt 1b for BYOC) to produce tokens.css — the token architecture that every component in Ch04 onwards will inherit from.

Token architecture

Tokens are the contract every component must obey. Architecture is what makes that contract survive rebrands, theme switches, and product evolution.

A token is a named value — --color-primary, --space-4, --text-base. A flat token list is a glossary. A token architecture is what lets you re-skin the system without touching component code, ship a dark theme without re-authoring 200 properties, and add Layer 3 component-tokens later without rewriting the foundation. This chapter establishes the architecture, ships the three prompts that produce it from your archetype spec, and tells you what to expect on the other side of running them.

Three layers — primitives, semantic aliases, components

Every token in this book lives at one of three layers. The layer it sits at determines who consumes it, when it changes, and what the blast-radius of changing it looks like.

Layer 3 is the layer most teams add too early. Don't author component tokens upfront. Let them emerge from real component CSS once you've shipped a few iterations — the Layer 3 extraction prompt scans your locked CSS for values repeated three or more times and proposes which ones deserve a token. Until then, components reference Layer 2 directly.

Why the layering matters

Three scenarios illustrate the cost of conflating layers:

• Rebrand. Your primary changes from indigo to teal. With layered tokens, you change one primitive (--primary-700) and every component inherits. With flat tokens, you grep your codebase for #1B2A4A and pray you find every reference.
• Theme switch. Light-to-dark swap. With layered tokens, the [data-theme="dark"] override re-points primitives only — semantic aliases stay untouched, components stay untouched. With flat tokens, every component needs its own dark-mode rule.
• Role shift. Your "primary" was the brand color; a redesign promotes "accent" to be the brand color and demotes "primary" to a structural neutral. With layered tokens, you re-point semantic aliases — primitives stay; components stay. With flat tokens, every component that referenced the old primary needs editing.

The wrong-versus-right pattern in CSS:

/* WRONG — component references a primitive directly. Tightly coupled. */
.button-primary {
  background: var(--primary-700);
}

/* RIGHT — component references a semantic alias. Decoupled. */
.button-primary {
  background: var(--color-primary);
}

/* The semantic alias resolves to a primitive once, centrally, in :root */
:root {
  --color-primary: var(--primary-700);
}

[data-theme="dark"] {
  --primary-700: #7AA8E0;  /* override at the primitive layer only */
}

Where the specs come from

Every prompt below opens with two pastes: governance.spec.md first (universal — same text for every archetype, every prompt that consumes a spec) and your chosen archetype spec second. Both are embedded inline below as COPY-able blocks. The archetype block carries a dropdown — pick Harbor, Sentinel, Current, Lattice, or Meridian and the spec updates in place; hit COPY to grab the full text. The Ch02 archetype-at-a-glance cards are the browsing surface; this is the running surface.

Pick your archetype's spec

Use the dropdown to switch archetype. Spec updates inline; COPY grabs whichever is currently shown. Paste second, after governance.

Loading archetype spec…

Governance — paste this FIRST, every time

The governance spec is universal. Copy the block below and paste it FIRST into Prompts 1, 1b, 49, 51 (and any other prompt that lists governance.spec.md in its inputs). Then paste your chosen archetype spec second. Two pastes, every prompt.

═══════════════════════════════════════════════════════════════
GOVERNANCE · UNIVERSAL · v1.0
Applies to ALL archetypes — paste before archetype spec
═══════════════════════════════════════════════════════════════

───────────────────────────────────────────────────────────────
ACCESSIBILITY GATES (WCAG 2.1)
───────────────────────────────────────────────────────────────
• Contrast ratios:
    - Body text:        ≥ 4.5:1 (AA), aim for AAA on primary body
    - Large text (18pt+ or 14pt bold): ≥ 3:1 (AA)
    - Non-text UI (icons, focus rings, chart elements): ≥ 3:1
    - Decorative-only elements: exempt
• Every spec page MUST include an Accessibility Verification
  table computed from the actual token values (FG / BG / Ratio /
  Status pill: AAA / AA / FAIL). Do not omit. Do not estimate.
• Failing combinations must be flagged with "FAIL — do not use"
  and an alternative pairing suggested.

───────────────────────────────────────────────────────────────
KEYBOARD NAVIGATION
───────────────────────────────────────────────────────────────
• Every interactive element reachable via Tab in DOM order
• Focus indicator visible: 2px outline, offset 2px,
  --color-focus-ring (defined per archetype)
• Standard key bindings honored:
    Enter / Space  → activate buttons, toggles, links
    Esc            → close dialogs, drawers, popovers, menus
    Arrow keys     → navigate within tabs, radio groups, menus,
                     and listboxes
    Home / End     → jump to first / last item in lists
    Tab / Shift+Tab → forward / back through focusable elements
• Focus trapping: required for modal dialogs, drawers, command
  palettes. Esc returns focus to trigger.
• Skip-to-content link required at top of every page.

───────────────────────────────────────────────────────────────
SCREEN-READER REQUIREMENTS
───────────────────────────────────────────────────────────────
• All icon-only buttons must have aria-label
• All form fields must have programmatic labels (label[for] or
  aria-labelledby — never placeholder-as-label)
• Live regions for toasts, async results, validation errors
  (aria-live="polite" default; "assertive" only for errors
  blocking task completion)
• Test matrix: VoiceOver (Safari/macOS), NVDA (Firefox/Win),
  TalkBack (Chrome/Android) for any component shipped to mobile
• Decorative SVGs: aria-hidden="true". Meaningful SVGs:
  role="img" + <title>.

───────────────────────────────────────────────────────────────
MOTION & ANIMATION
───────────────────────────────────────────────────────────────
• prefers-reduced-motion: reduce → fallback to fade-only or
  no animation. Never just shorten duration; remove transform
  animation entirely.
• No autoplay video or animated backgrounds without user
  consent.
• Vestibular safety: avoid parallax > 20% offset, scroll-jacking,
  spinning loaders > 2s without text label.

───────────────────────────────────────────────────────────────
TOKEN HYGIENE
───────────────────────────────────────────────────────────────
• Zero raw hex in component CSS. Every color, every size, every
  shadow goes through var(--token-name).
• Components reference SEMANTIC tokens, never primitives.
  Bad:  color: var(--color-blue-500);
  Good: color: var(--color-link);
• Both light and dark mode tokens defined for every semantic
  token, even if a mode is unshipped.
• Tokens declared in a single :root + [data-theme="dark"]
  override block. No tokens defined inside component scope.

───────────────────────────────────────────────────────────────
COMPONENT STATE COVERAGE
───────────────────────────────────────────────────────────────
Every interactive component must implement these states
(visually distinct, not just functionally present):
    default
    hover           (pointer devices only — :hover)
    focus-visible   (keyboard users — :focus-visible, NOT :focus)
    active          (pressed — :active)
    disabled        ([disabled] or aria-disabled="true")
    loading         (where applicable — async actions)
    error           (where applicable — validation/failure)
    success         (where applicable — confirmation states)

Form fields additionally implement:
    empty / filled / required / read-only

───────────────────────────────────────────────────────────────
ERROR-MESSAGE FORMULA (UNIVERSAL)
───────────────────────────────────────────────────────────────
Every error message follows What → Why → How:
    What: [what happened, plain language]
    Why:  [the cause]
    How:  [recovery action — concrete, doable]

  Bad:  "Invalid input."
        "Something went wrong. Try again."
  Good: "Email format isn't recognized. Try name@example.com."
        "Upload failed. The file is over 10MB.
         Try compressing it."

Banned: stack traces in user-facing copy, error codes without
explanation, generic "Oops!" / "Whoops!" messaging.

───────────────────────────────────────────────────────────────
COPY HYGIENE (UNIVERSAL)
───────────────────────────────────────────────────────────────
• Sentence case for headings, buttons, labels (not Title Case,
  not ALL CAPS — except for an "overline" eyebrow style)
• No emoji in UI copy. SVG icons only. (Emoji acceptable in
  user-generated content rendering.)
• Contractions allowed (we'll, don't, can't) — softer voice
• Verb-first CTAs ("Save changes", not "Changes can be saved")
• Banned filler: "Please", "Kindly", "Just", "Simply"
• Banned marketing fluff in product UI: "Let's embark on…",
  "Unlock the power of…", "Revolutionize your workflow"

───────────────────────────────────────────────────────────────
ICONOGRAPHY (UNIVERSAL FLOOR)
───────────────────────────────────────────────────────────────
• SVG only. Inline preferred for color inheritance.
• fill="currentColor" or stroke="currentColor" — never hex
• aria-hidden="true" for decorative; <title> for meaningful
• Consistent grid (24px standard; archetype may override)
• Consistent stroke width within a family
• Never mix icon families on the same surface
• Banned: emoji as icon, raster (.png) icons, animated GIF icons

───────────────────────────────────────────────────────────────
VERSIONING
───────────────────────────────────────────────────────────────
SemVer (MAJOR.MINOR.PATCH):
    MAJOR — breaking token rename, removed component, breaking
            API change
    MINOR — new component, new variant, new token, deprecation
            notice
    PATCH — bug fix, doc update, non-visual refactor

Deprecation policy: deprecated tokens/components ship for
2 MINOR versions before removal. Deprecation warnings logged
in console at build time.

───────────────────────────────────────────────────────────────
CHANGELOG TEMPLATE
───────────────────────────────────────────────────────────────
## [VERSION] — YYYY-MM-DD

### Added
- [new components, tokens, variants]

### Changed
- [modifications to existing surfaces]

### Deprecated
- [old → new migration path, removal version]

### Removed
- [breaking removals — MAJOR only]

### Fixed
- [bug fixes]

### A11y
- [accessibility improvements — call out separately]

───────────────────────────────────────────────────────────────
QUALITY-GATE CHECKLIST (PR / RELEASE BLOCKING)
───────────────────────────────────────────────────────────────
☐ Contrast ratios verified (AA minimum, AAA for primary body)
☐ Keyboard navigable (Tab / Space / Enter / Esc / Arrows)
☐ Screen-reader tested (VoiceOver + NVDA minimum)
☐ prefers-reduced-motion honored
☐ Both light + dark mode tokens defined
☐ Storybook (or equivalent) story per variant + state
☐ No raw hex in components
☐ No emoji in UI
☐ Component implements default / hover / focus-visible /
  active / disabled
☐ Error messages follow What/Why/How
☐ Visual-regression snapshot committed
☐ Changelog entry under correct semver bump

───────────────────────────────────────────────────────────────
PERFORMANCE BUDGETS (universal floor)
───────────────────────────────────────────────────────────────
Performance is a design system concern. Slow systems erode every
other quality choice. Universal targets per page (every archetype):

First Contentful Paint (FCP):     < 1.5s on 4G mobile
Largest Contentful Paint (LCP):   < 2.5s on 4G mobile
Cumulative Layout Shift (CLS):    < 0.1
Time to Interactive (TTI):        < 3.5s on 4G mobile
Bundle (JS, gzipped):             < 100KB initial route
Bundle (CSS, gzipped):            < 30KB
Web font payload:                 < 100KB total (subset + woff2)
Largest image:                    < 200KB (WebP/AVIF preferred)

Per-archetype tightening (overrides):
  Current   — initial JS < 70KB (mobile networks)
  Lattice   — initial JS < 50KB; data-grid virtualization mandatory
  Meridian  — web font < 60KB (subset to article glyph set);
              first paint must show body text within 1s
  Harbor    — hero image < 150KB; font subset to display set
  Sentinel  — initial JS < 100KB (workhorse default)

Quality-gate addition: every release runs Lighthouse + WebPageTest
budget check. Regressions fail CI.

───────────────────────────────────────────────────────────────
INTERNATIONALIZATION (i18n)
───────────────────────────────────────────────────────────────
Every component MUST work in:

Direction:
  • LTR (default — English, most European)
  • RTL (Arabic, Hebrew, Persian, Urdu)
  Required: every component declares logical CSS properties
  (margin-inline-start instead of margin-left) so RTL flips
  correctly without per-language overrides.

Character ranges:
  • Latin (basic + extended)
  • CJK (Chinese, Japanese, Korean) — taller line-heights
    needed (1.6+ minimum); fonts may need to swap to
    region-appropriate (Noto Sans CJK)
  • Cyrillic, Greek, Devanagari per product reach

Locale-sensitive tokens:
  • Date / time formats — use Intl.DateTimeFormat, never
    hardcode "MM/DD/YYYY"
  • Number formats — Intl.NumberFormat handles
    locale separators, currency, units
  • Sort orders — Intl.Collator for string comparison
  • Pluralization — Intl.PluralRules + ICU MessageFormat

Banned i18n antipatterns:
  ✗ Hardcoded English strings in components (use i18n keys)
  ✗ Concatenated strings ("You have " + count + " items") —
    use ICU plurals
  ✗ Fixed-width buttons that truncate German (avg 30%+ longer)
  ✗ Direction-aware icons (chevrons, arrows) without RTL flip
  ✗ Assuming Latin characters in regex / validation
  ✗ ASCII-only password rules

───────────────────────────────────────────────────────────────
FORM VALIDATION STRATEGY (universal pattern)
───────────────────────────────────────────────────────────────
Validation behavior is a tonal choice — get it wrong and the
form feels nagging or surprises the user at submit time.

WHEN to validate:

  ✓ On blur (after user leaves the field)        — DEFAULT
  ✓ On submit (final check, always runs)         — REQUIRED
  ✓ On change (real-time), but ONLY for:
    - Password strength meters (visible feedback as user types)
    - Username/handle availability (debounced API check)
    - Match-confirmation fields (password confirm matches)

  ✗ On every keystroke for general fields (nagging, breaks
    flow — user is mid-thought)

WHAT to validate:
  • Required field empty
  • Format mismatch (email, URL, phone, date)
  • Range / length violations
  • Server-side rules (uniqueness, conflict, capacity)

HOW to display:
  • Error message replaces helper text below input
  • Field gets --color-error border + 3px focus ring on focus
  • Error message follows What/Why/How formula
  • Error icon to the left of message (color + icon redundant
    encoding — colorblind a11y)
  • aria-invalid="true" + aria-describedby pointing to error msg
  • Submit button stays enabled (per WCAG SC 3.3.4); never
    disable submit because that hides the form's validation
    state from the user

Per-archetype overrides:
  Sentinel  — inline validation on blur, parenthetical
              "(required)" not asterisk-only
  Current   — keyboard type matches input semantic
              (inputMode="numeric" / "email" / "tel")
  Meridian  — forms are rare; when present, generous spacing
              (--space-4 between fields), clear labels
  Lattice   — number-field formatting (mono + tabular figures);
              tab key advances within table-grid forms
  Harbor    — labels above (NEVER floating); error tone
              consistent with editorial voice (no exclamation)

───────────────────────────────────────────────────────────────
LOADING-STATE STRATEGY (universal decision tree)
───────────────────────────────────────────────────────────────
Choose the right loading affordance — wrong choice feels broken.

Operation duration → preferred loading state:

  < 100ms     → no loading state (instant)
                User won't notice; showing a spinner adds latency
                perception, not removes it.

  100–300ms   → optimistic UI (immediate state change, server
                confirms in background; rollback on error)
                Right for: like buttons, toggle switches, inline
                edits.

  300ms–1s    → button → loading state on the action
                Button shows spinner inline + disables; rest of
                page stays interactive.

  1s–5s       → skeleton placeholders (NOT spinner)
                Show shape of incoming content; reduces perceived
                wait. Skeleton MUST match content shape (don't
                use generic rectangles).

  5s–30s      → progress indicator with text label
                "Analyzing screenshot — 68% (about 4 seconds left)"
                Shows progress + ETA + ability to cancel.

  > 30s       → background processing + notification on completion
                Don't make the user wait. Submit, navigate away,
                notify (toast / email / push) when done.

Per-archetype rules (tightening):
  Lattice   — prefer NO loading state for sub-100ms ops; never
              hide chrome behind a loader (keep keyboard
              shortcuts + nav functional)
  Current   — pull-to-refresh haptic on threshold; skeleton
              required for any list waiting > 500ms
  Meridian  — skeletons banned (motion ban); use opacity-static
              placeholders OR no loader at all (most docs render
              statically anyway)
  Harbor    — skeletons subtle (--color-surface-2 base, opacity
              pulse), never shimmer (too feature-y)
  Sentinel  — text label required next to spinner if wait > 1s

Banned loading antipatterns (universal):
  ✗ Spinner with no text after 1s (ambiguous — stuck or working?)
  ✗ Full-screen blocker for partial-page loads
  ✗ Skeleton shimmer in Meridian / editorial contexts
  ✗ Hide nav / sidebar / chrome behind a loading state
  ✗ Disabling Submit button "to prevent double-click" — use
    debounce + button loading state instead

───────────────────────────────────────────────────────────────
HYBRID PRODUCTS (when one archetype isn't enough)
───────────────────────────────────────────────────────────────
Most real products are hybrids. Common patterns:

  Marketing site + Product app
    → Harbor for the marketing surface (homepage, pricing,
      case studies); Sentinel for the in-app product
    → Examples: Linear, Notion, Stripe, Vercel
    → Strategy: separate codebases or distinct route trees;
      Harbor + Sentinel each ship their own tokens.css with
      shared brand primitives (same primary hex) but
      independent semantic layers, type scales, density.

  Web app + Mobile app
    → Sentinel for desktop web; Current for native mobile
    → Examples: Slack, Figma, Notion, Asana
    → Strategy: shared brand color anchor; otherwise distinct
      systems. Don't try to "responsive" Sentinel down to mobile
      — touch ergonomics demand Current's rules (44px targets,
      bottom-anchored nav, sheets-not-modals).

  Product app + Data terminal view
    → Sentinel for the workflow shell; Lattice for the
      data-explorer / monitoring screens
    → Examples: Linear's command bar, Datadog inside their
      broader app, Snowflake's worksheet inside admin chrome
    → Strategy: keep Lattice scoped to specific routes;
      transition is explicit (visual rule: navigating into the
      Lattice route changes chrome density + introduces the
      data-system color palette)

  Marketing site + Documentation
    → Harbor for marketing; Meridian for docs subdomain
    → Examples: Stripe, Tailwind, Vercel — marketing on root,
      docs on /docs or docs.* subdomain
    → Strategy: shared header brand, distinct layouts. Docs
      reading experience must NOT inherit Harbor's atmospheric
      hero patterns.

  Product app + In-app docs / help center
    → Sentinel shell + Meridian content panes for docs
    → Strategy: docs render as a Meridian-styled panel inside
      Sentinel's chrome (right drawer, modal, dedicated route)

KEEP TOKEN FILES SEPARATE (the universal hybrid rule):
  Don't force one tokens.css to cover both archetypes. Each
  archetype owns its own:
    - Semantic layer (Layer 2 token names per archetype)
    - Typography scale (Harbor clamp vs Sentinel fixed px etc.)
    - Density scale
    - Component priority order
    - Banned patterns

  Share ONLY:
    - Brand primary hex (the anchor color)
    - Brand voice principles (broad guidelines, not specific
      voice rules — those vary per archetype)
    - Universal governance gates (this file)

The most expensive mistake in hybrid design: forcing one
archetype's choices onto another archetype's use case. A 14px
base font is correct for Lattice and catastrophic for Meridian.
Pick the right archetype per surface, then build within it.

───────────────────────────────────────────────────────────────
ARCHETYPE OVERRIDES — AGGREGATED SUMMARY
───────────────────────────────────────────────────────────────
Each archetype inherits this governance spec in full and adds
its own overrides. Below is the canonical aggregated summary
(updated whenever any archetype's overrides change).

Harbor — 9 overrides
  Theme: dark-first; semantic-only tokens; fluid clamp typography;
  warm oklch shadows; single accent enforced; serif italic
  display reserved for editorial emphasis; floating label class
  banned; indigo/purple banned; avatar initials default; one
  primary CTA per section; hero variants limited to template 01.

Sentinel — 10 overrides
  Two-layer token architecture; accent-CTA rule (no white-on-
  orange in chrome); tabular numerals on numeric columns; fixed
  px modular typography; sans-serif only; cold rgba shadows;
  dark-mode tokens defined; WCAG verification table required
  in spec page; color-only encoding banned; "(required)"
  parenthetical (not asterisk-only).

Current — 11 overrides
  44px minimum touch targets enforced; body font ≥ 16px on
  inputs; native font stack default; safe-area insets honored;
  hover-only interactions banned; hamburger nav banned as
  primary; tab bar capped at 5 items; haptics paired with
  visible state; modal-only patterns flagged for review;
  inputMode matches input semantic; both light + dark modes
  required.

Lattice — 10 overrides
  Two-color-system architecture (chrome + data separate);
  monospace + tabular numerals on all numeric columns; every
  interactive element has documented keyboard shortcut;
  animation on data updates banned; shadows on default surfaces
  banned; confirmation dialogs banned for reversible actions;
  pagination banned for data tables (must virtualize); color-
  only encoding banned; body type ≥ 11px in chrome; pane
  resizability required.

Meridian — 11 overrides
  Reading-width hard-capped at 72ch on body; body type ≥ 17px;
  body line-height ≥ 1.7; animation on body content banned;
  sepia + dark mode tokens defined; print stylesheet required;
  all headings (h2+) auto-id'd; external links flagged with
  icon; code blocks have copy button; ⌘/Ctrl+K search wired;
  marketing hype words blocked in body.

───────────────────────────────────────────────────────────────
SPEC-PAGE OUTPUT REQUIREMENTS (Prompt 08)
───────────────────────────────────────────────────────────────
Every generated spec page MUST contain these sections, even if
the archetype spec doesn't enumerate them explicitly. Prompt 08
derives missing details from archetype rules.

Required sections (in this order):
  §1.1  Color system + Accessibility verification table
  §1.2  Typography (scale, weights, line-heights)
  §1.3  Spacing scale
  §1.4  Elevation + shadows (with use case per token)
  §1.5  Shape & borders (radii with use guidance)
  §1.6  Motion (durations + easings + reduced-motion fallback)
  §1.7  Iconography (family, grid, stroke, sample grid)
  §2    Voice & content (Do/Don't pairs)
  §3    Component library (foundation → composite → domain)
  §4    Patterns (form layout, empty state, + archetype-specific)
  §5    Accessibility (WCAG conformance, keyboard map, SR notes)
  §6    Versioning + Governance (this checklist + changelog
        template)
  Footer: version · generation date · mode · WCAG target ·
          archetype name

═══════════════════════════════════════════════════════════════
END GOVERNANCE · v1.0
═══════════════════════════════════════════════════════════════

The two prompts

Two prompts produce the token architecture. Both are in kit/prompts/ and work in any Claude session. In Chain Mode (paste kit/chain.md into Claude Code), they run sequentially with auto-save, Q&A branching, and handoff — no manual copy-paste between steps.

Prompt 1 — Token generation (with BYOC built in)

Reads the two specs, asks about brand colors and fonts before generating anything, emits output/tokens.css with verified WCAG contrasts, applies governance overrides, and tells you exactly what to do next. Use Claude Opus — the interpretive judgment matters more here than for any other prompt in the book.

The card below shows the core generation instructions — the prompt body that Claude executes. When you run this from the kit (kit/prompts/01-tokens-from-spec.md), the prompt opens with a meta-header that detects your environment (Claude Code vs Claude.ai), checks for existing output files, and asks the two branching questions before a single line of CSS is generated. It closes with a meta-footer that saves output/tokens.css, offers an HTML preview, and announces Prompt 2 is ready. The instructions below are what runs between those two wrappers.

PROMPT 1 — TOKEN GENERATION FROM ARCHETYPE SPEC

YOUR ROLE
You are a design-system token generator. You translate two pasted specs
into a production-grade tokens.css with verified WCAG contrasts and full
light + dark coverage.

STEP 0 — RECEIVE INPUTS
Confirm both pastes before generating any CSS.

  PASTE 1 — governance.spec.md: [paste here]
  PASTE 2 — [archetype].spec.md: [paste here]

If either paste is missing or incomplete, stop and ask for it.

STEP 1 — VALIDATE SPEC STRUCTURE
The archetype spec must contain: THEME, TOKEN NAMING, COLOR TOKENS,
TYPOGRAPHY, DENSITY, ACCENT STRATEGY, ELEVATION, RADII, MOTION,
ICONOGRAPHY, GOVERNANCE OVERRIDES.

The governance spec must contain: WCAG MINIMUMS, BANNED PATTERNS,
GLOBAL CONSTRAINTS.

If any required section is missing, name it and stop.

STEP 2 — EMIT THE :root BLOCK
Generate :root with:
  - Surface tokens per archetype's THEME (--color-bg, --color-surface, etc.)
  - Border tokens (--color-divider, --color-border, --color-focus-ring)
  - Text tokens (--color-text, --color-text-muted, --color-text-faint)
  - Accent tokens per ACCENT STRATEGY (single-hue OR multi-ramp per spec)
  - Semantic trio (--color-success, --color-warning, --color-error)
  - Spacing scale per DENSITY (4px, 2px, or 8px base)
  - Radii per RADII block
  - Motion per MOTION block (with reduced-motion fallback)
  - Icon sizing scale

Apply archetype rules:
  - TOKEN NAMING: semantic-only OR primitive+semantic, per spec
  - THEME: dark-first OR light-first, per spec
  - DENSITY: spacing base per spec

TYPOGRAPHY: generate ZERO font tokens here. --font-display, --font-body,
--font-mono, --text-*, --leading-*, --tracking-*, --weight-* are all
Prompt 2's job. If the archetype spec's TYPOGRAPHY section is present,
acknowledge receipt — then skip it. Prompt 2 will consume it.

PATH B TYPOGRAPHY DETECTION (MCP context only):
If running with Figma Dev Mode MCP access, after reading Variable
collections also scan Figma Text Styles — typography lives there,
not in Variables. Do NOT emit font tokens. Instead append to
output/chain-state.md:

  [Figma typography detected]
  Text Styles found: [yes | no]
  Styles: [name · font-family · size · weight · line-height per style]
  Note for Prompt 2: read these from Figma via MCP instead of
  asking the user to specify fonts manually.

If no Text Styles are found, note:
  [Figma typography detected]
  Text Styles found: no — Prompt 2 will ask user for font preferences.

STEP 3 — EMIT THE OPPOSITE-THEME OVERRIDE BLOCK
Generate the opposite-theme override block (e.g., [data-theme="light"]
if archetype is dark-first). Override only what changes — typically
surfaces, text, divider, border, focus-ring. Keep accent and semantic
constant unless governance spec requires otherwise.

STEP 4 — VERIFY WCAG CONTRAST
For every text-on-surface pair, compute contrast and output a markdown
table:

  | Foreground | Background | Ratio | WCAG |
  |---|---|---|---|
  | --color-text | --color-bg | 14.2:1 | AAA |
  ...

Flag any ratio below the governance spec's WCAG MINIMUMS section.

STEP 5 — APPLY GOVERNANCE OVERRIDES
Read GOVERNANCE OVERRIDES in the archetype spec. Apply archetype-specific
gates: Harbor's warm oklch shadows, Current's 44px touch-target floor,
Sentinel's sentence-case-only labels, etc.

STEP 6 — DELIVER THE FINAL FILE
Output the complete tokens.css as a single fenced code block, preceded
by a 2-line summary (token count, WCAG ratios passed/flagged). No prose
before or after the code block.

CONSTRAINTS
- No hardcoded color values outside the :root block.
- No magic numbers in spacing or radii — all spatial values reference tokens.
- All motion respects prefers-reduced-motion.
- Honor the BANNED PATTERNS section absolutely.
- No emoji, no Comic Sans, no Papyrus, no archetype-banned typefaces.

BYOC — Bring Your Own Colors

BYOC is built into Prompt 1 — there is no separate paste step. When you run Prompt 1 from the kit, it asks: "Do you have brand colors to honour?" — answer yes, supply your primary hex (and optionally accent), and Prompt 1 activates the BYOC path inline. The full derivation logic (oklch ramp interpolation, WCAG validation, per-archetype TOKEN NAMING) runs inside Prompt 1 without switching files. A standalone 01b-byoc.md file ships in the kit as reference documentation for the BYOC logic itself, not as a step you run separately.

Prompt 2 — Typography scale (with brand fonts if noted)

Reads output/tokens.css from Prompt 1, layers the type scale on top, and applies any brand fonts you specified in Prompt 1's meta-header. Optionally substitutes brand fonts while preserving role rules — Inter ↔ GT America in Sentinel works; serif body in Sentinel breaks the archetype and gets flagged. Saves the updated output/tokens.css and announces Prompt 03 is ready.

PROMPT 2 — TYPOGRAPHY SCALE (with optional brand-font substitution)

YOUR ROLE
You generate the typography token block on top of an existing tokens.css.
You match the type-scale shape (fluid clamp() vs fixed modular) to the
archetype's TYPOGRAPHY rules. You optionally substitute brand fonts
while preserving role rules.

STEP 0 — RECEIVE INPUTS
  PASTE 1 — existing tokens.css from Prompt 1 / 1b: [paste here]
  PASTE 2 — [archetype].spec.md (TYPOGRAPHY section): [paste here]
  YOUR BRAND DISPLAY FONT (optional): [font name + import URL]
  YOUR BRAND BODY FONT (optional): [font name + import URL]
  YOUR BRAND MONO FONT (optional): [font name + import URL]

Brand fonts are optional. Without them, use the archetype's default font
assignments.

STEP 1 — VALIDATE FONT ROLE COMPATIBILITY
Check brand fonts against archetype TYPOGRAPHY rules:
  - Harbor: display = serif (italic-capable for editorial flourish), body = sans
  - Sentinel: display + body = sans-serif (same family allowed), mono optional
  - Current: display + body = native or sans, mono optional
  - Lattice: display + body = sans, mono = required (tabular numerics)
  - Meridian: body = serif preferred (sans allowed for technical), display = sans

If a supplied brand font violates the archetype's role (e.g., a serif for
Sentinel's body), FLAG IT BACK and propose either keeping the archetype
default OR overriding (which breaks the archetype). Do not silently
substitute incompatible fonts.

STEP 2 — EMIT FONT FAMILY TOKENS
Generate:
  --font-display: [brand display | archetype default], [fallback stack];
  --font-body:    [brand body    | archetype default], [fallback stack];
  --font-mono:    [brand mono    | archetype default], ui-monospace, monospace;

Include @import url() at the top of the file for any web-fonts. Use
font-display: swap for all custom fonts.

STEP 3 — EMIT TYPE SCALE
Per archetype:
  - Fluid clamp() (Harbor / Current / Meridian display): clamp(min, base + vw, max).
  - Fixed modular (Sentinel / Lattice): 1.125 (Sentinel) or 1.067 (Lattice)
    modular ratio with a 14px or 12px base.
  - Reading-comfortable (Meridian body): 17–19px body with 1.75 leading.

Token names:
  --text-xs, --text-sm, --text-base, --text-lg, --text-xl, --text-2xl, --text-hero
  --leading-tight, --leading-snug, --leading-normal, --leading-relaxed
  --tracking-tight, --tracking-normal, --tracking-wide
  --weight-regular, --weight-medium, --weight-semibold, --weight-bold

STEP 4 — VERIFY READING ERGONOMICS
For body text in particular:
  - Body font size at viewport >= 1024px: 14px floor for Sentinel/Lattice,
    16px floor otherwise.
  - Reading-width cap (max-width on body p): 80ch for Meridian, 70ch for Harbor,
    no cap for Sentinel/Lattice/Current.
  - Reduced-motion respected for any text-related transitions (e.g., fade-in).

STEP 5 — DELIVER THE FINAL UPDATED tokens.css
Output the complete updated tokens.css as a single fenced code block.
No prose before or after.

CONSTRAINTS
- No font fallback shorter than 3 levels deep (custom -> category -> system).
- No text-transform: uppercase on body text — only on UI labels and eyebrows.
- All sizes use the type-scale tokens. No magic px values in component CSS.
- Honor TYPOGRAPHY's BANNED FONTS list from the archetype spec.

What you get back

A run of Prompt 1 + Prompt 2 against governance.spec.md and harbor.spec.md, with no brand fonts supplied, returns ~150 lines of tokens.css. The shape:

/* Generated from harbor.spec.md + governance.spec.md
   54 tokens · WCAG: 12 ratios verified, 0 flagged
*/
:root {
  /* Surfaces — dark-first per Harbor */
  --color-bg:           #141312;
  --color-surface:      #1A1918;
  --color-surface-2:    #1E1D1B;

  /* Text — 4 levels */
  --color-text:         #F5F4F0;
  --color-text-muted:   rgba(245,244,240,0.70);

  /* Accent — single hue per Harbor's ACCENT STRATEGY */
  --color-primary:      #66D9C2;
  --color-primary-hover: #7EE5D0;
  --color-primary-text:  #141312;

  /* Typography — fluid clamp() per Harbor */
  --font-display: "Instrument Serif", Georgia, serif;
  --font-body:    "Inter", system-ui, sans-serif;
  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
}

[data-theme="light"] {
  --color-bg:           #FAFAF7;
  --color-surface:      #F4F1EA;
  --color-text:         #1A1918;
  /* Override surfaces and text only. Accent and semantic stay constant. */
}

The full file covers about 50–60 tokens for Harbor (semantic-only naming keeps the count compact). Sentinel, with its primitive + semantic two-layer architecture, returns roughly 90–110 tokens for the same spec depth. The token count varies by archetype — what stays constant is the structure: :root primary block + opposite-theme override + WCAG verification.

Layer 3 emerges later, not now

Resist the urge to author component tokens upfront. Layer 3 is best left empty until you've shipped the foundation, composite, and pattern components and seen which values actually repeat. The Layer 3 extraction prompt scans your locked CSS for values used three or more times across components and proposes which ones deserve a component-level token.

That prompt lives in the kit at kit/prompts/10-layer-3-extraction.md and runs as the final step of Chain 1 (Token cascade) or Chain 9 (Greenfield end-to-end). Authoring guidance lands in a later chapter; for now, treat Layer 3 as a "later, not now" concern. Components in Ch04 onwards reference Layer 2 directly.

What's next

Tokens are a contract. The next chapter, Colors & WCAG, unpacks the most fragile part of that contract — color choices that survive both human aesthetic preference and machine-verified contrast. We'll go deeper on the WCAG verification step Prompt 1 emits, document the failure modes that show up most often when readers run their own brand colors through Prompt 1b, and walk the oklch interpolation that derives ramps from a single seed.

Colors & WCAG

Every prompt in this book emits a WCAG contrast table next to its tokens. This chapter unpacks why that table is the single most consequential output — and what the AI is checking when it builds it.

Color is the fastest-failing part of any AI-generated design system. The failure mode is always the same: the brand color looks beautiful in isolation, fails contrast against the surface roles the archetype demands, and ships anyway because nobody read the contrast table the prompt emitted. This chapter is about reading that table — what the numbers mean, what the AI does when a number fails, and how the oklch ramp interpolation in Prompt 1b derives a 9-shade palette from a single hex seed without inventing colors that fail the system.

WCAG fundamentals — the four numbers that matter

WCAG 2.1 specifies four contrast thresholds. Every token pair the AI emits is checked against the right one for its role. Memorize these — they're the only numbers that decide whether your palette ships.

The single most useful number is 4.5:1 — body text against its surface. Most palettes fail here, and almost always at the same place: the brand accent. A saturated mid-tone hex sits visually around #888 in oklch lightness, which means it scores ~3:1 against white and ~3:1 against black. Both fail body text. The rule that drops out of this is the Accent-CTA rule (covered later in this chapter).

Five archetypes, five color strategies

Each archetype encodes its color strategy in its spec. The strategies are deliberately different — what works for editorial reading would suffocate a data terminal.

The strategy is encoded in each archetype's ACCENT STRATEGY and COLOR TOKENS sections. When you ran the dropdown selector in Ch03, you copied the full text of one of these strategies into Prompt 1 — that's how the AI knows whether to emit a 9-step navy ramp (Sentinel) or a single teal hue with four states (Harbor).

Ramp generation — oklch interpolation from a seed

When you supply a brand color via Prompt 1b, the AI doesn't pick the ramp shades — it derives them using oklch interpolation. The seed is the input; the 9-shade ramp is the output. This is the math that makes BYOC palettes feel coherent rather than handpicked.

Why oklch, not HSL or RGB

HSL and RGB are perceptually uneven — a 10% lightness shift in HSL feels different at different hues (yellow gets washed out, blue gets pitch black). Oklch (Oklab Lightness-Chroma-Hue) is perceptually uniform: a 10% L shift looks like a 10% lift to the eye regardless of hue. That makes interpolation predictable.

/* Brand seed: #FF5733 (terracotta) */
:root {
  /* Derived ramp — oklch lightness varies 95% → 15%, hue + chroma stay anchored */
  --primary-50:  oklch(0.95 0.04 29);  /* very light tint */
  --primary-100: oklch(0.88 0.08 29);
  --primary-300: oklch(0.72 0.16 29);
  --primary-500: oklch(0.62 0.20 29);  /* the seed itself ≈ #FF5733 */
  --primary-700: oklch(0.45 0.18 29);
  --primary-900: oklch(0.25 0.12 29);  /* deepest shade */
}

/* Hue (third value: 29°) stays constant — every shade reads as the same brand color.
   Lightness scales linearly. Chroma falls off at the extremes (very light + very dark
   shades have less saturation room — physics of color, not a stylistic choice). */

The two non-obvious moves: chroma falls off at the lightness extremes (a 95% L shade can't hold the same chroma as a 60% L shade — the gamut runs out), and hue stays anchored across the whole ramp (no rainbow drift; every shade reads as terracotta). Prompt 1b applies both rules automatically. If you have a pre-tuned ramp from a designer, paste it as-is and skip the derivation.

The Accent-CTA rule — Sentinel's keystone

The single most common WCAG failure in AI-generated palettes is the Accent-CTA rule. It comes up so often, and breaks so many ramps, that Sentinel's spec encodes it as a hard gate.

Prompt 1b validates the brand seed against this rule explicitly. If your supplied primary fails 4.5:1 against both white and black surfaces, the prompt flags it back with a proposed darker or lighter derived shade rather than silently producing low-contrast tokens. You confirm or override; the prompt does not "fix" without telling you.

Triple encoding — color is never the only signal

About 8% of men and 0.5% of women have some form of color blindness. The implication for design systems: color alone never carries meaning. Every place a color encodes a signal, the system must also encode that signal in icon and text. Three redundant channels, every time.

The governance spec encodes this as a banned pattern: color-only encoding. Lattice strict-enforces it (every status indicator in a data terminal must combine color + icon + text). Sentinel and Current both inherit it. Harbor and Meridian use semantic color so sparingly that the rule rarely binds, but it still applies — a red-bordered callout still needs the icon and the title.

Dark mode as token swap

Per Ch03's three-layer architecture, dark mode is a primitive-only override — semantic aliases stay constant; components stay constant. This is the simplest possible dark-mode pattern, and it's the one Prompt 1 emits by default.

:root {
  /* Primitives — light mode */
  --neutral-50:  #FAFAF9;
  --neutral-900: #1C1917;
  --primary-700: #1B2A4A;

  /* Semantic aliases — these never change between modes */
  --surface-page: var(--neutral-50);
  --text-primary: var(--neutral-900);
  --color-primary: var(--primary-700);
}

[data-theme="dark"] {
  /* Re-point primitives — semantic aliases pick up the new values automatically */
  --neutral-50:  #1C1917;  /* surface flips dark */
  --neutral-900: #FAFAF9;  /* text flips light */
  --primary-700: #7AA8E0;  /* primary lifted for dark contrast */
}

The accent typically does NOT swap — its hue stays the same; only its lightness lifts to maintain contrast on the new surface. Sentinel and Lattice keep their accent constant. Harbor's teal stays teal in both modes. Meridian's link blue lifts slightly for dark mode (#0066CC → #66B3FF) — the same hue, just brighter to clear the dark surface.

Failure modes — what Prompt 1b flags back

The most common BYOC outcomes when readers run their own brand colors through Prompt 1b. Each is a real failure I've seen ship — and each is what the prompt's contrast validation step is checking for.

In every case, the prompt names the failure, proposes a derived or alternative value that does pass, and asks for confirmation. It does not silently substitute. The reason is simple: silent substitution erodes trust. The reader needs to know exactly what changed, why, and approve the change — that's what makes the system auditable.

The contrast table is the deliverable

Every spec page generated by Prompt 08 contains an accessibility verification table — every text-on-surface pair, every accent-on-surface pair, every focus-ring-on-surface pair, computed from the actual token values. If you take one thing from this chapter, take this: the contrast table is the audit trail. It's what proves the palette ships. Stripping it from the spec page is a governance failure, not a stylistic choice.

What's next

Tokens defined and verified is half the work. The other half is making sure designers and engineers are looking at the same source of truth. Chapter 5 — Figma Variables covers how the tokens you just generated land in Figma as Variable collections, how Figma's Dev Mode MCP reads them back into prompts, and the read/write round trip that keeps both ends in sync.

Figma Variables

CSS custom properties and Figma Variables solve the same problem. They are not the same thing — and conflating them is the fastest way to drift between what designers see and what ships.

The three-layer architecture from Ch03 exists in two worlds: the code side (tokens.css) and the Figma side (Variable collections). This chapter maps the architecture onto Figma, shows how the Dev Mode MCP reads from Figma's Variables into Claude-driven prompts, and documents the three sync strategies that keep both worlds from drifting apart.

Variables vs CSS custom properties — the differences that matter

Three collections, three jobs

The primitive → semantic → component architecture from Ch03 maps directly to three Figma Variable collections. Each collection has one job and one set of rules about what it may contain.

Modes — the theme mechanism

Figma Variable modes are the native equivalent of a CSS [data-theme="dark"] block. The key rule is the same in both systems: primitives never change between modes — only semantic aliases change, pointing at different primitives.

/* The same Variable resolves differently per mode */

/* Light mode (default) */
text/primary   →  {Primitives/color/navy/700}   =  #1B2A4A
surface/page   →  {Primitives/color/neutral/50}  =  #FAFAF9
accent/default →  {Primitives/color/accent/500}  =  #FF9900

/* Dark mode (switch the Semantics collection mode on a Figma frame) */
text/primary   →  {Primitives/color/neutral/50}  =  #FAFAF9
surface/page   →  {Primitives/color/neutral/950} =  #0A0E17
accent/default →  {Primitives/color/accent/400}  =  #FFB84D

/* Primitive values never change between modes.
   Only the semantic aliases change — pointing to different primitives.
   Components see the same Variable names in both modes; Figma resolves them. */

How the MCP reads Figma Variables (Path B · Standard)

In Path B (and C), Claude reads directly from the Figma file via the Dev Mode MCP instead of interpreting from specs. The MCP doesn't receive a JSON export — it queries the live Figma file's Variable collections at prompt time, resolving each alias to its mode-specific value.

This is the artifact vs specification distinction from Ch01 playing out in practice. Path A readers run Prompt 1 (spec + adjectives → tokens.css). Path B readers run Prompt 1 in MCP mode (live Figma Variables → tokens.css). Same prompt, different source. Same tokens.css output, different provenance.

What MCP covers — and what it doesn't

MCP handles the Figma → tokens.css direction on demand — you run a prompt, Claude reads the live Variables, emits CSS. That covers one direction of one workflow, triggered by a human. Two things MCP does not cover:

When you need sync outside the AI workflow

For automated continuous sync — running in CI, on commit, or on Figma file save without a human triggering Claude — three options ordered by control vs. setup effort.

Source-of-truth decision

You need to decide once, write it down, and not revisit it for at least six months. Both directions work. The only failure mode is undocumented drift between both.

The naming convention is the contract

Whether you sync via REST API, Tokens Studio, or manually — the naming convention is what makes the sync reliable. Both sides must follow the same rule or the mapping breaks.

/* The rule: replace "/" with "-", prefix with "--" */

/* Figma Variable name  →  CSS custom property */
color/primary/700  →  --color-primary-700
space/4            →  --space-4
text/primary       →  --text-primary
surface/page       →  --surface-page

/* Document this rule in your governance spec.
   Every prompt that reads from Figma uses this mapping.
   Every prompt that emits CSS uses this mapping.
   The naming convention IS the contract. */

What's next

Variables and tokens are color-and-spacing. They say nothing yet about how the text in those surfaces is sized and shaped. Chapter 6 — Typography covers the type scale per archetype — fluid clamp() vs fixed modular, why the distinction matters, how Prompt 2 generates the scale, and what "brand font substitution" means structurally vs what it breaks.

Typography — fluid vs fixed

Harbor uses fluid clamp() scales with serif display italics. Sentinel uses fixed modular scales with sans-only. Lattice caps at 22px. Meridian enforces 17–19px body with 1.75 leading. The scale is not a preference — it is part of the archetype contract.

Prompt 2 (shipped in Ch03 as a paste-ready card) generates the type scale from the archetype spec and any brand font overrides you supply. This chapter explains why the archetype dictates the scale shape, what happens when you substitute brand fonts, and the three failure modes that make typography the most common place where AI-generated systems quietly break.

Fluid vs fixed — five archetypes, two approaches

Why fluid for Harbor and Meridian

Harbor and Meridian both have reading as the primary activity. Fluid clamp() scales let body text expand on large screens (breathing room improves reading) and contract on small screens (no truncation) — in a single declaration, with no media queries and no breakpoints to maintain.

/* Three values: min viewport · preferred (viewport-unit) · max viewport */
--text-hero:  clamp(2.5rem,  1rem + 6vw,  6rem);   /* 40px → 96px */
--text-2xl:   clamp(2rem,    1.2rem + 2.5vw, 3.5rem);  /* 32px → 56px */
--text-base:  clamp(1rem,    0.95rem + 0.25vw, 1.125rem); /* 16px → 18px */
--text-xs:    clamp(0.75rem, 0.7rem + 0.25vw,  0.875rem);/* 12px → 14px */

/* All nine sizes declared once. No breakpoints. No @media. */

Why fixed for Sentinel and Lattice

Sentinel and Lattice are task-focused, not reading-focused. Their primary constraint is pixel-perfect alignment at a specific density. A Sentinel dashboard needs table cells to align across columns; a Lattice terminal needs monospace numbers to stack. Fluid scaling would shift these alignments between viewports. Fixed values are the correct tool.

--text-caption:  11px;   /* metadata, timestamps */
--text-body-sm:  13px;   /* dense UI, helper text */
--text-body:     14px;   /* DEFAULT — every table cell, every form field */
--text-h4:       22px;   /* card title, dialog title */
--text-h1:       34px;   /* page title — maximum in Sentinel */

/* font-feature-settings: "tnum" 1, "lnum" 1 — tabular numerals, required
   on any column of numbers. Variable-width numerals break column alignment. */

Brand font substitution — what works and what breaks

Prompt 2 accepts optional brand font names. The archetype's type-scale shape (fluid vs fixed, ratio, base size, leading) is preserved regardless of what font you supply. Only the family name substitutes. But the substitution has limits — some swaps are safe, others break the archetype.

Prompt 2 validates the supplied font against the archetype's role rules. If you supply a geometric sans as Harbor's display font, the prompt flags it and asks whether you want to override the archetype's editorial signature or pick a different font. It does not silently comply.

Reading-width caps and leading — where typography meets layout

Line length and line height are typographic decisions that live in tokens. They determine reading comfort more directly than font size.

Three failure modes

These are the three typography mistakes AI-generated systems make most often. All three appear in the WCAG verification step of Prompt 1 — if you read the output, these failures announce themselves.

Prompt 2 — where to find it

Prompt 2 (typography scale with optional brand font substitution) ships as a paste-ready card in Ch03's archetype spec section — open the kit in the sidebar, or run it directly from kit/prompts/02-typography-scale.md. The verbatim prompt body validates font role compatibility against the archetype, emits the type scale, and includes a reading-ergonomics check before delivering the updated output/tokens.css. In Chain Mode, brand fonts you noted in Prompt 1 carry forward automatically — Prompt 2 confirms them before applying.

What's next

Colour and type are the first two token categories. Chapter 7 — Spacing & Elevation covers the third: how the spacing scale is structured per archetype (4px base vs 2px base vs platform units), how elevation tokens (shadows, hairlines, surface tints) encode the visual depth model, and the specific combinations that each archetype mandates or bans.

Spacing & elevation

The spacing scale determines how dense or generous a product feels. The elevation model determines how depth is expressed — through background tints, hairlines, or shadows. Both are encoded per archetype, and the archetype's choices are opposite each other.

After tokens.css has colors and typography, the remaining decisions are spatial. This chapter covers the spacing base, naming conventions, radii, and the three elevation strategies — and explains why Sentinel and Lattice are flat where Harbor and Current use shadows, and why that isn't a stylistic preference but an architectural constraint.

Spacing — two bases, five archetypes

The spacing scale is anchored to a base unit. Every step in the scale is a multiple of that base. The choice of base is the archetype's density signal.

Why percentile naming wins at scale

Integer naming (--space-1 through --space-40) feels natural until you need a value between two existing steps. Adding --space-3.5 is awkward; renaming --space-4 onwards is a breaking change. Percentile naming avoids this: --space-50 = 4px, --space-100 = 8px, --space-75 = 6px — inserted later with zero renaming. Sentinel and Lattice use percentile naming precisely because their component libraries grow over time.

/* Harbor — integer naming. Simple, correct for editorial. */
--space-1:  0.25rem;  /*  4px */
--space-2:  0.5rem;   /*  8px */
--space-4:  1rem;     /* 16px — skip 3 because integers are sequential */
--space-6:  1.5rem;   /* 24px */

/* Sentinel — percentile naming. Safe to extend. */
--space-25:   2px;     /* tight icon-text pair */
--space-50:   4px;     /* inline gap */
--space-100:  8px;     /* DEFAULT gap */
--space-200:  16px;    /* card padding */
/* Later, 6px is needed. Insert --space-75 with zero migration. */

Radii — personality encoded in corners

Radii are the most visible spacing decision. Sharp corners (0–4px) signal precision and density. Generous curves (12–24px) signal friendliness and consumer-app character. The archetype's radii spec encodes this personality deliberately — the AI must not override it by defaulting to "modern-looking" rounded corners.

Elevation — three strategies

How does a surface signal that it's "above" another? Three strategies exist, and each archetype picks exactly one. Using the wrong one breaks the archetype's visual logic.

Harbor's warm shadow rule — oklch

Cold black shadows (rgba(0,0,0,0.12)) look sterile against Harbor's warm palette. Harbor derives shadow color from the primary hue using oklch's "from" syntax — the shadow shares the brand's warmth without requiring a separate color decision.

/* Harbor — warm shadow derived from primary hue via oklch */
--shadow-sm:  0 1px 2px   oklch(from var(--color-primary) l c h / 0.08);
--shadow-md:  0 4px 16px  oklch(from var(--color-primary) l c h / 0.12);
--shadow-lg:  0 12px 40px oklch(from var(--color-primary) l c h / 0.18);
/* The `from` syntax reads primary's lightness, chroma, hue —
   modifies only alpha. Shadow inherits warm tint, no new color needed. */

/* Sentinel — cold neutral shadows, floating elements only */
--shadow-0:   none;  /* + 1px --border-default on default surfaces */
--shadow-2:   0 2px 4px   rgba(0,0,0,0.08);  /* dropdown */
--shadow-8:   0 8px 16px  rgba(0,0,0,0.12);  /* dialog, modal */
/* NEVER on default card surfaces — border only */

The forbidden combinations

Three combinations that appear reasonable but break the archetype's visual logic. Prompt 01 applies governance overrides that flag these at generation time.

What this means for Prompt 01

Spacing, radii, and elevation are all in tokens.css — emitted by Prompt 01 (and 01 in Path B). The archetype spec's DENSITY, RADII, and ELEVATION sections drive these decisions. When you paste the spec into Prompt 01, the AI reads those sections and generates the correct scale + shadow model for that archetype automatically. You do not make these choices manually — the spec does.

The governance gate checks: no raw px values in components (must use spacing tokens), no banned radius violations (no pill-rounded Sentinel buttons), no cross-archetype shadow mixing. These run as part of STEP 5 (governance overrides) in Prompt 01.

What's next

The token architecture is now complete: colors (Ch04), typography (Ch06), and spacing/elevation (Ch07). Chapter 08 — Semantic Tokens covers the layer above all of this — how semantic aliases stitch the raw values into a coherent role vocabulary that components can consume without knowing which primitive sits underneath.

Semantic tokens

Primitives are raw values. Semantic tokens are role-based names. The difference is what makes a design system rebrandable in one file edit — and what makes AI-generated components coherent across a hundred screens.

You've seen the two-layer architecture in Ch03. This chapter unpacks the semantic layer in practice — what roles a design system actually needs, how the four universal base semantics extend into domain-specific vocabularies, and why naming tokens by meaning rather than appearance is the single most consequential architectural decision you'll make.

Primitives vs semantics — the practical difference

Components reference semantics, never primitives. That's the rule. When dark mode activates, only primitives flip — semantic aliases keep pointing at the right primitives and components inherit the new values without a single component-level edit.

The four universal base semantics

Every archetype's governance spec requires a minimum semantic trio (success / warning / error). Most also require info. These four names are universal — every team, every product, every archetype uses them. The specific hex behind each varies per archetype (Harbor's success green is warmer than Sentinel's WCAG-verified green) but the role name never changes.

Domain extension — extending without forking

The four base semantics cover most products. Specialised domains (monitoring, analytics, review tools, financial products) need more granular vocabulary. The pattern is always the same: extend by pointing at base semantics or primitives — never by introducing new raw hex values.

/* Base semantic layer — governance.spec.md requirement */
--color-success: var(--color-success-500);
--color-warning: var(--color-warning-500);
--color-error:   var(--color-error-500);

/* Domain extension — severity scale for a monitoring product */
--severity-critical: var(--color-error-700);   /* darker = more severe */
--severity-high:     var(--color-error);      /* aliases base semantic */
--severity-medium:   var(--color-warning);    /* aliases base semantic */
--severity-low:      var(--color-warning-300); /* lighter primitive */
--severity-info:     var(--color-info);       /* aliases base semantic */

/* Now the AI building alert badges uses --severity-critical, not a raw hex.
   Rebrand → primitive updates → severity-critical follows automatically.
   The domain extension chain means no maintenance debt. */

Semantic role vocabulary — per archetype

Each archetype has its own semantic role vocabulary beyond the four base semantics. The names reflect the archetype's use-case — what kinds of surfaces and text roles the system needs.

Prompt 01 emits the semantic layer as part of its :root block. When you paste the archetype spec, the DENSITY, THEME, and TOKEN NAMING sections tell the AI exactly which role names to use. This is why swapping between Harbor and Sentinel produces tokens.css files with completely different semantic vocabulary — not just different hex values, but different architectural shapes.

What's next

The token architecture is complete. Chapters 9–11 are the payoff: each archetype documented as a full reference system — its token decisions explained, its component priorities laid out, its anti-patterns catalogued. Chapter 9 — Harbor is first: the editorial archetype in full.

Harbor — the editorial archetype

Dark-first, single-hue, fluid serif display. The complete reference system for editorial sites, marketing pages, portfolios, and services firms. Structure felt, not seen.

Live Harbor spec preview

The spec — copy and paste

The Harbor spec is what you paste into Prompt 01 (second paste, after governance). Open the Ch03 dropdown, select Harbor, and hit COPY — or grab it from kit/specs/harbor.spec.md. The spec drives every structural decision in the token file the prompt generates.

→ Go to Ch03 archetype dropdown to copy the Harbor spec

Six section templates

Harbor's section vocabulary is finite and deliberate. Any marketing page is an assembly of these six — the AI assembles, never invents a new section type. This is what prevents the drift toward generic SaaS layouts.

Anti-pattern catalog

Harbor bans the patterns AI builders drift toward by default. These are the specific clichés that make generated marketing pages look like templates rather than designed products. Prompt 01's governance-override step enforces these as hard gates.

What Prompts 03–08 produce for Harbor

When to pick Harbor vs other archetypes — see Ch02's failure modes table and the Ch02 decision tree. The rendered spec page is always the fastest way to verify whether the generated system matches Harbor's character before shipping components.

Sentinel — the enterprise archetype

Light-first, compact, primitive + semantic two-layer architecture. The complete reference system for dashboards, monitoring tools, admin products, and B2B SaaS. Clear, helpful, respectful of expertise.

Live Sentinel spec preview

The spec — copy and paste

The Sentinel spec is what you paste into Prompt 01 (second paste, after governance). Open the Ch03 dropdown, select Sentinel, and hit COPY — or grab it directly from kit/specs/sentinel.spec.md. The two-layer token architecture, the Accent-CTA rule, and every structural decision in the generated token file come from this spec.

→ Go to Ch03 archetype dropdown to copy the Sentinel spec

The Accent-CTA rule — Sentinel's keystone

Sentinel's anchor orange (#FF9900) scores 2.30:1 against white — a WCAG FAIL for body text. Against dark text (#1C1917) it scores 7.0:1 — AAA. The rule that drops out: --color-accent-500 is a background color only. Never a text color on a light surface. Primary CTAs are always orange-bg + dark-text. White-text-on-orange is banned everywhere in the system.

Prompt 01 applies this as a governance gate. If you supply a BYOC seed that fails this same test, the prompt flags it before emitting a single token. This is the single most important WCAG behavior the prompt enforces for Sentinel.

The data table — Sentinel's signature component

Sentinel's most architecturally distinct component is the data table. It encodes everything the archetype stands for: tabular numerals, compact row height, keyboard navigation, column resize, column reorder, bulk-action bar, virtualized rendering for 1000+ rows. Prompt 03 generates this as part of the foundation set. The table inherits all Sentinel token rules — fixed 14px type, percentile spacing, hairline border, semantic color for status columns.

Anti-pattern catalog

What Prompts 03–08 produce for Sentinel

The specialist archetypes

Harbor and Sentinel cover 60–70% of products. Current (mobile-first), Lattice (data-dense), and Meridian (long-form reading) cover the cases where neither generalist archetype fits — and where forcing one onto the wrong use case costs more than not picking.

The specialist archetypes share the same generation pipeline as Harbor and Sentinel. Paste governance + archetype spec into Prompt 01, run Prompts 02–08 in sequence. What changes is the spec — and the spec changes everything.

Current — mobile-first consumer

The specs — copy and paste

Each specialist archetype has its own spec in the Ch03 dropdown and in the kit. Copy yours before running Prompt 01.

Current is the only archetype where the primary input device is a thumb, not a cursor. Every architectural decision follows from that constraint.

The Current spec also defines six screen layouts (Tab Bar Shell, Stack Navigation, Bottom Sheet, Full-Screen Takeover, Onboarding Wizard, Empty State) as the only layouts Prompt 05 assembles into. The AI is constrained to these six — it cannot invent a seventh. This is the same vocabulary constraint Harbor applies to section templates.

Live Current spec preview

Lattice — data-dense terminal

Lattice is the inversion of Meridian. Where Meridian maximizes comprehension, Lattice maximizes density. Every pixel earns its place. The density doctrine is the architectural keystone — every decision passes through it.

Live Lattice spec preview

Meridian — long-form reading

Meridian is the only archetype where body text is the hero. Everything else exists to serve reading — and reading has well-documented ergonomic thresholds that this archetype enforces as governance gates, not preferences.

Live Meridian spec preview

Hybrid products — when one archetype isn't enough

Most real products have surfaces that span two archetypes. The governance spec documents the five canonical hybrid patterns:

A note on the product names below: these are illustrative references to publicly-recognisable products that exemplify each hybrid pattern, not endorsements or partnerships. The named products almost certainly do not describe themselves using this book's archetype vocabulary; the mapping is observational, applied here to make the patterns concrete. Trademarks are property of their respective owners.

The universal hybrid rule: keep token files separate. Each archetype owns its own semantic layer, typography scale, density scale, component priority order, and banned patterns. What you share across archetypes is exactly: brand primary hex, high-level voice principles, and universal governance gates.

What Prompts 03–08 produce for specialist archetypes

Component specification

When you spec a component, you are not describing pixels. You are writing an API contract. The AI builds from the contract, not from what the component looks like.

Prompts 03–05 generate components from the archetype spec and tokens.css. The archetype spec tells them which components to build; the tokens tell them which values to use. This chapter covers what makes a component spec complete enough for the AI to get it right the first time — and what Figma Component Properties add when you're on Path B.

Five elements of a complete component spec

A component spec is complete when it answers these five questions. Leave any one out and the AI fills the gap from training-data defaults — which means the statistical average of the web, not your archetype.

The archetype spec's component library section (which Prompt 03 consumes) pre-fills all five elements per component per archetype. You don't author the spec from scratch — you paste it. The AI executes from the spec's contract.

Figma Component Properties — the API contract for Path B

On Path B, Claude reads component specs directly from Figma via MCP. Figma Component Properties are the structured format that makes this work — they encode the logical structure of a component (what props it has, what types they are) separate from the visual renders. The AI reads properties directly rather than inferring structure from screenshots.

Four property types, each with a direct TypeScript equivalent:

Button worked example — properties → TypeScript → Storybook

Six properties. One Figma component. Three outputs (TypeScript interface, Storybook argTypes, CSS implementation) all derived from the same source without manual transcription.

/* Properties defined in Figma:
   variant      Variant  "primary | ghost | destructive | accent"
   size         Variant  "sm | md | lg"
   label        Text     "Save changes"
   icon         Instance Swap  → Icon component
   iconPosition Variant  "left | right"
   loading      Boolean  false                                 */

interface ButtonProps {
  /** Visual role — maps to Figma variant "variant" */
  variant?: "primary" | "ghost" | "destructive" | "accent";
  /** Touch target size — maps to Figma variant "size" */
  size?: "sm" | "md" | "lg";
  /** Label — maps to Figma text property "label" */
  children: React.ReactNode;
  /** Icon slot — maps to Figma instance swap "icon" */
  icon?: React.ReactNode;
  /** Icon placement — maps to Figma variant "iconPosition" */
  iconPosition?: "left" | "right";
  /** Loading state — maps to Figma boolean "loading" */
  loading?: boolean;
  onClick?: (e: React.MouseEvent) => void;
}

Component build order

Prompts 03–05 run in a strict order. Each tier composes from the tier below — never the reverse. A composite component (Modal) must not be built before the foundation components it needs (Button, Icon) exist.

What's next

Chapter 13 — Layout Patterns covers how components assemble into layouts — the responsive rules, the container-width tokens, and why each archetype has its own finite layout vocabulary the AI must respect.

Once components are generated (Prompts 03–07 via Chain 3), Prompt 14 drives Chain 6 — Storybook Generation to produce living documentation: one *.stories.tsx per component with every variant, every state, and a11y annotations wired in. The component spec from this chapter becomes the Storybook story tree without a manual transcription step.

Layout patterns

Don't let the AI invent layouts. Give it a finite vocabulary — then it assembles rather than creates, and the result reads as a designed system, not a generated template.

Every archetype's spec defines a closed set of layout shapes. Harbor has 6 section templates; Sentinel has 6 application layouts; Current has 6 screen types; Lattice has 6 workspace configurations; Meridian has 6 document layouts. The AI picks from this set. It never invents a seventh. This is how you get design-system-coherent layouts rather than layout drift.

Container widths and breakpoints as tokens

Every layout decision traces back to two types of tokens: content widths and breakpoints. When these are encoded as tokens rather than inline values, the AI uses the same number everywhere — and changing the system means changing one token, not grepping 200 CSS files.

/* Content widths — per archetype (example: Harbor) */
--content-narrow:   640px;   /* reading column, pull quotes */
--content-default:  960px;   /* articles, value rows */
--content-wide:     1200px;  /* case studies, hero compositions */
--content-max:      1440px;  /* full-bleed compositions */

/* Breakpoints — shared across archetypes (Harbor/Sentinel) */
--bp-mobile:        390px;   /* Current's primary target */
--bp-tablet:        600px;
--bp-desktop:       900px;
--bp-wide:          1200px;

/* If you ever change a breakpoint, one token edit updates every component.
   If the AI uses 898px in one component and 900px in another, those are
   two different breakpoints — and that is how design systems die. */

Layout vocabulary — five archetypes, five vocabularies

Each archetype's layout vocabulary reflects its primary use case. Harbor sections are about editorial rhythm. Sentinel layouts are about application chrome. Current screens are about mobile navigation patterns. Lattice workspaces are about pane configurations. Meridian documents are about reading experiences.

Prompt 05 (Pattern components) generates archetype-aware page patterns from this vocabulary. When you paste the Sentinel spec, Prompt 05 generates the Dashboard layout, the List + Detail layout, and the Focus Mode layout — because the spec encodes those as the expected patterns. You don't specify them explicitly. The vocabulary is in the spec.

Responsive: column collapse rules per archetype

What's next

Chapter 14 — Design Patterns covers the smaller-scale patterns: how components combine into cards, forms, feedback states, and empty states — and why defining patterns by composition rather than screenshot is what makes AI-generated patterns reliable.

Design patterns

Patterns are how components combine into recognisable interactions. Define them by composition — which components, in what arrangement — not by what they look like. The AI can reassemble components; it cannot reliably reverse-engineer screenshots.

Card patterns

Cards are the most common pattern AI builders get wrong. The failure mode is always the same: the AI defaults to a generic "card with shadow and image" because that's the most common pattern in training data. Archetype specs ban or mandate specific card shapes precisely because of this drift.

Form patterns

Forms are where the most a11y failures happen in AI-generated systems. Three rules enforced by every archetype's governance spec:

Feedback patterns

Loading, empty, error, and success states are the patterns most commonly skipped in first-pass AI generation. When the archetype spec is pasted into Prompt 03–05, these states generate automatically as part of every component's state coverage. The governance spec requires all eight states for every interactive component.

What's next

Chapter 15 — Figma + AI Foundation opens Act V: the Figma integration layer. This is where the book shifts from token and component theory to the MCP workflow that reads from — and writes back to — the living Figma file.

Component-to-archetype mapping

The same component is not the same component. Three primitives — Button, Card, Form field — implemented across all five archetypes, with the spec rule that drives each difference made visible. After this chapter, you can read any component in any archetype and predict what its variants will look like before you generate it.

Chapters 12–14 covered the doctrine: API-contract specs, finite layout vocabularies, composition over screenshots. This chapter is the worked example. Same primitive, five archetype implementations, side-by-side. The point is not to memorize the differences — it is to internalise that the archetype IS the difference. When you paste a different archetype spec into Prompt 03, the same component prompt produces different code, and that's by design.

Worked example 1 — Button

Button is the highest-frequency component. Each archetype's Button reflects its core value system: Harbor's editorial restraint, Sentinel's accent-CTA convention, Current's touch ergonomics, Lattice's keyboard-first density, Meridian's reading-paged minimalism.

Note what shifts and what does not. Every archetype has the same three semantic Button roles (primary, secondary, tertiary) but the visual encoding differs. The prop API stays consistent — `variant`, `size`, `disabled`, `loading` — so a component consumer never needs to know which archetype it's in. The archetype is invisible at the API surface and decisive at the rendering layer.

Worked example 2 — Card

Card is where Act IV's "composition not screenshot" doctrine pays the most. Cards are the most common AI failure mode (training data defaults to a generic shadow + image card). Archetype specs explicitly mandate or ban specific card shapes — that is the only thing that prevents drift.

Worked example 3 — Form field

Form fields are where a11y bans matter most. Every archetype's governance section bans floating labels, color-only error states, and asterisk-only required indicators — but the visual treatment differs:

Three things stay constant across all five archetypes: labels above inputs (never floating), error message follows the What → Why → How formula (Ch14), and color is never the only signal (icon + border + text always combined). These are governance gates, not archetype choices — they apply universally.

Reading any archetype's component list

The pattern: every archetype's spec has a COMPONENT LIBRARY section listing the components in priority order. The order itself is meaningful — Lattice lists Data Grid before Modal because it's used 50× more often in a terminal product; Harbor lists Hero before Modal for the same reason in editorial. When you read a new archetype, scan the component list before the rules. The list tells you what the archetype is for; the rules tell you what it forbids.

What's next

That closes Act IV. Chapter 15 — Figma + AI Foundation opens Act V: how the Figma Dev Mode MCP turns these specs into living code via the read/write bridge. If you're on Path A (no Figma), skip Act V and go to Ch20.

Figma + AI foundation

Figma Dev Mode MCP is the bridge between your design system and any AI builder. Before MCP: you described a Figma file to Claude in prose and hoped. After MCP: Claude opens the file itself, reads the actual token values, inspects the actual component tree, and builds code that matches exactly.

This chapter is the foundation for Act V (Ch15–19). It covers what MCP is and does, how to verify the connection, what MCP unlocks beyond just reading token values, and what to expect in terms of output accuracy.

Which path are you on?

The three paths were introduced in Ch00. This table is the practical routing: what you have, what you produce, and where to go from here.

What MCP is

MCP (Model Context Protocol) is a standard that lets an AI model communicate with external tools — read files, call APIs, query databases. The Figma Dev Mode MCP is Figma's official implementation: it lets Claude read and write Figma files directly, without screenshots or manual token transcription.

This book covers a single MCP: the Figma Dev Mode MCP (official). Not open-source community servers. Every prompt and workflow in Ch15–19 is verified against Figma's vendor-supported implementation.

Read capabilities vs write capabilities

Accuracy depends on input quality

How much structured information you provide to Claude determines how close the output is to your design intent. This is not a limitation of the model — it is a structural reality. More signal → less inference → fewer gaps filled with training-data defaults.

Setup requirements

Verifying the connection — diagnostic prompt

Before running any Figma-dependent prompt, confirm the MCP is connected and responding. Paste this diagnostic into your MCP-enabled Claude session:

MCP CONNECTION DIAGNOSTIC — Figma Dev Mode MCP

List all Figma MCP tools you have access to.

For each tool, report:
1. Tool name
2. What it does (one sentence)
3. Required parameters
4. Optional parameters

Then confirm:
  - Is the Figma MCP server connected and responding?
  - Is a Figma file currently open in the Desktop app?
  - If yes: what is the file name and file key?

If no tools are listed, the MCP server is not connected.
Check: (a) Figma Desktop is running, (b) Dev Mode is enabled,
(c) your AI client's MCP configuration points at Figma's
local server URL, (d) you have restarted your AI client
since updating the MCP config.

What MCP unlocks beyond setup

"Connect Claude to Figma" sounds like a single capability. It is not — it is a layer underneath six distinct workflow capabilities, each addressed by a specific chain in the kit. The reason MCP is the headline of Act V is that each of these would otherwise require copy-paste, screenshots, manual transcription, or a custom plugin.

The MCP read/write layer is what makes the rest of Act V work. Ch16 (Three-Phase Workflow) uses it for token extraction. Ch17 (Claude Design) uses it for spec validation in Workflow B. Ch18 (Figma → Code) is the production output of MCP reads. Ch19 (Code → Figma) closes the round-trip via MCP writes. Without MCP, every chapter in this act becomes "paste a screenshot and hope."

What's next

Chapter 16 — The Three-Phase Workflow maps out the full Path B execution: Phase 1 (Figma → MCP → tokens), Phase 2 (tokens → components → patterns), Phase 3 (audit, write-back, drift monitoring). The MCP connection verified here is what the rest of Act V depends on.

The three-phase workflow

STUDY first. GENERATE second. REFINE third. Every AI design-to-code workflow that skips a phase produces mediocre results. The three-phase structure is not a preference — it's the minimum architecture for consistent fidelity.

Most teams ask the AI to "build this from Figma" in a single prompt and get something that's 70% right. The fix is to split the work into three sequential prompts, each with a different job and a different output artifact. The spec from Phase 1 constrains Phase 2. The comparison from Phase 3 is surgical, not vague.

The three phases

Phase 1 — STUDY prompt

The study prompt does the extraction. Run it with Figma Dev Mode MCP connected. The output is a structured spec document — not code. Explicitly block code generation in the prompt itself.

PHASE 1 — STUDY: Extract design specification

Study this Figma file: [FIGMA_URL]

Before writing any code, output a complete design specification
with these sections:

1. COLOR PALETTE
   - Every unique color with exact hex value
   - Usage role for each (background, text, border, accent, etc.)
   - Grouped into: primitives and semantic roles

2. TYPOGRAPHY SCALE
   - Every unique font size with exact value (no rounding)
   - Font-family, weight, line-height, letter-spacing per style
   - Suggested token name for each

3. SPACING MAP
   - Every unique spacing value (padding, margin, gap) in exact px
   - Grouped into a suggested token scale

4. COMPONENT INVENTORY
   - Every distinct component visible
   - Variants present, sizes used, interactive states visible

5. EFFECTS
   - Shadow values (x / y / blur / spread / color, exact)
   - Border radii used (exact px values)
   - Any transitions or animations

6. LAYOUT STRUCTURE
   - Container widths
   - Grid structures
   - Breakpoints inferable from source

Output as structured markdown with exact values throughout.

CRITICAL: Do NOT write any code. Do NOT suggest improvements.
Extract only what exists with exact values — no approximations.

Phase 2 — GENERATE prompt

PHASE 2 — GENERATE: Build code from Phase 1 specification

Spec from Phase 1: [paste Phase 1 output here]

Tech stack:
  Framework: [React + TypeScript | Vanilla HTML/CSS | Vue | Svelte]
  Styling: [CSS custom properties | Tailwind]
  Existing components at: [path, if any]
  Token file at: [path, if any]

Rules:
1. Use EXACT values from the spec. No rounding, no "approximately".
2. Define all colors and spacing as CSS custom properties in :root,
   grouped by category.
3. Every component references tokens via var(), never raw values.
4. Include hover, focus-visible, and disabled states for all
   interactive elements.
5. Use semantic HTML (button for buttons, not div with onclick).
6. Add aria-labels where visible text is absent.
7. Respect prefers-reduced-motion for any animation.
8. Do not improvise values not in the spec. If something is unclear,
   flag it with a comment and use the closest spec value.

Output: component code with tokens at top, component below.
No inline styles. No raw hex values in components.

Phase 3 — REFINE prompt

PHASE 3 — REFINE: Surgical corrections only

Apply these corrections to the code. Modify ONLY what is listed.
Do not refactor, rename, or "improve" anything not on the list.

Format: [Element]: [property] is [current] → should be [value]

Corrections:
- [element]: [property] is [current] → should be [value]
- [element]: [property] is [current] → should be [value]
- [element]: [property] is [current] → should be [value]

Rules:
1. Make ONLY the changes listed.
2. Do not refactor or improve other code.
3. Do not "fix" other issues you notice — add them to a separate
   NOTE section if they are important, but do not change them.
4. Keep all existing structure intact.
5. Return the corrected code, not a diff.

Output the updated file(s).

Closing the round-trip — Figma write-back

Phase 3 ends with the code corrected against the Figma source. But the inverse is also true: when REFINE updates a token value (e.g., a button's border-radius is fixed in code), Figma now drifts behind code. Chain 8 — Figma write-back closes that gap. Run Prompt 15 after a REFINE pass that materially changed token values; it reads the updated tokens.css, reconciles against the Figma variable library via MCP write access, and updates Figma to match. The three-phase workflow is then a complete round-trip — Figma → code → Figma — with code as the source of truth at the end of every cycle.

Claude Design

A full design critique, a rendered HTML prototype, and five rounds of layout iteration — from a description, a screenshot, and a spec, inside a single persistent session. Claude Design is the fastest first mile in any design system workflow. This chapter is the operating manual.

The seam with Figma is real and intentional: Claude Design handles speed, exploration, and critique; the Figma-first workflow (Ch15–16) handles artifact-level consistency at scale. These two compose — and every improvement to Claude Design makes both sides of the composition more powerful. This chapter covers what that composition looks like in practice, using Claude's full 2026 capability set.

What Claude Design is in 2026

Six capabilities that define Claude Design's current power profile. No limitations in this list — scope comes next.

Full capability profile

The seam between Claude Design and Figma is a handoff point, not a deficiency. Left: what Claude Design does natively. Right: where the Figma source of truth takes over.

Projects — persistent design system context

The most consequential 2026 capability for design system work. A Claude Project stores files as persistent knowledge — the spec, the tokens, the governance rules — and every conversation inside the Project inherits them without repasting. For recurring design system work, this eliminates the single biggest friction in the workflow.

PROJECT SYSTEM PROMPT — design system context

Product: [product name]
Archetype: [Harbor | Sentinel | Current | Lattice | Meridian]
Design system version: [e.g. v1.2]

Context loaded in Project knowledge:
  - governance.spec.md (universal quality gates)
  - [archetype].spec.md (archetype-specific rules)
  - tokens.css (generated token output)

Your role in this Project:
You are a design system specialist working within the
[archetype] archetype. All generated components, critiques,
and recommendations must reference tokens from the loaded
tokens.css. All governance rules from governance.spec.md
apply unconditionally. Archetype-specific rules from
[archetype].spec.md override general defaults where
they conflict.

When generating HTML/CSS:
  - Use CSS custom properties from tokens.css, never raw values
  - Respect the archetype's spacing base, radii, and motion rules
  - Flag any request that would violate governance gates

When critiquing:
  - Reference specific token names, not just values
  - Use the severity system: Critical / Major / Minor
  - State the expected token alongside the observed value

Artifacts — rendered output in the browser

Artifacts transforms the Workflow A first mile. Before Artifacts, "Claude Design generates a mockup" meant Claude wrote code you had to copy, run locally, and screenshot. With Artifacts, the rendered output appears immediately in the claude.ai interface — viewable, shareable, screenshottable without leaving the conversation.

RENDERED MOCKUP — Artifact output

[If not in a Project: paste governance.spec.md and
[archetype].spec.md here before this prompt.]

Component / screen to generate:
  [describe the component or screen]

Requirements:
  - Output as a complete, self-contained HTML file
  - Use only CSS custom properties defined in the loaded
    tokens.css (or pasted :root block)
  - No raw hex, no magic numbers in CSS — all values via var(--token)
  - Dark mode by default (if archetype is dark-first)
  - Include all interactive states visible at once
    (default, hover, focus, disabled) using adjacent variants
    in the layout — not JS toggle

Archetype constraints to enforce:
  - Spacing: [archetype]'s spacing base (2px | 4px | 8px)
  - Radii: [archetype]'s radius set (do not use pill if Lattice)
  - Typography: [archetype]'s type scale (fixed px if Lattice/Sentinel)
  - Motion: [archetype]'s duration tokens (instant if Lattice)

Output the HTML as an Artifact so it renders in the preview panel.

Extended Thinking — when to engage it

Extended Thinking makes Claude reason step-by-step through a problem before producing output — surfacing the constraint chain so you can audit the logic, not just the result. It costs significantly more time and tokens than standard mode. Use it deliberately.

LAYOUT ARCHITECTURE — Extended Thinking

[Paste spec blocks if not in a Project]

Screen: [name and purpose of the screen]

Constraints — resolve all of these simultaneously:
  Responsive: [list breakpoints, e.g. 375px / 768px / 1280px]
  Components: [list nested component types, e.g. data table, filter bar,
               detail drawer, command palette]
  Token rules: [key constraints, e.g. Lattice 2px spacing base,
                flat elevation only, 32px row height default]
  Accessibility: [e.g. keyboard-navigable, WCAG AA contrast,
                  skip-link required]
  Layout archetype: [e.g. W1 Multi-Pane, W2 Full-Table — from spec]

Think through each constraint before proposing the layout:
  1. Which layout workspace template applies? Why?
  2. Which constraints are in tension? How do you resolve each conflict?
  3. What component hierarchy satisfies all constraints simultaneously?
  4. What would break at the narrowest breakpoint — and how do you
     prevent it within the archetype's rules?

Then produce the layout as an Artifact (rendered HTML/CSS).

Model selection — matching the task to the tier

Claude's three tiers (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) differ in reasoning depth, speed, and cost. Opus is not always better — for critique and iteration loops, Sonnet 4.6 produces equivalent results at a fraction of the latency. Default to Sonnet 4.6; reach for Opus 4.7 when you need architectural depth.

Multi-image vision — cross-screen consistency

Per-screen critique never catches inter-screen drift. If screen 3 uses --space-200 for card padding and screen 7 uses --space-300, a single-screenshot critique of each passes them both individually. Only a simultaneous multi-image critique catches the inconsistency.

Three workflows — updated for 2026

Prompt reference — all Claude Design workflows

Five prompt cards for the full workflow set. The Project setup prompt runs once. The rest run per-task.

Prompt card 1 (Project setup) is in the Projects section above. Cards 2–5 follow.

CROSS-SCREEN CONSISTENCY AUDIT

Archetype: [Harbor | Sentinel | Current | Lattice | Meridian]
Screens attached: [list screen names, e.g. Dashboard, Detail, Settings]
Token system:
  [paste :root block from tokens.css — or load from Project]

PART 1 — Per-screen issues
For each screen, check every visible element for:
1. COLOR — raw hex not in token system
2. SPACING — gaps or padding not on the archetype grid
3. TYPOGRAPHY — font size, weight, or family outside the scale
4. BORDER RADIUS — value not in the archetype's radius set
5. ANTI-PATTERNS — any pattern from the archetype's banned list

Output: ranked issue list per screen
  Critical / Major / Minor
  Format: [screen] · [element] · [property] · [observed] → [expected token]

PART 2 — Consistency matrix
Compare all screens against each other for:
- Shared component types (e.g., all tables, all nav headers, all modals)
- Token application consistency (does the same element use the same
  token across screens, or does it vary?)
- Pattern consistency (same interaction pattern coded the same way?)

Output: a table with rows = component type, columns = screen name,
cells = CONSISTENT / INCONSISTENT + note on the inconsistency.

VERDICT (one per screen + one overall):
  PASS / FIX BEFORE CODE / REWORK
Overall: CONSISTENT / DRIFT DETECTED (list cross-screen issues)

The durable integration pattern

Every improvement to Claude Design strengthens the workflow on both sides of the seam. Better generation makes Workflow A's first mile faster and closer to spec. Better critique makes Workflow C's quality gate more precise and catches more drift before code ships. The system's value comes from the composition — a spec-loaded Project, rendered Artifacts, and a multi-image critique loop is significantly more capable than any one of those parts alone.

The next chapter (Ch18 — Figma → Code) picks up where Workflow A's Artifact handoff ends: the Figma component is built, the archetype tokens are applied, and the MCP workflow takes over to generate production code from a canonical source of truth.

Figma → Code

Five specialized prompt templates for turning Figma designs into production code. Each handles a different starting condition: pixel-perfect clone, framework migration, token extraction, or surgical refinement.

Scenario matching — which prompt when

Canonical Figma → React template

The base template for Path B. Adapts to any framework — swap the framework/styling lines. The six elements (source pointer, context block, numbered task list, output format, critical rules, content slot) are the architecture every design-to-code prompt should inherit from.

Read this Figma file: [FIGMA_URL]

Context:
  Framework: React with TypeScript
  Styling: CSS custom properties (tokens.css at src/tokens.css)
  Existing components at: src/components/ui/
  Design tokens at: src/tokens.css

Please:
1. Convert the "[FRAME_NAME]" frame to a React component
2. Use existing components where they match (check src/components/ui/)
3. Preserve all spacing using the token scale in tokens.css
4. Extract any new colors as CSS custom properties if not in tokens.css
5. Make it responsive (mobile-first, use archetype breakpoints)
6. Add meaningful TypeScript interface with prop names

Output format:
  - Single .tsx file, TypeScript interface at top
  - Named export for the component
  - New CSS custom properties appended to tokens.css (if any)
  - Short JSDoc comment explaining the component's role

Rules:
  - Use var(--token-name) for all values. No raw hex or magic numbers.
  - Semantic HTML: button for buttons, nav for nav, etc.
  - Every interactive element has hover, focus-visible, disabled states.
  - aria-label on any icon-only element.

Token extraction prompt

Run this before component work on any Figma file that has Variable collections. Produces tokens.css + (optionally) tailwind.config.js in one pass. This is the Path B equivalent of Prompt 01 in Path A — but it reads from the live Figma artifact rather than generating from the archetype spec.

Read the Figma file and extract every design token.

Source: [FIGMA_URL]

Output two files:

1. src/tokens.css
:root {
  /* Colors — grouped by role */
  --color-primary-50: #...;
  /* ... */

  /* Typography */
  --text-xs: clamp(...); /* or fixed px per archetype */
  /* ... */

  /* Spacing, radius, shadow, motion */
}

[data-theme="dark"] {
  /* Primitive overrides only — semantic aliases stay */
}

2. (Optional) tailwind.config.js — only if project uses Tailwind
   Extend theme so utilities map to tokens:
   colors: { primary: { 50: 'var(--color-primary-50)' } }
   spacing: { 1: 'var(--space-1)' }

Rules:
- Extract EXACT values. No rounding.
- Group semantically per the archetype TOKEN NAMING section
- Include a brief comment for non-obvious tokens
- Do NOT generate components. Token extraction only.
- Flag any WCAG contrast failures in a comment (WCAG AA = 4.5:1 body text)

Pixel-perfect clone with token enforcement

Scenario A from the routing table. Use when the Figma frame is the contract — a designer-approved hi-fi mock that must ship at byte-level fidelity. The trick is enforcing tokens while preserving exact visual output. Without enforcement, the AI freelances; with it, the AI maps every value to a token or flags it as a deliberate one-off.

Read this Figma frame and produce pixel-perfect HTML/CSS.
The frame is canonical — match it exactly, do not reinterpret.

Source frame: [FIGMA_URL]
Token system: src/tokens.css (paste full :root block below)
Archetype: [Harbor | Sentinel | Current | Lattice | Meridian]

Token enforcement rules — ZERO exceptions:
1. Every color value → var(--color-token-name) from tokens.css.
   If a color in Figma does not exist in tokens.css, DO NOT use it.
   Flag it: "[element]: Figma value #ABCDEF has no matching token.
   Closest match: var(--color-...). Use match? OR add new token?"

2. Every spacing/radius/shadow → var(--space-N) / var(--radius-N) /
   var(--shadow-N). Off-grid values flagged the same way.

3. Every typography value → match exactly to the type scale tokens.

4. Every transition → use --duration-* + --easing-* tokens.

Output format:
- HTML structure matching Figma layer hierarchy
- CSS using tokens only — no raw values anywhere
- A comment block at the top listing every flagged divergence
  ("Differs from spec at: [element], [property]")

Critical rule: do NOT silently fix divergences. List them. The
designer decides whether each is a one-off or a token addition.

Framework migration — Tailwind to vanilla CSS via Figma source

Common scenario: a codebase shipped in Tailwind, the design system is moving to vanilla CSS with custom properties (or the reverse). Use the Figma file as the canonical reference and migrate component-by-component. The key is to NOT translate Tailwind classes literally — use Figma as the source of truth for what each component should look like, then write fresh CSS against tokens.

Migrate this component from [SOURCE_FRAMEWORK] to [TARGET_FRAMEWORK].
Use the Figma file as the canonical source — not the existing code.

Existing component: [paste source code]
Source framework: [Tailwind | styled-components | CSS modules | vanilla]
Target framework: [Tailwind | styled-components | CSS modules | vanilla]
Figma source: [FIGMA_URL] · frame: [FRAME_NAME]
Token system: src/tokens.css (paste below)

Steps:
1. READ the Figma frame and extract its design intent
   (spacing, typography, color usage by role).
2. IGNORE the existing component's literal class names.
   They may carry baggage from old conventions.
3. WRITE fresh code in the target framework using:
   - Token references from tokens.css (not raw values)
   - Semantic HTML matching the Figma layer hierarchy
   - Component states (hover, focus-visible, disabled)
     even if not visible in Figma's default state
4. PRESERVE the existing component's prop API surface
   (props in → props out the same), so consumers don't change

Output:
- New component file in target framework
- Migration notes: what changed, what stayed
- List of any tokens that need to be added to tokens.css
- Test surface: what props/states should be exercised post-migration

Do NOT translate class-by-class. Re-derive from Figma + tokens.

Refactor a legacy component to match the archetype spec

The component shipped before the spec existed. It works, but it doesn't follow the archetype's banned patterns, governance rules, or token naming. Use this prompt to refactor it into compliance without changing its behavior. The output is a drop-in replacement that passes Chain 4 (drift audit) and Chain 5 (a11y audit).

Refactor this legacy component to comply with the archetype spec.
The behavior must stay identical — only the implementation changes.

Legacy component: [paste source code]
Archetype: [Harbor | Sentinel | Current | Lattice | Meridian]
Specs (paste both):
  governance.spec.md: [paste]
  [archetype].spec.md: [paste]
Token system: src/tokens.css (paste)

Refactor rules:
1. Replace every raw value with the matching token from tokens.css.
   If no matching token exists, propose a new one and add it inline.
2. Apply the archetype's banned patterns list — anything banned that
   the legacy code uses must be removed and replaced.
3. Apply governance state coverage: every interactive element must
   have default / hover / focus-visible / active / disabled.
4. Apply governance copy hygiene: remove "Please", marketing fluff,
   "Submit"/"OK" buttons, etc.
5. Apply ARIA correctness — aria-label on icon buttons, aria-expanded
   on disclosure widgets, aria-live for async messages.
6. Keep the prop API EXACTLY as it was — consumers must not break.

Output:
- The refactored component (drop-in replacement)
- A diff summary: what was banned, what was added, what was renamed
- A short test plan: which props/states to verify post-refactor
- A note on whether prop renames are needed (if so, provide a
  deprecation shim so the old API works for one MINOR version)

Run Chain 4 (drift audit) and Chain 5 (a11y audit) after refactor.
Both must pass with zero Critical findings before merging.

Code → Figma

The less-common direction, but powerful: push an existing codebase back into Figma as a living component library. Three use cases, a six-phase pipeline, and one essential artifact — the component mapping report.

When to reverse the pipeline

The six-phase reverse pipeline

Component mapping report prompt

Analyze my existing codebase and the target Figma file.
Produce a component mapping report.

Codebase: [paste components or file path]
Target Figma library: [FIGMA_URL]

Output three sections:

1. DIRECT MATCHES
   Code components that exist identically in the Figma library.
   For each: code path → Figma library path

2. PARTIAL MATCHES
   Code components that exist in Figma but are missing variants
   or states. For each:
   - What exists in Figma
   - What is missing
   - Recommended action

3. FIGMA ASSEMBLY SPEC
   Components in code that do not exist in Figma at all.
   For each, specify:
   - Name and target location in Figma library
   - Auto-layout direction (horizontal | vertical | grid)
   - Padding, gap, sizing constraints (exact px)
   - Child component hierarchy as ASCII tree
   - Variants to create (if any)

Rules:
  - Preserve exact naming conventions from the codebase
  - Use Figma auto-layout terminology (not CSS flexbox)
  - All measurements in px (Figma native)
  - Do NOT modify Figma yet. This is planning only.

Review the report with the designer before any writes.

Operational write-back — Chain 8 + Prompt 15

The mapping report above is the planning artifact. The execution is Chain 8 — Figma write-back, powered by Prompt 15. Where the mapping report tells you what needs to be added or changed, Chain 8 actually performs the writes — variable by variable, with a reconciliation table you confirm before any change reaches Figma.

When to use which: the mapping report (above) is for the first round when Figma has gaps and you need a designer review before any writes. Chain 8 is for ongoing maintenance — quarterly token sync, post-release reconciliation, BYOC palette updates that need to flow back to Figma. Together they cover both the discovery and the operational sides of the Code → Figma direction.

Path A — the code-first pipeline

No Figma file. Three brand adjectives. Fourteen prompts chained in sequence. Final output: a shippable design system with tokens, components, patterns, chrome, and a live spec page. Estimated runtime: 45–90 minutes on first pass.

Path A is Chain 9 in the kit. The fastest way to run it is to paste kit/chain.md into Claude Code and answer the six upfront questions. If you prefer to understand each step before running it — or to run individual prompts manually — this chapter walks the pipeline in sequence.

Prerequisites and timing

The fourteen-step pipeline

Running in Chain Mode vs ad-hoc

Time estimates and iteration notes

Atomic prompts

Individual prompts are the atoms of the system. This chapter documents the full catalog — what each prompt does, what inputs it requires, what it produces, and which chains it belongs to. Use this as a reference when running ad-hoc or building custom chains.

All 28 prompts (00–27, plus 01b as merged reference) live in kit/prompts/. The kit's README.html, Prompt Flow Map, and Full Prompt Catalog show them in context. This chapter explains why the boundaries between prompts are where they are — and the constraints that make each one a complete, independent unit.

The atomic prompt contract

An atomic prompt is complete when it can be pasted into any Claude session, given its documented inputs, and produce its documented output without requiring context from a prior conversation. This is not about size — some atomic prompts are 70 lines; some are 200. It is about self-containment.

Prompt catalog

The catalog groups 28 prompts into six functional clusters. Generation prompts (00–13) compose into Chain 9 (Path A end-to-end). Validation & integration (14, 15) are post-generation. Path B workflow (16–18) is the three-phase Figma → code chain. Claude Design (20–23) covers Workflow A/C in claude.ai. Scenarios (24–26) are alternative production paths. Code → Figma planning (19, 27) prepares the chain that closes the round-trip.

Why the token / typography split (Prompts 01 and 02)

Prompt 01 generates color, spacing, radii, and motion. It generates zero typography tokens. Prompt 02 generates all typography. The split exists so you can iterate on the color palette without regenerating the type scale — and iterate on type without re-running the full token pass. The two files compose in output/tokens.css (Prompt 02 updates the same file in place). Changing either one after components ship requires re-running all downstream component prompts.

Prompt chains

A chain is a sequence of prompts where each output is an input to the next. Ten chains cover the full design system lifecycle — from initial token generation to Path B production code to Figma round-trip. This chapter documents each chain's structure, entry point, and intended outcome.

The ten chains

Chain 9 — the canonical Path A run

Chain 9 is what kit/chain.md orchestrates. The sequence is the standard Path A run — it produces a complete design system from adjectives. The human's decision points: adjectives, archetype confirmation, BYOC colors, brand fonts, domain component descriptions, and go/no-go at each checkpoint.

Key sequencing rules:

• Tokens must be locked before components run (Steps 1–2 before Steps 3–7)
• Foundation before composite (Step 3 before Step 4)
• Spec page last (Step 8, after all component CSS is final)
• Layer 3 extraction after components stabilise (not on first run)
• Never re-run token prompts after components ship — use Prompt 11 (drift audit) to detect divergence

Composing custom chains

Chains 1–8 are building blocks. If you need a subset — tokens only, or components without chrome — combine the relevant prompts. The rule for any custom chain: each prompt must have all its prerequisite output files before it runs. The dependency graph is simple: token prompts have no kit-level prerequisites; component prompts need tokens; spec page needs components; audit prompts need the final locked files.

Quality gates

A quality gate is a check that runs automatically and can block a merge. This chapter covers the four gates that belong in every design system CI pipeline — WCAG contrast, token drift, a11y, and visual regression — and the prompts that power them.

Four gates, four cadences

The governance spec IS the quality gate

The governance spec's QUALITY-GATE CHECKLIST section encodes these gates as explicit checkboxes — 13 items from contrast verification to Storybook stories. When Prompt 08 generates the spec page, it produces an accessibility verification table computed from the actual token values (not estimated). That table is the WCAG gate's evidence.

The banned patterns in each archetype spec (Harbor's "no gradient circles", Sentinel's "no floating labels", etc.) are also quality gates — they run as part of Prompt 01's governance override step (STEP 5). Any component that generates a banned pattern has a governance failure, not a stylistic preference.

Drift audit in CI — the minimal setup

Failure modes

The twelve patterns that make AI-generated design systems fail in production. Each has a root cause, a detection signal, and a fix. Most are preventable by following the archetype spec. All are recoverable.

Pipeline failures

Archetype-specific failures (cross-reference Ch09–Ch11)

Five AI-specific failure modes

Building for change

A design system is not a delivered artifact. It is a maintained contract. This chapter covers how the layered token architecture absorbs rebrands, how Layer 3 extraction adapts to product evolution, and the four ceremonies that keep a system alive after v1 ships.

How the layers absorb change

The four maintenance ceremonies

Org playbook

Everything in this book can be run by one person in an afternoon. But design systems live at the intersection of design, engineering, and product — and that intersection requires a human playbook, not just a prompt library. This appendix covers roles, objections, and the three-month rollout.

Who does what

The three-month rollout

Migrating onto an existing codebase

The three-month rollout above assumes a greenfield project. Most teams adopt this on a system that already ships — partial tokens, inconsistent components, accumulated drift. The migration playbook below is designed to deliver value from week one without forcing a rewrite.

Common objections and honest responses

Glossary of terms

The vocabulary of this book in one place. Definitions are scoped to how the term is used here — broader industry meanings may differ.

References & further reading

The standards, specifications, and prior art this book builds on. Where the book's claims rest on external sources, this is where they're traced.

Standards & specifications

• WCAG 2.1 AA / 2.2. Web Content Accessibility Guidelines. The contrast ratios (4.5:1 body, 3:1 large text and UI), focus-visible requirements, and keyboard reachability rules in this book derive from WCAG 2.1 AA. w3.org/TR/WCAG22
• ARIA 1.2. Accessible Rich Internet Applications spec. The role / state / property requirements for interactive components (Button, Input, Combobox, Dialog) follow ARIA 1.2 patterns. w3.org/TR/wai-aria-1.2
• ARIA Authoring Practices Guide (APG). Reference implementations for common interaction patterns. Where the book references "the standard pattern for X," the APG is the source. w3.org/WAI/ARIA/apg
• Model Context Protocol (MCP). Open protocol for connecting AI assistants to data sources, published by Anthropic. Defines how Figma Dev Mode and Storybook expose design context to Claude. modelcontextprotocol.io
• W3C Design Tokens Format Module (DTCG). Emerging standard for design token interchange. The book's Layer 1 / 2 / 3 architecture is compatible with DTCG semantics; export tooling is out of scope but planned for v2.x. w3.org/community/design-tokens
• OKLCH color space. Perceptually uniform color space used by Prompt 02 for ramp generation. w3.org/TR/css-color-4 §OKLab/OKLCH

Tools & platforms referenced

• Figma Dev Mode & Code Connect. The official designer-developer handoff surface; required for Paths B and C. help.figma.com — Dev Mode
• Claude (Anthropic). The model family these prompts were authored against — Opus 4.7, Sonnet 4.6, Haiku 4.5 (current as of 2026-05). claude.com
• Claude Projects & Artifacts. See Ch17. Artifacts render HTML/CSS in-thread; Projects persist context across conversations. docs.claude.com
• Storybook. Component workshop and visual reference. Used as the visual regression target in Ch23 (CI gates) and the docs surface in Ch20. storybook.js.org

Prior art on design systems

• Brad Frost, Atomic Design (2016). The atoms-molecules-organisms framing remains the most cited mental model for component decomposition; this book's component spec (Ch12) is aligned with that shape. atomicdesign.bradfrost.com
• Nathan Curtis, EightShapes design-tokens writing. The three-layer token model (primitive / semantic / component) traces to Curtis's mid-2010s articles on naming and aliasing. medium.com/eightshapes-llc
• Salesforce Lightning Design System. One of the earliest publicly-documented enterprise systems with explicit governance and token architecture. lightningdesignsystem.com
• Material Design. Google's system; the source of the typography-scale and density-tier framing this book adapts (and selectively diverges from). m3.material.io
• Polaris (Shopify), Carbon (IBM), Spectrum (Adobe), Primer (GitHub). Public enterprise systems that informed the Sentinel archetype's component priority order and governance posture. Each has open documentation worth reading.

Industry research on AI & design consistency

• The "70% fidelity from description / 95–98% with spec + MCP + tokens" range is a working estimate based on the author's project work, not a published study. Independent, peer-reviewed numbers on AI design fidelity are not yet established as of 2026-05; readers should calibrate locally before quoting these as benchmarks.
• Anthropic's published guidance on prompt engineering, structured outputs, and tool use informs the prompt format used in kit/prompts/. docs.claude.com — prompt engineering

External links above were correct as of 2026-05-02. URLs change. Where a link 404s, search the title — the canonical content typically remains discoverable.