[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72CG992X0N6KP2CBEHSECM6":3,"skill-same:01M72CG992X0N6KP2CBEHSECM6":65},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":6,"updatedAt":33,"install":34,"resources":46},"01M72CG992X0N6KP2CBEHSECM6","design-system",null,"Read a canvas design system, bootstrap a new system, or check its completeness. Select the matching mode.","1aGh\u002Fmaude","1aGh","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F17166964?v=4","01M72CAQDBB0YG724KFT7WEYRF","Michal Dovrtel","01M72CAQDXC32AWQRZYNJXXDC4",3,"MIT","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002FSKILL.md",[],[],"2026-11-10 18:39:20",false,"---\nname: design-system\ndescription: \"Read a canvas design system, bootstrap a new system, or check its completeness. Select the matching mode.\"\nuser-invocable: true\n---\n\n# design-system — router\n\nFollow [host conventions](..\u002F..\u002FHARNESS.md) for Claude Code or Codex.\n\nThis skill has **two responsibilities** with **mode-switched flows**:\n\n1. **READ flow** (default) — load the project's design-system context (tokens, philosophy, hard-stops, active families) so any agent iterating on a canvas respects the system.\n2. **BOOTSTRAP flow** — scaffold a new design system (first one, an additional one alongside an existing DS, or re-bootstrap an existing DS with `--force`).\n\nThe mode is **auto-detected** at invocation (see `## Mode-detection` below). **This router is intentionally small — load exactly one sub-doc for the resolved mode so a turn never parses the flow it doesn't need.**\n\n- **READ** → load [`_read.md`](.\u002F_read.md) only.\n- **BOOTSTRAP** → load [`_bootstrap.md`](.\u002F_bootstrap.md) only (it carries discovery, the **Stage-3 direction gate** (pre-refinement moodboard pick of ~`moodboard.variants` seed-composed directions — DDR-080 + DDR-147) + the **Stage-4 refinement residue** + the **LOCK gate** (the direction contract) + the **Batch-A hero-preview drift gate**, scaffold, the opt-in organic-artifact seed step (`draw-agent` — backgrounds \u002F patterns \u002F spot \u002F brand mark, grounded in the discovered palette), the 4-round post-scaffold gate, and Post-Flight). Discovery probes load on demand from [`_pastier-probe-templates.md`](.\u002F_pastier-probe-templates.md) when you reach Stage 2.\n\nThe **Animation tooling contract** below stays in this router because both flows share it and `commands\u002Fnew.md` + `commands\u002Fedit.md` link to \"SKILL.md → Animation tooling contract\".\n\n---\n\n## Mode-detection (which flow to run)\n\nAt every invocation, decide which flow to execute:\n\n- Invoked via `\u002Fdesign:setup-ds \u003Cname>` → **BOOTSTRAP**, `target_ds = \u003Cname>`\n- Invoked via `\u002Fdesign:edit \"...\"` or `\u002Fdesign:new \"...\"` AND no `\u003CdesignRoot>\u002Fsystem\u002F*\u002F` exists → **BOOTSTRAP**, `target_ds = \"project\"`, Q1 prefilled from `$ARGUMENTS` \u002F `$BRIEF`\n- Invoked via `\u002Fdesign:setup-ds \u003Cexisting-name> --force` → **BOOTSTRAP** (re-bootstrap), `target_ds = \u003Cexisting-name>`\n- Invoked via `\u002Fdesign:setup-ds \u003Cname> --app` (the Maude app's \"Make a design system\" sheet) → **BOOTSTRAP**, sub-mode `app`, `target_ds = \u003Cname>`; the brief is the person's sentence, verbatim\n- Invoked via `\u002Fdesign:setup-ds \u003Cname> --upgrade-schema` (the Maude app's \"Bring \u003Csystem> up to the schema?\" sheet, or by hand) → **UPGRADE**, `target_ds = \u003Cname>`: load nothing else — [§ upgrade-schema](#upgrade-schema) below is the whole flow\n- Otherwise (active canvas exists, `system\u002F*\u002F` exists) → **READ** (default)\n\nWhen in BOOTSTRAP mode, classify into sub-modes:\n\n- `first-bootstrap` — `.design\u002Fconfig.json` does not exist (or `designSystems[]` is empty)\n- `additional-ds` — config exists, `target_ds` is NOT in `designSystems[]`\n- `re-bootstrap` — config exists, `target_ds` IS in `designSystems[]`, `--force` passed (else refuse)\n- `app` — `--app`: the Maude app already made the system as an outline (`revisions\u002Fhead.json` has no head). The flow is `_bootstrap.md` § \"`app` adaptation\": three directions written with `maude design ds draft`, the in-app pick as the gate, the sections filled through the working files, and no `ds done` (the person's button does it)\n\n**A new system in a Maude project starts on its canvas.** For `first-bootstrap` and `additional-ds`, run `maude design ds make \u003Ctarget_ds> --label \"\u003CLabel>\"` BEFORE any scaffold. It writes the config entry, `system\u002F\u003Ctarget_ds>\u002F` and the Design system canvas (outlines), so the person gets the canvas straight away and the app has no static folder to offer to convert. On success the flow is the `app` sub-mode (the brief verbatim, no Stage 0\u002F1 interview, no roster); only when `ds make` is refused because the project cannot be edited that way (older format, unknown verb) does the staged discovery + scaffold below run, and then the folder it makes is offered \"Turn this folder into a Design system canvas\". Never write `design-system.tsx` or `revisions\u002F` by hand.\n\nIf both modes seem plausible, **prefer READ** — bootstrap should be the explicit choice.\n\n**Changing a token of an existing system** is not a bootstrap. A system on its Design system canvas (it has\n`revisions\u002Fhead.json`) takes a waiting change: `maude design ds pending \u003Cds> --set \u003Cfile.json>`, applied with **Update N\ncanvases** or `maude design ds publish \u003Cds>`. A **folder system** (no `head.json`; the `ds` verbs answer\n`ds-not-converted`) has no review: files are the API, so edit its token CSS directly (`tokensCssRel` in\n`config.json`, default `system\u002F\u003Cds>\u002Fcolors_and_type.css`), then run `maude design ds-check \u003Cds> --emit` to refresh its\n`tokens.json`. Never edit `tokens.json`, `revisions\u002F` or `head.json` by hand.\n\nOnce the mode is resolved, **load the matching sub-doc** ([`_read.md`](.\u002F_read.md) or [`_bootstrap.md`](.\u002F_bootstrap.md)) and follow it. The sub-mode adaptations (`additional-ds`, `re-bootstrap`) are documented inside `_bootstrap.md`.\n\n---\n\n## upgrade-schema\n\nBring a design system that was made before the schema (ds-check level 11, or 10 with more than `missing-functional` wrong) up to the schema (V2-1.13 §5.10), **without changing how any canvas looks**. Invoked as `\u002Fdesign:setup-ds \u003Cds> --upgrade-schema`; in the Maude app, the amber dot on the system's row (or a switch to or from it) opens \"Bring \u003Csystem> up to the schema?\" and its \"✦ Bring it up\" sends you here with that message. **The person applies; you never do.** Everything goes through `maude design ds-upgrade \u003Cds> …` — nothing in `system\u002F\u003Cds>\u002F` or `config.json` is edited by hand, and a system that already lives on a Design system canvas (`revisions\u002Fhead.json` exists) is refused with `ds-upgrade-converted`: say so plainly and stop.\n\n**The steps, in order**\n\n1. `maude design ds-upgrade analyse \u003Cds>` — the deterministic first pass. It returns the mechanical plan: the `.ds` scope selector, alias inversions (`--w-semibold` → `--weight-semibold`), own-token prefixes (`--island-bg` → `--x-island-bg`), the manifests, and one `add-role` item per functional role the system lacks, each `status: needs-judgement`.\n2. **Judge what is left open** — only the `needs-judgement` and `needs-pick` items, from the system's own colours and type (read `colors_and_type.css`, its `README`, its specimens). Write them to a JSON file as a list of plan items with the same `id`s:\n   - an `add-role` item becomes `{ \"id\": \"role:--scrim\", \"kind\": \"add-role\", \"status\": \"judged\", \"by\": \"ai\", \"values\": { \"light\": \"\u003Cvalue>\", \"dark\": \"\u003Cvalue>\" }, \"sources\": [\"--fg-0\", \"--bg-0\"], \"note\": \"\u003Cwhy>\" }` (`\"*\"` for a value that does not change by theme). **A new colour is built only from the system's own tokens** — `var(--x)`, `color-mix(in oklch, var(--a) 40%, transparent)`, relative colour over them. Never a literal hex or `oklch(0.6 …)` (V3).\n   - a colour kind the system lacks entirely (no brand, no chart palette) is the one place a new hue is allowed: `status: \"needs-pick\"`, `newHue: true`, **exactly three** `options`, and a `picked` index — the person picks in the chat first; never pick for them (V4).\n   - a collision (`--x` already declared) is resolved as old meaning → new name, and written down in the item's `note` (V1).\n   - Do not add items of your own for canvases: the codemods are made at stage time.\n3. `maude design ds-upgrade validate \u003Cds> \u003Cjudged.json>` — refuses a breach of V1–V4 and V8 with exit 13 and names the item. Fix the item; do not loosen the check.\n4. `maude design ds-upgrade \u003Cds> --stage \u003Cjudged.json>` — copies `.design\u002F` to a throwaway `before\u002F` and `after\u002F` outside the project, applies the plan to `after\u002F`, and writes the canvas codemods (only `var()` names, `className` tokens, import lines and meta keys change — V6). Canvases left out at an older revision, `pinned` canvases and `ui\u002Fv2\u002F**` get no codemod (V7, Q2). The live tree is untouched. It prints the stage's **stamp**.\n5. `maude design ds-upgrade \u003Cds> --prove \u003Cstamp>` — two quiet studios render every artboard of every affected canvas and specimen, in every theme, and diff them (a pixel counts when its OKLab ΔE × 100 is over 2; an artboard fails over 0.5 % changed pixels). It takes about a second per artboard and theme; the app shows its progress and a Cancel. A canvas whose codemod fails is **refused** (it stays as it is, and the person sees \"N canvases can't be updated yet\"). A failure on a canvas with **no** codemod — or on a specimen — is the system files' fault, and refuses the whole apply (`systemFailed`): system edits must be invisible, because the new roles have no users yet. If that happens, find the item that shows (usually a role whose value is not what an existing literal looked like), fix the judged item, `--discard` the stage and start again from step 3.\n6. **Stop.** Tell the person in one short message what the stage does (the numbers in `review.json`: roles added, components renamed, own tokens kept, canvases updated, canvases refused) and that the sheet is ready. **Do not run `--apply`.** In the app the sheet's primary button is the apply (one action, one undo step, the permission card on the agent side); in Claude Code the person asks you, and the card appears.\n\n**What the engine does and does not do.** It applies the scope selector, alias inversions, own prefixes, `add-role` items, the manifests and the canvas codemods. A `map-component` item (`{ \"id\": \"component:island\", \"kind\": \"map-component\", \"native\": \"island\", \"to\": \"Panel\", \"variant\": \"floating\" }`) is recorded and shown as \"Renames N components\", but the engine does not rewrite component CSS: keep the old class as a second selector yourself (`.island, .panel--floating { … }`, V5) in `preview\u002F_components.css` before you stage, so both copies carry it.\n\n**Housekeeping.** `maude design ds-upgrade \u003Cds> --status` lists the system's live stages (staged, being proved with `current`\u002F`total`, proved with its review); `--cancel \u003Cstamp>` stops a proof in flight; `--discard \u003Cstamp>` removes a stage's copies and record. A stage whose project has moved since it was made (`ds-upgrade-stale`) cannot be applied: discard it and stage again. Never run the steps for another project, never implicitly (boot, sync and `maude migrate v2` never start a bring-up).\n\n---\n\n## Animation tooling contract (authoritative — DDR-049)\n\n**This is the single source of truth for how animation is authored in Maude.**\nIt applies identically to **specimens** (`system\u002F\u003Cds>\u002Fpreview\u002F*.tsx`) and\n**canvases** (`ui\u002F*.tsx`). When `\u002Fdesign:new`, `\u002Fdesign:edit`, `\u002Fdesign:setup-ds`,\nor any critic touches motion, this section wins over any looser phrasing\nelsewhere. Other docs (`commands\u002Fnew.md`, `templates\u002F...\u002FSUB-AGENT-PROMPTS.md`,\n`agents\u002Fmotion-critic.md`, `agents\u002Fdesign-system-keeper.md`) link here rather\nthan restating the rule.\n\n**Default — Motion One via canvas-lib (MUST).** Any animated UI MUST use the\ncanvas-lib motion vocabulary from `@maude\u002Fcanvas-lib`, which wraps Motion One\n(`motion\u002Freact`):\n- `\u003CMotionDemo role>` — the 8 canonical roles: `flip` · `panel` · `route` ·\n  `soft` · `spring` · `scroll` · `drag` · `presence`. Each binds a `--dur-*` +\n  `--ease-*` token pair, clips its own bounds (`overflow:hidden`), and defaults\n  to `loop=\"always\"` so motion is visible on first paint (closes the\n  \"looks dead until you hover\u002Freplay\" failure mode).\n- `\u003CMotionTrack>` (staggered rows), `\u003CTokenPlayback>` (replay chip),\n  `\u003CReducedMotionToggle>` (in-browser reduced-motion preview), `useMotionTokens()`,\n  `easingFromToken()`.\n- `motion\u002Freact` is declared as a peer dep of canvas-lib and emitted into\n  `\u002Fdesign:handoff`'s `registry-item.json` automatically — handed-off canvases\n  animate in a Next.js + shadcn target with no manual `npm i`.\n\n**Escape hatch — pure-CSS `.motion-*` classes (opt-in, must be justified).**\nZero-JS surfaces may use the role classes shipped in `_components.css`\n(`.motion-flip … .motion-presence`) — same token bindings, same bounded\nkeyframes, no JS. Legitimate ONLY for declared zero-runtime cases: static hero,\na single hover\u002Ffocus transition, an accessibility-first marketing page. Choosing\nthe escape hatch over `\u003CMotionDemo>` MUST be recorded with a one-line reason\n(canvas `.meta.json` note, or the DS bypass log for a specimen).\n\n**Never:**\n- Hand-roll `@keyframes` for any of the 8 roles when a `\u003CMotionDemo role>` \u002F\n  `.motion-*` equivalent exists. (`motion-critic` + `design-system-keeper`\n  enforce this — warning in ordinary canvases, **blocker in the `motion.tsx`\n  specimen**, which is the teaching artifact and must model the canonical path.)\n- Add `!important` reduced-motion overrides anywhere except the motion\n  specimen's `\u003CReducedMotionToggle>` chrome. Tokens already collapse `--dur-*`\n  to `1ms` under `@media (prefers-reduced-motion: reduce)`; with `motion\u002Freact`\n  use `useReducedMotion()` and short-circuit the `animate` prop.\n\n**Decision rule when generating:** brief implies motion (`animate`, `transition`,\n`play`, `loop`, `slide`, `fade`, drag\u002Fdrop, route transitions, presence cursors,\nscroll-linked) → reach for `\u003CMotionDemo role>` first; drop to `.motion-*` only\nfor a justified zero-JS surface; never reinvent keyframes for a named role.\n\n---\n\n## Companion skills\n\n- `design` — user-facing orchestrator (canvas-first iteration loop)\n- `ui-kit` — pointer to project-specific reference surfaces \u002F components\n- `frontend-design` (external plugin) — generates new canvas files using these tokens\n\n## Cross-links\n\n- READ flow: [`_read.md`](.\u002F_read.md)\n- BOOTSTRAP flow: [`_bootstrap.md`](.\u002F_bootstrap.md)\n- Discovery probes: [`_pastier-probe-templates.md`](.\u002F_pastier-probe-templates.md)\n- Inspiration library: `plugins\u002Fdesign\u002Ftemplates\u002Fdesign-system-inspiration\u002F`\n- Mapping contract: `plugins\u002Fdesign\u002Ftemplates\u002Fdesign-system-inspiration\u002F_MAPPING.md`\n- Tokens (authoritative, post-scaffold): `\u003CdesignRoot>\u002F\u003CtokensCssRel>` (single-DS) or `\u003CdesignRoot>\u002Fsystem\u002F\u003Cds>\u002Fcolors_and_type.css` (multi-DS)\n- Live specimen browse: dev server at `http:\u002F\u002Flocalhost:\u003Cport>\u002F\u003CdesignRoot>\u002Fsystem\u002F...`\n- Per-repo config: `.design\u002Fconfig.json`\n- Completeness-critic: `plugins\u002Fdesign\u002Fagents\u002Fdesign-system-completeness-critic.md`\n- Stage-2 research agent: `plugins\u002Fdesign\u002Fagents\u002Fux-research-agent.md` (mode `discovery`)\n- Stage-2 payload cache: `\u003CdesignRoot>\u002F_history\u002F_system\u002F\u003Cds>-\u003Cbrief-sha8>-domain-research-discovery.json` (brief-hash in key — different briefs in same DS get separate cache files)\n","# design-system — router\n\nFollow [host conventions](..\u002F..\u002FHARNESS.md) for Claude Code or Codex.\n\nThis skill has **two responsibilities** with **mode-switched flows**:\n\n1. **READ flow** (default) — load the project's design-system context (tokens, philosophy, hard-stops, active families) so any agent iterating on a canvas respects the system.\n2. **BOOTSTRAP flow** — scaffold a new design system (first one, an additional one alongside an existing DS, or re-bootstrap an existing DS with `--force`).\n\nThe mode is **auto-detected** at invocation (see `## Mode-detection` below). **This router is intentionally small — load exactly one sub-doc for the resolved mode so a turn never parses the flow it doesn't need.**\n\n- **READ** → load [`_read.md`](.\u002F_read.md) only.\n- **BOOTSTRAP** → load [`_bootstrap.md`](.\u002F_bootstrap.md) only (it carries discovery, the **Stage-3 direction gate** (pre-refinement moodboard pick of ~`moodboard.variants` seed-composed directions — DDR-080 + DDR-147) + the **Stage-4 refinement residue** + the **LOCK gate** (the direction contract) + the **Batch-A hero-preview drift gate**, scaffold, the opt-in organic-artifact seed step (`draw-agent` — backgrounds \u002F patterns \u002F spot \u002F brand mark, grounded in the discovered palette), the 4-round post-scaffold gate, and Post-Flight). Discovery probes load on demand from [`_pastier-probe-templates.md`](.\u002F_pastier-probe-templates.md) when you reach Stage 2.\n\nThe **Animation tooling contract** below stays in this router because both flows share it and `commands\u002Fnew.md` + `commands\u002Fedit.md` link to \"SKILL.md → Animation tooling contract\".\n\n---\n\n## Mode-detection (which flow to run)\n\nAt every invocation, decide which flow to execute:\n\n- Invoked via `\u002Fdesign:setup-ds \u003Cname>` → **BOOTSTRAP**, `target_ds = \u003Cname>`\n- Invoked via `\u002Fdesign:edit \"...\"` or `\u002Fdesign:new \"...\"` AND no `\u003CdesignRoot>\u002Fsystem\u002F*\u002F` exists → **BOOTSTRAP**, `target_ds = \"project\"`, Q1 prefilled from `$ARGUMENTS` \u002F `$BRIEF`\n- Invoked via `\u002Fdesign:setup-ds \u003Cexisting-name> --force` → **BOOTSTRAP** (re-bootstrap), `target_ds = \u003Cexisting-name>`\n- Invoked via `\u002Fdesign:setup-ds \u003Cname> --app` (the Maude app's \"Make a design system\" sheet) → **BOOTSTRAP**, sub-mode `app`, `target_ds = \u003Cname>`; the brief is the person's sentence, verbatim\n- Invoked via `\u002Fdesign:setup-ds \u003Cname> --upgrade-schema` (the Maude app's \"Bring \u003Csystem> up to the schema?\" sheet, or by hand) → **UPGRADE**, `target_ds = \u003Cname>`: load nothing else — [§ upgrade-schema](#upgrade-schema) below is the whole flow\n- Otherwise (active canvas exists, `system\u002F*\u002F` exists) → **READ** (default)\n\nWhen in BOOTSTRAP mode, classify into sub-modes:\n\n- `first-bootstrap` — `.design\u002Fconfig.json` does not exist (or `designSystems[]` is empty)\n- `additional-ds` — config exists, `target_ds` is NOT in `designSystems[]`\n- `re-bootstrap` — config exists, `target_ds` IS in `designSystems[]`, `--force` passed (else refuse)\n- `app` — `--app`: the Maude app already made the system as an outline (`revisions\u002Fhead.json` has no head). The flow is `_bootstrap.md` § \"`app` adaptation\": three directions written with `maude design ds draft`, the in-app pick as the gate, the sections filled through the working files, and no `ds done` (the person's button does it)\n\n**A new system in a Maude project starts on its canvas.** For `first-bootstrap` and `additional-ds`, run `maude design ds make \u003Ctarget_ds> --label \"\u003CLabel>\"` BEFORE any scaffold. It writes the config entry, `system\u002F\u003Ctarget_ds>\u002F` and the Design system canvas (outlines), so the person gets the canvas straight away and the app has no static folder to offer to convert. On success the flow is the `app` sub-mode (the brief verbatim, no Stage 0\u002F1 interview, no roster); only when `ds make` is refused because the project cannot be edited that way (older format, unknown verb) does the staged discovery + scaffold below run, and then the folder it makes is offered \"Turn this folder into a Design system canvas\". Never write `design-system.tsx` or `revisions\u002F` by hand.\n\nIf both modes seem plausible, **prefer READ** — bootstrap should be the explicit choice.\n\n**Changing a token of an existing system** is not a bootstrap. A system on its Design system canvas (it has\n`revisions\u002Fhead.json`) takes a waiting change: `maude design ds pending \u003Cds> --set \u003Cfile.json>`, applied with **Update N\ncanvases** or `maude design ds publish \u003Cds>`. A **folder system** (no `head.json`; the `ds` verbs answer\n`ds-not-converted`) has no review: files are the API, so edit its token CSS directly (`tokensCssRel` in\n`config.json`, default `system\u002F\u003Cds>\u002Fcolors_and_type.css`), then run `maude design ds-check \u003Cds> --emit` to refresh its\n`tokens.json`. Never edit `tokens.json`, `revisions\u002F` or `head.json` by hand.\n\nOnce the mode is resolved, **load the matching sub-doc** ([`_read.md`](.\u002F_read.md) or [`_bootstrap.md`](.\u002F_bootstrap.md)) and follow it. The sub-mode adaptations (`additional-ds`, `re-bootstrap`) are documented inside `_bootstrap.md`.\n\n---\n\n## upgrade-schema\n\nBring a design system that was made before the schema (ds-check level 11, or 10 with more than `missing-functional` wrong) up to the schema (V2-1.13 §5.10), **without changing how any canvas looks**. Invoked as `\u002Fdesign:setup-ds \u003Cds> --upgrade-schema`; in the Maude app, the amber dot on the system's row (or a switch to or from it) opens \"Bring \u003Csystem> up to the schema?\" and its \"✦ Bring it up\" sends you here with that message. **The person applies; you never do.** Everything goes through `maude design ds-upgrade \u003Cds> …` — nothing in `system\u002F\u003Cds>\u002F` or `config.json` is edited by hand, and a system that already lives on a Design system canvas (`revisions\u002Fhead.json` exists) is refused with `ds-upgrade-converted`: say so plainly and stop.\n\n**The steps, in order**\n\n1. `maude design ds-upgrade analyse \u003Cds>` — the deterministic first pass. It returns the mechanical plan: the `.ds` scope selector, alias inversions (`--w-semibold` → `--weight-semibold`), own-token prefixes (`--island-bg` → `--x-island-bg`), the manifests, and one `add-role` item per functional role the system lacks, each `status: needs-judgement`.\n2. **Judge what is left open** — only the `needs-judgement` and `needs-pick` items, from the system's own colours and type (read `colors_and_type.css`, its `README`, its specimens). Write them to a JSON file as a list of plan items with the same `id`s:\n   - an `add-role` item becomes `{ \"id\": \"role:--scrim\", \"kind\": \"add-role\", \"status\": \"judged\", \"by\": \"ai\", \"values\": { \"light\": \"\u003Cvalue>\", \"dark\": \"\u003Cvalue>\" }, \"sources\": [\"--fg-0\", \"--bg-0\"], \"note\": \"\u003Cwhy>\" }` (`\"*\"` for a value that does not change by theme). **A new colour is built only from the system's own tokens** — `var(--x)`, `color-mix(in oklch, var(--a) 40%, transparent)`, relative colour over them. Never a literal hex or `oklch(0.6 …)` (V3).\n   - a colour kind the system lacks entirely (no brand, no chart palette) is the one place a new hue is allowed: `status: \"needs-pick\"`, `newHue: true`, **exactly three** `options`, and a `picked` index — the person picks in the chat first; never pick for them (V4).\n   - a collision (`--x` already declared) is resolved as old meaning → new name, and written down in the item's `note` (V1).\n   - Do not add items of your own for canvases: the codemods are made at stage time.\n3. `maude design ds-upgrade validate \u003Cds> \u003Cjudged.json>` — refuses a breach of V1–V4 and V8 with exit 13 and names the item. Fix the item; do not loosen the check.\n4. `maude design ds-upgrade \u003Cds> --stage \u003Cjudged.json>` — copies `.design\u002F` to a throwaway `before\u002F` and `after\u002F` outside the project, applies the plan to `after\u002F`, and writes the canvas codemods (only `var()` names, `className` tokens, import lines and meta keys change — V6). Canvases left out at an older revision, `pinned` canvases and `ui\u002Fv2\u002F**` get no codemod (V7, Q2). The live tree is untouched. It prints the stage's **stamp**.\n5. `maude design ds-upgrade \u003Cds> --prove \u003Cstamp>` — two quiet studios render every artboard of every affected canvas and specimen, in every theme, and diff them (a pixel counts when its OKLab ΔE × 100 is over 2; an artboard fails over 0.5 % changed pixels). It takes about a second per artboard and theme; the app shows its progress and a Cancel. A canvas whose codemod fails is **refused** (it stays as it is, and the person sees \"N canvases can't be updated yet\"). A failure on a canvas with **no** codemod — or on a specimen — is the system files' fault, and refuses the whole apply (`systemFailed`): system edits must be invisible, because the new roles have no users yet. If that happens, find the item that shows (usually a role whose value is not what an existing literal looked like), fix the judged item, `--discard` the stage and start again from step 3.\n6. **Stop.** Tell the person in one short message what the stage does (the numbers in `review.json`: roles added, components renamed, own tokens kept, canvases updated, canvases refused) and that the sheet is ready. **Do not run `--apply`.** In the app the sheet's primary button is the apply (one action, one undo step, the permission card on the agent side); in Claude Code the person asks you, and the card appears.\n\n**What the engine does and does not do.** It applies the scope selector, alias inversions, own prefixes, `add-role` items, the manifests and the canvas codemods. A `map-component` item (`{ \"id\": \"component:island\", \"kind\": \"map-component\", \"native\": \"island\", \"to\": \"Panel\", \"variant\": \"floating\" }`) is recorded and shown as \"Renames N components\", but the engine does not rewrite component CSS: keep the old class as a second selector yourself (`.island, .panel--floating { … }`, V5) in `preview\u002F_components.css` before you stage, so both copies carry it.\n\n**Housekeeping.** `maude design ds-upgrade \u003Cds> --status` lists the system's live stages (staged, being proved with `current`\u002F`total`, proved with its review); `--cancel \u003Cstamp>` stops a proof in flight; `--discard \u003Cstamp>` removes a stage's copies and record. A stage whose project has moved since it was made (`ds-upgrade-stale`) cannot be applied: discard it and stage again. Never run the steps for another project, never implicitly (boot, sync and `maude migrate v2` never start a bring-up).\n\n---\n\n## Animation tooling contract (authoritative — DDR-049)\n\n**This is the single source of truth for how animation is authored in Maude.**\nIt applies identically to **specimens** (`system\u002F\u003Cds>\u002Fpreview\u002F*.tsx`) and\n**canvases** (`ui\u002F*.tsx`). When `\u002Fdesign:new`, `\u002Fdesign:edit`, `\u002Fdesign:setup-ds`,\nor any critic touches motion, this section wins over any looser phrasing\nelsewhere. Other docs (`commands\u002Fnew.md`, `templates\u002F...\u002FSUB-AGENT-PROMPTS.md`,\n`agents\u002Fmotion-critic.md`, `agents\u002Fdesign-system-keeper.md`) link here rather\nthan restating the rule.\n\n**Default — Motion One via canvas-lib (MUST).** Any animated UI MUST use the\ncanvas-lib motion vocabulary from `@maude\u002Fcanvas-lib`, which wraps Motion One\n(`motion\u002Freact`):\n- `\u003CMotionDemo role>` — the 8 canonical roles: `flip` · `panel` · `route` ·\n  `soft` · `spring` · `scroll` · `drag` · `presence`. Each binds a `--dur-*` +\n  `--ease-*` token pair, clips its own bounds (`overflow:hidden`), and defaults\n  to `loop=\"always\"` so motion is visible on first paint (closes the\n  \"looks dead until you hover\u002Freplay\" failure mode).\n- `\u003CMotionTrack>` (staggered rows), `\u003CTokenPlayback>` (replay chip),\n  `\u003CReducedMotionToggle>` (in-browser reduced-motion preview), `useMotionTokens()`,\n  `easingFromToken()`.\n- `motion\u002Freact` is declared as a peer dep of canvas-lib and emitted into\n  `\u002Fdesign:handoff`'s `registry-item.json` automatically — handed-off canvases\n  animate in a Next.js + shadcn target with no manual `npm i`.\n\n**Escape hatch — pure-CSS `.motion-*` classes (opt-in, must be justified).**\nZero-JS surfaces may use the role classes shipped in `_components.css`\n(`.motion-flip … .motion-presence`) — same token bindings, same bounded\nkeyframes, no JS. Legitimate ONLY for declared zero-runtime cases: static hero,\na single hover\u002Ffocus transition, an accessibility-first marketing page. Choosing\nthe escape hatch over `\u003CMotionDemo>` MUST be recorded with a one-line reason\n(canvas `.meta.json` note, or the DS bypass log for a specimen).\n\n**Never:**\n- Hand-roll `@keyframes` for any of the 8 roles when a `\u003CMotionDemo role>` \u002F\n  `.motion-*` equivalent exists. (`motion-critic` + `design-system-keeper`\n  enforce this — warning in ordinary canvases, **blocker in the `motion.tsx`\n  specimen**, which is the teaching artifact and must model the canonical path.)\n- Add `!important` reduced-motion overrides anywhere except the motion\n  specimen's `\u003CReducedMotionToggle>` chrome. Tokens already collapse `--dur-*`\n  to `1ms` under `@media (prefers-reduced-motion: reduce)`; with `motion\u002Freact`\n  use `useReducedMotion()` and short-circuit the `animate` prop.\n\n**Decision rule when generating:** brief implies motion (`animate`, `transition`,\n`play`, `loop`, `slide`, `fade`, drag\u002Fdrop, route transitions, presence cursors,\nscroll-linked) → reach for `\u003CMotionDemo role>` first; drop to `.motion-*` only\nfor a justified zero-JS surface; never reinvent keyframes for a named role.\n\n---\n\n## Companion skills\n\n- `design` — user-facing orchestrator (canvas-first iteration loop)\n- `ui-kit` — pointer to project-specific reference surfaces \u002F components\n- `frontend-design` (external plugin) — generates new canvas files using these tokens\n\n## Cross-links\n\n- READ flow: [`_read.md`](.\u002F_read.md)\n- BOOTSTRAP flow: [`_bootstrap.md`](.\u002F_bootstrap.md)\n- Discovery probes: [`_pastier-probe-templates.md`](.\u002F_pastier-probe-templates.md)\n- Inspiration library: `plugins\u002Fdesign\u002Ftemplates\u002Fdesign-system-inspiration\u002F`\n- Mapping contract: `plugins\u002Fdesign\u002Ftemplates\u002Fdesign-system-inspiration\u002F_MAPPING.md`\n- Tokens (authoritative, post-scaffold): `\u003CdesignRoot>\u002F\u003CtokensCssRel>` (single-DS) or `\u003CdesignRoot>\u002Fsystem\u002F\u003Cds>\u002Fcolors_and_type.css` (multi-DS)\n- Live specimen browse: dev server at `http:\u002F\u002Flocalhost:\u003Cport>\u002F\u003CdesignRoot>\u002Fsystem\u002F...`\n- Per-repo config: `.design\u002Fconfig.json`\n- Completeness-critic: `plugins\u002Fdesign\u002Fagents\u002Fdesign-system-completeness-critic.md`\n- Stage-2 research agent: `plugins\u002Fdesign\u002Fagents\u002Fux-research-agent.md` (mode `discovery`)\n- Stage-2 payload cache: `\u003CdesignRoot>\u002F_history\u002F_system\u002F\u003Cds>-\u003Cbrief-sha8>-domain-research-discovery.json` (brief-hash in key — different briefs in same DS get separate cache files)\n",{"name":5,"description":7,"user-invocable":24},true,"main","cfde9d2b169e4b418a5c5efb35297cc575dc764c","plugins\u002Fdesign\u002Fskills\u002Fdesign-system",0,"https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude","https:\u002F\u002Fmaude.sh","https:\u002F\u002Fgithub.com\u002F1aGh","www.iagh.cz","2026-11-13 20:38:15",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":24},[36,39,42],{"tool":37,"command":38},"npx","npx skills add 1aGh\u002Fmaude --skill design-system",{"tool":40,"command":41},"bunx","bunx skills add 1aGh\u002Fmaude --skill design-system",{"tool":43,"command":44},"pnpm","pnpm dlx skills add 1aGh\u002Fmaude --skill design-system","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002FSKILL.md",[47,53,57,61],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"_bootstrap.md","REFERENCE","参考文档",153349,"https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002F_bootstrap.md",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"_DISCOVERY-v1.md",17283,"https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002F_DISCOVERY-v1.md",{"path":58,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":59,"sourceHtmlUrl":60},"_pastier-probe-templates.md",15322,"https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002F_pastier-probe-templates.md",{"path":62,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":63,"sourceHtmlUrl":64},"_read.md",3019,"https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fdesign\u002Fskills\u002Fdesign-system\u002F_read.md",[66,73,80,87,94,101],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M72CJCVNC5JB3M36ES649CTY","workflow-state","Read and update workflow state when planning, executing, completing, pausing or resuming project work.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Fworkflow-state\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M72CJAJBZT2RHE97ND8EFTA3","ui-rules","UI hard-stop rules and audit method: WCAG 2.1 AA accessibility, responsive layout and motion.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Fui-rules\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M72CJ857314HCC8A99T4K0D2","testing-rules","Apply test quality rules during implementation and review: meaningful assertions, isolation and coverage.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Ftesting-rules\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M72CJ6N80HW2WRS8BV4QSS4V","security-rules","Apply application and AI security checks to code reviews, implementation and threat-driven validation.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Fsecurity-rules\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M72CJ4C41Q4E1WDTFMKYFX3Q","scenario","Author or run cross-platform UI scenarios with selectors, screenshots, platform coverage and result reports.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Fscenario\u002FSKILL.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":19},"01M72CJ1QYX752BM7G12250YJR","question-protocol","Batch necessary questions from workflow participants, collect user answers and route them to the requester.","https:\u002F\u002Fgithub.com\u002F1aGh\u002Fmaude\u002Fblob\u002Fmain\u002Fplugins\u002Fflow\u002Fskills\u002Fquestion-protocol\u002FSKILL.md",[],[]]