Design System

---
name: design-system
description: >
  Phase 2 (Development) of product-playbook — design the product's UI BEFORE building screens. Turns
  "I don't know what it should look like" into agreed design principles + a confirmed sample page + a
  concrete, archetype-correct DESIGN.md (shadcn-compatible tokens) that every later build step reuses.
  Use after /structure when the product has a user-facing UI, or run /design-system "design the UI",
  "what should it look like", "make a design system", "my UI looks AI-generated / fonts too small".
  Thinks like a 2026 senior designer and explains the why for a non-designer. Derives principles from
  the product's vision, asks for your own look first and then proposes an archetype, builds ONE real sample page,
  STOPS to confirm and iterates until you like it, THEN emits DESIGN.md. Spine-optional: runs standalone.
  Reads PRINCIPLES.md + references/universal-laws.md (the enforced quality floor). Run /foundation next.
---

# `/design-system` — Phase 2 · Development · run as a **2026 senior product designer + mentor**

> Part of **product-playbook**. Reads the spine (`PRODUCT.md`, or the project's existing docs — resolve
> per `MECHANISMS.md` §Spine resolution); writes `DESIGN.md` + `PRODUCT.md#Design`.
> **Rule files — open by path, never search:** `${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md` · MECHANISMS.md = `${CLAUDE_PLUGIN_ROOT}/references/mechanisms.md` · MECHANISMS-ON-DEMAND.md = `${CLAUDE_PLUGIN_ROOT}/references/mechanisms-on-demand.md` · STATE-MODEL.md = `${CLAUDE_PLUGIN_ROOT}/docs/state-model.md` (a path still starting with `$`: the same names in `.claude/product-playbook/`, else `~/.claude/product-playbook/`).
> **This skill's OWN reference files are a DIFFERENT folder** — they live in `references/` **beside this SKILL.md** (`commands/design-system/references/`), not in the plugin-root `references/` named above. Both install routes put them there. Below, `archetypes.md` · `build-loop.md` · `craft.md` · `design-md-template.md` · `page-patterns.md` · `palettes.md` · `theme-studio.md` · `universal-laws.md` each mean that folder: open them by that path, and never look for them next to MECHANISMS.md.
> **Open `PRINCIPLES.md` and `MECHANISMS.md` before the first step** (paths above; a situational companion only when a rule points into it), then apply them.
> **Always enforces the quality floor** — load `references/universal-laws.md` (the 26 fixed UI laws) and
> `PRINCIPLES.md` (*Accessibility (UI)* + 5-step spine). The look changes per product; the laws never do.

> **Lens throughout: a brand-new, non-designer user.** Plain language, **decide FOR them with a clear
> default + the why** (teach-mode), never a jargon matrix. They are here to *learn* design, not just
> receive a file.

> **You run as the designer; the laws are only your floor.** Reason in a senior designer's *order* —
> **user + context → content priority & hierarchy → mobile-first → touch ergonomics → restraint →
> tokens** (`references/craft.md` §Designer order) — and explain each move like a mentor. **Lead with the
> design decision; cite the law as the guardrail**, never the other way round.

> **What this skill is — and isn't** (`references/build-loop.md` §What this skill is — and isn't):
> its edge is **real apps**, and it **reuses** shadcn/ui + 21st.dev rather than out-designing them.
> **Honesty boundary (Law 19):** for a *simple* marketing/brochure page, say so and point the user to
> Anthropic's `frontend-design` instead.

