design-system
Read a canvas design system, bootstrap a new system, or check its completeness. Select the matching mode.
- License 许可
- MIT
- 所属仓库
- 1aGh/maude
- 最近更新
- 2026-11-13
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- design-system
- description
- Read a canvas design system, bootstrap a new system, or check its completeness. Select the matching mode.
- user-invocable
- true
02 资源文件 4
- 参考文档_bootstrap.md149.8 KB
- 参考文档_DISCOVERY-v1.md16.9 KB
- 参考文档_pastier-probe-templates.md15.0 KB
- 参考文档_read.md2.9 KB
03 SKILL.md 正文
design-system — router
Follow host conventions for Claude Code or Codex.
This skill has two responsibilities with mode-switched flows:
- 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.
- BOOTSTRAP flow — scaffold a new design system (first one, an additional one alongside an existing DS, or re-bootstrap an existing DS with
--force).
The 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.
- READ → load
_read.mdonly. - BOOTSTRAP → load
_bootstrap.mdonly (it carries discovery, the Stage-3 direction gate (pre-refinement moodboard pick of ~moodboard.variantsseed-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 / patterns / spot / 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.mdwhen you reach Stage 2.
The Animation tooling contract below stays in this router because both flows share it and commands/new.md + commands/edit.md link to "SKILL.md → Animation tooling contract".
Mode-detection (which flow to run)
At every invocation, decide which flow to execute:
- Invoked via
/design:setup-ds <name>→ BOOTSTRAP,target_ds = <name> - Invoked via
/design:edit "..."or/design:new "..."AND no<designRoot>/system/*/exists → BOOTSTRAP,target_ds = "project", Q1 prefilled from$ARGUMENTS/$BRIEF - Invoked via
/design:setup-ds <existing-name> --force→ BOOTSTRAP (re-bootstrap),target_ds = <existing-name> - Invoked via
/design:setup-ds <name> --app(the Maude app's "Make a design system" sheet) → BOOTSTRAP, sub-modeapp,target_ds = <name>; the brief is the person's sentence, verbatim - Invoked via
/design:setup-ds <name> --upgrade-schema(the Maude app's "Bring <system> up to the schema?" sheet, or by hand) → UPGRADE,target_ds = <name>: load nothing else — § upgrade-schema below is the whole flow - Otherwise (active canvas exists,
system/*/exists) → READ (default)
When in BOOTSTRAP mode, classify into sub-modes:
first-bootstrap—.design/config.jsondoes not exist (ordesignSystems[]is empty)additional-ds— config exists,target_dsis NOT indesignSystems[]re-bootstrap— config exists,target_dsIS indesignSystems[],--forcepassed (else refuse)app—--app: the Maude app already made the system as an outline (revisions/head.jsonhas no head). The flow is_bootstrap.md§ "appadaptation": three directions written withmaude design ds draft, the in-app pick as the gate, the sections filled through the working files, and nods done(the person's button does it)
A new system in a Maude project starts on its canvas. For first-bootstrap and additional-ds, run maude design ds make <target_ds> --label "<Label>" BEFORE any scaffold. It writes the config entry, system/<target_ds>/ 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/1 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/ by hand.
If both modes seem plausible, prefer READ — bootstrap should be the explicit choice.
Changing a token of an existing system is not a bootstrap. A system on its Design system canvas (it has
revisions/head.json) takes a waiting change: maude design ds pending <ds> --set <file.json>, applied with Update N
canvases or maude design ds publish <ds>. A folder system (no head.json; the ds verbs answer
ds-not-converted) has no review: files are the API, so edit its token CSS directly (tokensCssRel in
config.json, default system/<ds>/colors_and_type.css), then run maude design ds-check <ds> --emit to refresh its
tokens.json. Never edit tokens.json, revisions/ or head.json by hand.
Once the mode is resolved, load the matching sub-doc (_read.md or _bootstrap.md) and follow it. The sub-mode adaptations (additional-ds, re-bootstrap) are documented inside _bootstrap.md.
upgrade-schema
Bring 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 /design:setup-ds <ds> --upgrade-schema; in the Maude app, the amber dot on the system's row (or a switch to or from it) opens "Bring <system> 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 <ds> … — nothing in system/<ds>/ or config.json is edited by hand, and a system that already lives on a Design system canvas (revisions/head.json exists) is refused with ds-upgrade-converted: say so plainly and stop.
The steps, in order
maude design ds-upgrade analyse <ds>— the deterministic first pass. It returns the mechanical plan: the.dsscope selector, alias inversions (--w-semibold→--weight-semibold), own-token prefixes (--island-bg→--x-island-bg), the manifests, and oneadd-roleitem per functional role the system lacks, eachstatus: needs-judgement.- Judge what is left open — only the
needs-judgementandneeds-pickitems, from the system's own colours and type (readcolors_and_type.css, itsREADME, its specimens). Write them to a JSON file as a list of plan items with the sameids:- an
add-roleitem becomes{ "id": "role:--scrim", "kind": "add-role", "status": "judged", "by": "ai", "values": { "light": "<value>", "dark": "<value>" }, "sources": ["--fg-0", "--bg-0"], "note": "<why>" }("*"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 oroklch(0.6 …)(V3). - 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 threeoptions, and apickedindex — the person picks in the chat first; never pick for them (V4). - a collision (
--xalready declared) is resolved as old meaning → new name, and written down in the item'snote(V1). - Do not add items of your own for canvases: the codemods are made at stage time.
- an
maude design ds-upgrade validate <ds> <judged.json>— refuses a breach of V1–V4 and V8 with exit 13 and names the item. Fix the item; do not loosen the check.maude design ds-upgrade <ds> --stage <judged.json>— copies.design/to a throwawaybefore/andafter/outside the project, applies the plan toafter/, and writes the canvas codemods (onlyvar()names,classNametokens, import lines and meta keys change — V6). Canvases left out at an older revision,pinnedcanvases andui/v2/**get no codemod (V7, Q2). The live tree is untouched. It prints the stage's stamp.maude design ds-upgrade <ds> --prove <stamp>— 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,--discardthe stage and start again from step 3.- 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.
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/_components.css before you stage, so both copies carry it.
Housekeeping. maude design ds-upgrade <ds> --status lists the system's live stages (staged, being proved with current/total, proved with its review); --cancel <stamp> stops a proof in flight; --discard <stamp> 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).
Animation tooling contract (authoritative — DDR-049)
This is the single source of truth for how animation is authored in Maude.
It applies identically to specimens (system/<ds>/preview/*.tsx) and
canvases (ui/*.tsx). When /design:new, /design:edit, /design:setup-ds,
or any critic touches motion, this section wins over any looser phrasing
elsewhere. Other docs (commands/new.md, templates/.../SUB-AGENT-PROMPTS.md,
agents/motion-critic.md, agents/design-system-keeper.md) link here rather
than restating the rule.
Default — Motion One via canvas-lib (MUST). Any animated UI MUST use the
canvas-lib motion vocabulary from @maude/canvas-lib, which wraps Motion One
(motion/react):
<MotionDemo role>— the 8 canonical roles:flip·panel·route·soft·spring·scroll·drag·presence. Each binds a--dur-*+--ease-*token pair, clips its own bounds (overflow:hidden), and defaults toloop="always"so motion is visible on first paint (closes the "looks dead until you hover/replay" failure mode).<MotionTrack>(staggered rows),<TokenPlayback>(replay chip),<ReducedMotionToggle>(in-browser reduced-motion preview),useMotionTokens(),easingFromToken().motion/reactis declared as a peer dep of canvas-lib and emitted into/design:handoff'sregistry-item.jsonautomatically — handed-off canvases animate in a Next.js + shadcn target with no manualnpm i.
Escape hatch — pure-CSS .motion-* classes (opt-in, must be justified).
Zero-JS surfaces may use the role classes shipped in _components.css
(.motion-flip … .motion-presence) — same token bindings, same bounded
keyframes, no JS. Legitimate ONLY for declared zero-runtime cases: static hero,
a single hover/focus transition, an accessibility-first marketing page. Choosing
the escape hatch over <MotionDemo> MUST be recorded with a one-line reason
(canvas .meta.json note, or the DS bypass log for a specimen).
Never:
- Hand-roll
@keyframesfor any of the 8 roles when a<MotionDemo role>/.motion-*equivalent exists. (motion-critic+design-system-keeperenforce this — warning in ordinary canvases, blocker in themotion.tsxspecimen, which is the teaching artifact and must model the canonical path.) - Add
!importantreduced-motion overrides anywhere except the motion specimen's<ReducedMotionToggle>chrome. Tokens already collapse--dur-*to1msunder@media (prefers-reduced-motion: reduce); withmotion/reactuseuseReducedMotion()and short-circuit theanimateprop.
Decision rule when generating: brief implies motion (animate, transition,
play, loop, slide, fade, drag/drop, route transitions, presence cursors,
scroll-linked) → reach for <MotionDemo role> first; drop to .motion-* only
for a justified zero-JS surface; never reinvent keyframes for a named role.
Companion skills
design— user-facing orchestrator (canvas-first iteration loop)ui-kit— pointer to project-specific reference surfaces / componentsfrontend-design(external plugin) — generates new canvas files using these tokens
Cross-links
- READ flow:
_read.md - BOOTSTRAP flow:
_bootstrap.md - Discovery probes:
_pastier-probe-templates.md - Inspiration library:
plugins/design/templates/design-system-inspiration/ - Mapping contract:
plugins/design/templates/design-system-inspiration/_MAPPING.md - Tokens (authoritative, post-scaffold):
<designRoot>/<tokensCssRel>(single-DS) or<designRoot>/system/<ds>/colors_and_type.css(multi-DS) - Live specimen browse: dev server at
http://localhost:<port>/<designRoot>/system/... - Per-repo config:
.design/config.json - Completeness-critic:
plugins/design/agents/design-system-completeness-critic.md - Stage-2 research agent:
plugins/design/agents/ux-research-agent.md(modediscovery) - Stage-2 payload cache:
<designRoot>/_history/_system/<ds>-<brief-sha8>-domain-research-discovery.json(brief-hash in key — different briefs in same DS get separate cache files)
04 同仓库更多 Skills
workflow-state
Read and update workflow state when planning, executing, completing, pausing or resuming project work.
ui-rules
UI hard-stop rules and audit method: WCAG 2.1 AA accessibility, responsive layout and motion.
testing-rules
Apply test quality rules during implementation and review: meaningful assertions, isolation and coverage.
security-rules
Apply application and AI security checks to code reviews, implementation and threat-driven validation.
scenario
Author or run cross-platform UI scenarios with selectors, screenshots, platform coverage and result reports.
question-protocol
Batch necessary questions from workflow participants, collect user answers and route them to the requester.