Design System

Skill: design-system

The design-side twin of survey: once per repo it fixes the design canon in docs/design-system.md — which tool screens are drawn with (figma / pencil / code), the platform posture, where tokens come from, and the component inventory new screens must compose. architecture-map.md §Frontend stays the inventory of the code; this file is the design canon the design pipeline (ux-flows → screens) and implement/review read. The tool choice is committed here — never in .claude/sdd.local.md (that file is per-developer and gitignored; the canon is team-wide).

Question phrasing → ../_shared/ask-style.md. Canon prose follows artifact_language — frontmatter keys/values (tool:, figma_file:, …), component names and file anchors stay English → ../_shared/artifact-language.md.

Owner

Whoever owns the product's look (designer / frontend lead / the solo maintainer).

Inputs

• (Optional) docs/architecture-map.md §Frontend / UI foundation + the frontend: machine key — the code-side inventory this canon cites.
• (Optional) an existing docs/design-system.md — updated, never silently overwritten.
• The design-tool MCPs available in this session (Figma / Pencil), if any → detected in step 3.

Protocol

1. Check existing. If docs/design-system.md exists, show its tool + posture + inventory summary and ask: reuse as-is (STOP — nothing to do) / update (continue, edits land in place) / rebuild. Never overwrite silently.
2. Scan the code side. Read architecture-map.md §Frontend / UI foundation + the frontend: key. Map absent, stale, or frontend: "" on a repo that visibly has UI code → dispatch the explorer agent — subagent_type: "sdd:explorer" (fallback subagent_type: "Explore", per ../_shared/agent-roster.md) — for the component library / tokens / styling approach / shared primitives, each with a file:line. A repo with no UI code at all is fine — the canon can start tool-side or empty (greenfield: the inventory grows as implement registers components).
3. Detect tools + ask ONE question set. Detect which design-tool MCPs the session actually has (Figma / Pencil — probe the available tools, don't assume). Then one AskUserQuestion call (up to 3 questions in it, phrased per ../_shared/ask-style.md): (a) tool — options from what's detected, the detected one first as «(Recommended)»; code (markdown wireframes in screens.md) is always offered — it needs no MCP and never blocks; (b) platform posture — mobile-first / desktop-first / responsive-both; (c) token source — the code file(s) found in step 2 / the tool's variables / «none yet».
4. Write the canon. Fill ./templates/design-system.md → docs/design-system.md: frontmatter tool + figma_file/pen_file (the one matching the tool; the other stays ""), posture, token source, the component inventory — each row citing file:line (code) or the node/URL (tool-side) — and the cross-screen conventions.
5. Bootstrap the tool library (tool: pencil only — figma links an existing file, code needs nothing). The canon naming a pen_file that doesn't exist or is an empty stub is the #1 way this skill «did nothing» — so materialize it: a. File. Absent → write the minimal stub to pen_file ({"version": "2.17", "children": []}). b. Open + verify. The Pencil MCP ignores filePath — it writes into whatever document is active in the app. Ask the user to open the file (macOS: open -a Pen <pen_file>), then verify via get_app_state that the active canvas IS pen_file. Mismatch → stop and repeat the ask; never write into a foreign document. c. Seed. Dispatch the pen-keeper agent — subagent_type: "sdd:pen-keeper" (no fallback: without the Pencil MCP this step degrades to code mode per ../_shared/tool-adapters.md) — with the canon path, pen_file, and the token source files. It re-checks the active document, seeds the variables (light + dark), ensures the foundations frame, and returns a reconcile report. d. Persist. Relay the report's user actions — always «Cmd+S in Pencil»: the app holds changes in memory and the MCP cannot save; confirm the file on disk actually changed (size/mtime) before calling the canon done.
6. Structural self-check — per ../_shared/self-check.md: re-read the file from disk and verify 5 items: (1) tool ∈ {figma, pencil, code}; (2) the tool ↔ file fields agree — figma ⇒ figma_file non-empty, pencil ⇒ pen_file non-empty, code ⇒ both ""; (3) every inventory row carries a source anchor (file:line or node/URL); (4) no <placeholder> stubs survive; (5) tool: pencil ⇒ the pen_file exists on disk and is larger than the empty stub (step 5 ran and the user saved). Fix + re-check ≤2 cycles; surface anything unresolved.
7. Commit + handoff. Propose commit design-system: establish <tool> canon (on pencil — including the seeded pen_file). Then emit the stage-handoff block per ../_shared/handoff.md (utility variant) — What I did (incl. «self-check: 4/4 pass») + Review (docs/design-system.md) + Run next: resume your backbone stage (typically /sdd:ux-flows <slug> for the UI feature in flight); /clear optional.

Definition of Done

• docs/design-system.md exists with tool ∈ {figma, pencil, code}, a stated platform posture, a token source, and an inventory whose every row cites its source.
• The tool ↔ figma_file/pen_file fields are consistent; the file is committed (team-wide canon, not a local setting).
• tool: pencil ⇒ the .pen library exists on disk, holds the seeded token variables, and the user has saved it (the canon never points at a file that was never created).

Anti-patterns

• The tool choice in sdd.local.md. That file is per-developer and gitignored — two teammates would draw in different tools. The canon is committed, in this one file.
• Re-asking the tool per feature. ux-flows/screens read the canon; the question is asked once, here.
• Duplicating architecture-map.md §Frontend. The map inventories the code; this file cites it and adds the design-side canon — never a second copy of the same rows.
• Blocking on a missing MCP. No Figma/Pencil in the session → code mode is always available; degrade, don't block (→ ../_shared/tool-adapters.md).
• An inventory with no anchors. A component row that cites nothing is a guess — cite file:line or the tool node, or leave it out.
• A canon that names a pen_file nobody created. tool: pencil without step 5 is a dangling pointer — downstream screens opens nothing and silently degrades.
• Writing into whatever document is open. The Pencil MCP targets the ACTIVE document and ignores filePath — skipping the get_app_state identity check pollutes a foreign file.
• Assuming the MCP saved to disk. It edits in-memory; only the user's Cmd+S persists. Verify the file changed before committing.

References & template

• ./templates/design-system.md — the canon scaffold; inline comments are the per-section generation contract.
• ../_shared/tool-adapters.md — the design-tool MCP degradation row.
• ../_shared/agent-roster.md — the explorer contract (step 2).
• ../../agents/pen-keeper.md — the .pen reconcile contract (step 5).