--- name: design-system disable-model-invocation: true description: "Once per UI project: turn a design system (Figma, spec, reference screens, or a guided definition when no designs exist) into tokens, a UI library, a preview page, and an AGENTS.md rule; extend later." metadata: version: "0.2.3" --- # design-system Builds a provided design system into named tokens, a UI library in the target stack's idiom, a verifiable preview page, and three registrations (doc, AGENTS.md reference, project UI skill) — so every later UI change reuses the library instead of inlining one-off markup. Run once per UI project after `/agents-md` → `/setup-matt-pocock-skills` → placeholder fill; re-run `extend` when a trigger fires. **Not this skill.** One page matching its design pixel-for-pixel is `/pixel-audit`; cosmetic QA tails are `/polish-batch`; porting UI from a reference stack is `/port-feature`; tracing existing UI is `/feature-discovery`. ## Inputs Infer from the request and cheap repo evidence; interview only for gaps: - **TARGET PROJECT-CODE** — the full Project Matrix code; it determines the output idiom. Project Matrix missing → stop and route to `/agents-md` first. Read the target's stack from the matrix / `AGENTS.md`, never guess it. - **DESIGN-SYSTEM SOURCE (required)** — the named source wins. When none is named, load [`references/source-selection.md`](references/source-selection.md) and follow its ordered discovery. A source with tokens remains their single source of truth. No source or explicitly approved guided definition → stop and ask; never fabricate a system. ## Rules - Zero attribution: never add or leave co-author, AI, or tool attribution in commits, PRs, issue comments, release notes, generated docs, settings, or code comments. Include this rule in each generated or updated instruction file. - Name the full PROJECT-CODE from the Project Matrix everywhere; never mix one project's conventions, tokens, or components into another. - Decisions are **artifacts** — every output lives on disk, not in chat. - Never hardcode locations — resolve paths from the target's stack conventions and setup decisions; record real paths in doc, reference, and skill. - Sub-agents: dispatch local lanes automatically for independent work — never cloud agents; announce the lane count at dispatch and report each lane as it completes. Lanes extract and survey only; the main agent owns synthesis. - Emit `Stage / Found / Next / Needs user` at each phase transition — one line per field. - **Suggest, never auto-chain.** Recommend the next step and stop; never start feature work here. ## Stack-adaptive output Emit in the target's idiom, never one hardcoded framework: framework web (Laravel/Livewire, Rails, Django, …) → framework components + server-rendered preview route (e.g. `/ui/preview/all`); React Native → library + preview screen; static HTML/PHP → HTML/CSS components + static preview file; anything else → the closest match by how it renders UI. ## Modes ### bootstrap (default) Full first run; an existing design-system doc or library → switch to `extend`. In order: 1. **Extract** tokens and the base component list with states from the source. 2. **Tokens** — colours, typography, spacing, radii, shadows as named tokens in the project's existing mechanism, checked against its installed framework version; never hardcoded per use. Source defines light and dark → tokens carry both and the preview renders both. - **Contrast:** check every text/background token pair against WCAG AA — 4.5:1 body, 3:1 large text, focus indicators, and control boundaries. A failing source pair goes under Deviations and Needs user; never adjust a source colour silently. - **Fonts:** a font token names a face the project loads; one it cannot load is a Deviation, never a silent fallback. 3. **UI library** — build the base components (buttons, inputs, selects, toggles, cards, alerts, badges, …) from the tokens, faithful to the source. 4. **Preview page** — one page/route/screen rendering every component in its states (default/hover/focus/disabled/active; empty/loading/error where relevant; responsive) — the verification gate, in two halves: - **Agent half — evidence first.** Build/serve the target, load the preview, and check every extracted component appears with no error output. A rendered screenshot is the evidence floor; served HTML substitutes only for server-rendered web output. Client-only web and native stacks require a screenshot or rendered DOM/tree snapshot from the local browser or simulator. Quote the evidence: URL/file, status, screenshot path or stated fallback, and the rendered component list checked off against the extracted inventory. A bare aggregate count is not evidence. - **Human half — the gate.** If workspace policy requires `/agentic-qa` first and its proof is missing, mark human inspection pending and suggest that QA step; do not auto-invoke it. A later `preview` request, or the next `extend`, resumes at this half once that proof exists. Once applicable QA gates pass, show the preview location and ask the user to eyeball it. If the user is away, state the preview location and the agent-half evidence, record the eyeball as pending in the phase update, and continue to the suggestions — never claim the design system verified until they have looked. Where a snapshot harness exists, add a minimal render/snapshot test per base component. 5. **Register** — write the doc, the AGENTS.md reference, and the project UI skill (below). ### extend (re-run) Triggers: the design system grew (a new Figma component); a UI change needs a missing component; the feedback loop — a shipped page's UI flows back into the library. - **Missing component:** check the library first. Exists → nothing to build; stop and say so. Missing → build from the design-system source; no covering reference → ask the user for one before building — do not invent it. - **Feedback loop:** review the shipped page's diff and promote each reusable piece into the library, built from the shipped UI plus the source; leave page-local one-offs only when documented with a reason. - **Pending eyeball:** when bootstrap left the human half pending, show the preview location and ask for the eyeball before the sync. - **Sync:** update library, preview, doc, AGENTS.md reference, and project UI skill together in one pass. - **Boundary — design system only.** `extend` updates the design system and nothing else. It does not commit, push, write ADRs, or produce handovers; those stay `/grill-with-field` and `/commit-push-*`, invoked separately per suggest-never-auto-chain. ## Registration ### The `specs/design-system/` doc Write the full doc to `/design-system/-design-system.md`, with `` the setup docs location; no setup decision → `/specs/`. Resolve ``: the `*.code-workspace` directory if one exists, else the per-context root (`GLOSSARY-MAP.md` at repo root; legacy `CONTEXT-MAP.md`), else the repo root. Fill the doc skeleton in [`references/registration-templates.md`](references/registration-templates.md) §1. ### The AGENTS.md reference Add only a terse PROJECT-CODE-keyed reference where `/agents-md` structures it; update in place on `extend`, never duplicate. The full design system never goes in AGENTS.md — it points to the doc. Fill [`references/registration-templates.md`](references/registration-templates.md) §2. ### The project UI skill The deep reference for real UI work; every project-specific UI rule lives in it and the doc, never in `/design-system`. - **Detect an existing UI skill first:** survey `/.agents/skills/` and the runtime dirs (`.claude/skills/`, `.cursor/skills/`, …) for a skill already owning this project's UI work. - Found one → adopt and extend it in place; **never seed a parallel skill beside it** — two UI skills compete for routing. Fold in the real paths, component inventory and states, reuse-before-new discipline, missing-component procedure, and the consume-the-library rule; sharpen its description so UI work still routes to it. - Preserve its hand-grown conventions and voice: show the diff, and where an existing rule contradicts the design system, surface the conflict to the user rather than silently rewriting either side. - Record the adopted skill's **real name** in the doc's `Project skill:` line and the AGENTS.md reference. - Only when no UI skill exists anywhere: seed a project-local `-ui-coding` (kebab-case, per target naming); load [`references/fresh-ui-skill.md`](references/fresh-ui-skill.md) for location, per-runtime copies, and content. ## Output Emit the phase update and stop: ```markdown Stage: design-system () — tokens+library+preview for ; doc /design-system/-design-system.md; AGENTS.md reference added; seeded/extended. Found: tokens, components (); source = ; contrast ; stack = . Next: . Then /feature-prompt for the first feature. Needs user: ; confirm guided choices, failing contrast pairs, or DS/stack deviations. Suggested next skills (optional): - /feature-prompt: begin the first feature — it consumes this library. - /pixel-audit: per-page conformance during that feature work (not here). ``` Do not proceed past the suggestion. ## Completion criteria - [ ] Tokens, library, and preview exist at the doc-recorded paths - [ ] Preview evidence quoted per the agent half; render/snapshot tests pass where a harness exists - [ ] `/design-system/-design-system.md` exists with a `Project skill:` line naming a skill present on disk - [ ] `AGENTS.md` holds exactly one design-system reference for the TARGET PROJECT-CODE - [ ] The phase update records the eyeball as done or pending; nothing ran after it - [ ] `extend` runs: `git log` shows no new commits from this run