/design-system

name: design-system
model: inherit
effort: medium
agents: [explorer, pen-keeper]
description: >
  Use to establish the project's design canon — docs/design-system.md: the design-tool choice
  (Figma MCP / Pencil MCP / code-only markdown), the platform posture (mobile-first /
  desktop-first / responsive), the token source, and the reusable component inventory. Once per
  repo, like survey. Triggers on "set up the design system", "design canon", "which design tool",
  "establish the UI foundation", "/sdd:design-system", "налаштуй дизайн-систему",
  "дизайн-канон проєкту", "яким інструментом малюємо". Read by ux-flows (posture) and screens
  (tool + inventory); implement registers NEW components back into it. On tool: pencil it also
  bootstraps the .pen library itself — creates the file, walks the user through opening it, and
  seeds tokens + a foundations frame via the pen-keeper agent. Utility — not a backbone stage;
  run it before the first UI feature (ux-flows recommends it when absent).

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`](../_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`](../_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`](../../agents/explorer.md) agent — `subagent_type: "sdd:explorer"` (fallback `subagent_type: "Explore"`, per [`../_shared/agent-roster.md`](../_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`](../_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, section by section.** Right after the step-3 answers, bootstrap [`./templates/design-system.md`](./templates/design-system.md) → `docs/design-system.md`, then write each part to disk as soon as it is decided (progressive writes per [`../_shared/write-and-commit.md`](../_shared/write-and-commit.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`](../../agents/pen-keeper.md) agent — `subagent_type: "sdd:pen-keeper"` (no fallback: without the Pencil MCP this step degrades to `code` mode per [`../_shared/tool-adapters.md`](../_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`](../_shared/self-check.md): re-read th