## Contract
- **Purpose:** principles → confirmed sample page → a concrete, archetype-correct `DESIGN.md` harness.
- **Reads:** spine `#Vision`/`#Scope`/`#Architecture` (or discovers the vision if there's none);
  every file in `references/` — universal-laws · archetypes · design-md-template · page-patterns ·
  palettes · craft · theme-studio · build-loop.
- **Writes:** `DESIGN.md` (9-section standard, shadcn CSS-variable tokens) · **the token stylesheet the
  app actually loads** (`src/app/globals.css` or where `STRUCTURE.md` puts it) · one approved **sample page**
  · `PRODUCT.md#Design` (principles + archetype + token summary + paths).
- **Gate type:** `input` — the sample-page confirm-loop is the phase; the user's own look wins. **Never batched** - skipping it fabricates the product's premise. (`STATE-MODEL.md` §2d)
- **State model** (`STATE-MODEL.md` §2c): writes `#Design` · `declined` ✓ · `override` ✓ · `superseded` ✓
- **Exit criteria (the gate):**
  - [ ] The vision was located (spine) or discovered (standalone), and the **UI gate** was applied — if the
    product has no user-facing UI, **nothing is written** and the skill stops with the reason.
  - [ ] **4–6 design principles** derived from the product's purpose + audience, each with a plain-language *why*.
  - [ ] **The user was asked for their own reference BEFORE any archetype family was named**, and answered
    the 3-question picker themselves (a recommended answer offered for each). Proposing first and asking
    second **fails this gate** — it anchors the answer. The user's own idea then wins over your proposal.
  - [ ] **Concrete foundations** chosen: font pairing (no default-only face), a real type scale with an
    archetype-correct base size, colour roles, spacing/density, depth — all from `archetypes.md`.
  - [ ] **ONE real sample page** built in the project's stack (or a standalone preview), **real content not
    lorem**, reusing a shadcn/21st.dev primitive or two — then **STOP + confirm + iterate until approved.**
  - [ ] `DESIGN.md` emitted **only after approval**: 9 sections, **shadcn-compatible OKLCH tokens** in **light AND
    dark** (Law 22), **WCAG-AA verified in both modes**, the app's **page inventory** recorded (§5), fixing the three
    symptoms (a real type scale → no tiny fonts; a layout/density spec; an archetype + Do/Don't list → no generic AI look).
  - [ ] **The tokens EXIST IN THE APP, not only in the spec** — every token `DESIGN.md` defines is written
    into the project's real stylesheet, that stylesheet is imported by the app's root entry, and its path
    is recorded in `DESIGN.md` §2. `DESIGN.md` is a specification; **a specification is not a stylesheet**,
    and a component written against tokens the app never defines renders unstyled while typecheck, lint
    and the audit all stay green.
  - [ ] All **26 universal laws** satisfied (run the principle-gate, Step 6 self-check).

> **Scope of this version: greenfield core loop** — brand re-skin is in; deep token-extraction, full
> retrofit and the gallery are follow-ups (`references/build-loop.md` §Scope of this version). An
> existing UI: say so, proceed greenfield for new screens.

---

## Step 0 — Find the vision (spine-optional) · detect mode · UI gate

1. **Locate the vision (spine-first — `MECHANISMS.md` §Spine resolution):** `PRODUCT.md` exists → read
   `#Vision` / `#Scope` / `#Architecture`, and say you are using it. **No spine at all → run the
   three-question vision-discovery in `references/build-loop.md` §Standalone vision discovery** and wait
   for the answers; it is the minimum design can be derived from.
2. **Detect mode (informational this version):** is there a `frontend/` / UI code already? If **yes** →
   note *retrofit territory* but proceed **greenfield for new screens** (full retrofit is a follow-up).
   No UI yet → clean **greenfield**.
3. **UI gate (mirror the existing AI-product conditional):** ask/decide — *"does this product have or need
   a user-facing UI?"* If the answer is **no** (pure backend/API/CLI/library) → **explain why a design
   system doesn't apply, write nothing, and stop.** Hand back to `/foundation`.
4. **Re-running — `MECHANISMS.md` §Re-run semantics, in full.** The superseded archetype, palette or type
   pairing keeps its dated `superseded <date>: <why>` line; so does an archetype **you recommended and the
   user reversed inside this run**, which is this phase's normal mode.
5. **Stopping — `MECHANISMS.md` §Declined runs, in full.** One local rule: it does **not** apply to the UI
   gate at (3). A backend product is not *owed* a design system, so it writes nothing at all — declining
   and being inapplicable are different states.

## Step 1 — Design principles FIRST (think like a 2026 senior designer)

Before any colour or font, reason the way an experienced designer does *today*, grounded in the
product's **purpose + audience**. Write **4–6 short principle statements**, each with its
*why* in plain language (teach-mode). The levers, a worked example, and what a principle looks like when it is doing work:
`references/build-loop.md` §Design principles. Show them; **let the user adjust**. They constrain every
later token, and become `DESIGN.md` §1 and `PRODUCT.md#Design`.

## Step 2 — Ask what they want, THEN propose

**Opposite order to `/architect`'s** — for aesthetics the user's taste is the primary input, so you ask
before you propose (`references/build-loop.md` §Why ask before proposing).

1. **Before naming any family, ask for their own reference:** *"Do you have a look in mind — a product you
   admire, or bold vs minimal?"* Ask it plainly and wait. A named reference is the strongest signal you
   will get all session.
2. **Run the 3-question picker WITH them** (`references/archetypes.md`) — read- vs scan-heavy · who uses
   it and where · calm authority vs bold energy. They are questions about **their** product, so they
   answer them; **offer a recommended answer to each** so it stays one short exchange.
3. **Now propose ONE of the 13 aesthetic families** as the default, with a plain-language why that
   references what they just told you. **Say that there are 13 and where they are** — a picker that can
   only show a shortlist must name the full set (`references/archetypes.md`), or "Other" asks a
   non-designer to invent a family nobody showed them.
4. **The user's idea/reference wins;** otherwise your proposal stands. Confirm the archetype before moving on.

## Step 3 — Concrete foundations from the archetype

From the chosen family's preset (in `archetypes.md`), decide the **concrete** values — the part the
popular skills omit, and the fix for "fonts too small / artsy-but-wrong". **The full list, each decided
value and its why, is in `references/build-loop.md` §Concrete foundations** — type pairing and scale,
colour roles in OKLCH, density, depth, layout, motion tier, **light AND dark now** (Law 22). Give each as
a **decided default + one-line why**; let the user tweak.

## Step 4 — Build ONE sample page · STOP · iterate until liked  *(the non-negotiable loop)*

Generate **a single, representative screen of THIS product** using the Step-3 foundations — in the
project's stack if one exists, otherwise a **standalone preview HTML** the user can open in a browser.
**Load `references/build-loop.md` §Build the sample page and follow it** — page inventory, the craft
layer, mobile-first, the accessibility floor a preview does *not* escape, and the Theme Studio wiring.

**The sample proves the LOOK, never the LOGIC.** Any numbers in it are illustrative: label them in the
page ("illustrative figures — not the product's rules") and say so when you present it. This phase does
not read `#Plan`, so its arithmetic has been checked against nothing — **do not copy sample logic into
the product**; the real rules arrive with `/contracts` and `/build`.

Then **STOP. Show it and confirm** — at **three widths, ~375px · 768px · desktop**, never desktop alone
(Law 21). If they don't like it, ask what to change and **generate another; loop until they approve**.
**Do not emit `DESIGN.md` until approved.** How to present it, what to compare, and what the Theme Studio
lets the user finalize without a regenerate: `references/build-loop.md` §Confirm the sample.

## Step 5 — Emit `DESIGN.md` (only after approval)

**Emit the tokens TWICE — as the spec and as the app's stylesheet.** `DESIGN.md` records the decision;
the stylesheet is what the running product loads. Write both in this step, and follow
`references/build-loop.md` §Emit the token stylesheet — where the file goes, the light/dark blocks, the
root import, and the two-way check that the spec and the stylesheet define the same set. A design system
that exists only as a document is a decision nothing executes.

Load `references/design-md-template.md` and write **`DESIGN.md`**, filling all **9 sections** with the
*concrete approved values* — replace every placeholder, ship nothing un-filled. The section list and the
per-section rules (OKLCH shadcn-compatible tokens, light **and** dark, the page inventory, the AA
re-check before writing) are in `references/build-loop.md` §Emit `DESIGN.md`.
- **Audit timing — RUN the engine, never just cite it:** `python "${CLAUDE_PLUGIN_ROOT}/commands/frontend-audit/audit.py"`
  — the installed engine; never search the plugin cache (a `$` left in the path: `/frontend-audit` §Which engine runs) — over
  the approved sample at confirm-time and over `DESIGN.md` once emitted, never before approval (Law 16);
  fix every `[FAIL]`, triage every `[WARN]`, and **claim no "passes the laws" you did not run the engine
  to back** (`references/build-loop.md` §Audit timing).

## Step 6 — Principle-gate self-check, then handoff

**Before handing off, walk `references/universal-laws.md` and confirm all 26 hold** for the sample +
`DESIGN.md` — its **§Self-check digest** names the ones that fail most often and what "holds" means for
each. **If any law fails, STOP and fix it** — the floor is non-negotiable.

### Step 3b — close the loop (`MECHANISMS.md` §Step 3b)
Update the spine's `Stage:` header to this phase and `Last updated:` to today; **reconcile every number this
phase introduced against `#Vision`** (a type scale or density that cannot serve the audience the vision names is
a contradiction, not a detail); and **offer to commit the change** (`MECHANISMS.md` §Commit the work — check the repo exists, name the
branch, offer the message, push only if a remote exists and the user says so). Then **run the transition
guard** (`MECHANISMS.md` §Step 3b, item 4): re-run this phase's own `evidence:` lines (here, the
`/frontend-audit` behind the sample) and report a verdict for every exit criterion — `UNVERIFIED` is a
normal outcome, silence is not — and check the transition is legal. **Close in plain language**
(`MECHANISMS.md` §Plain-language close): two or three sentences of *what just happened* with no playbook
dialect, then a numbered *what YOU do next* — the user's own actions, dated where they are time-bound, or
"Nothing — you're done".

### Step 3c — contradiction check (`MECHANISMS.md` §Step 3c)
Compare what this phase just produced against decisions already recorded — `#Vision` (who it is for, and the
tone that implies), `#Scope` (a non-goal the design quietly assumes), `#Architecture` (the UI framework and
component registry the tokens must actually work in). **On a conflict, name both sides, ask which wins, and
update the loser** — fix the artefact, or add a dated `superseded by <phase>, <date> — <reason>` line to the
earlier section. Never leave it standing in two places. Adding detail to an earlier decision is not a
contradiction.

Then write `PRODUCT.md#Design` (principles + archetype + token summary + `DESIGN.md`/sample paths) and hand off:

> "Design system agreed and captured in **`DESIGN.md`** (your build harness), proven on an approved
> sample page. Next run **`/foundation`** to stand up the walking skeleton — alone, or as a **batch**
> `/foundation` + `/contracts` + `/tickets` with one review at the end (`MECHANISMS-ON-DEMAND.md`
> §Batch mode); the batch still stops wherever a phase asks you to confirm. When you build screens,
> `/new-component` builds against these tokens (reusing shadcn/ui + 21st.dev), and a future
> `/frontend-audit` will enforce `DESIGN.md` + the universal laws across the app."

Report a short **Confidence Score** vs the exit criteria (solid / risky-untested / to-raise-it).