AGENT SKILL

design-system

Ratify a visual DESIGN.md. Use for a UI design system: colors, type, layout, and component tokens. 視覺設計系統 / デザインシステム.

License 许可
MIT
所属仓库
kouko/loom-plugins
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
design-system
version
1.0.0
description
Ratify a visual DESIGN.md. Use for a UI design system: colors, type, layout, and component tokens. 視覺設計系統 / デザインシステム.

02 资源文件 3

03 SKILL.md 正文

What this tool does

Relative paths in this document are relative to this skill's own directory.

Deliver local documents with actual absolute paths from the active worktree or external location, including in copyable instructions. For known local Markdown support, use the document's project-relative path as link text (external files: basename) and absolute targets; otherwise show full absolute paths. Enclose targets with spaces in angle brackets: [doc.md](</worktree name/doc.md>). Preserve bundled references, stored relative paths, quoted examples and incidental filenames.

The user names a product with a UI. You run one short interview, write DESIGN.md at the consumer project's root, restate it, and — on "yes" — write the ratified-by: line. DESIGN.md documents the product's visual system only — brand, color, type, spacing, elevation, shape, and component tokens — never flows, screens, or navigation.

Step 1 — When to run

When a visual-system choice depends on missing consequential evidence about users or usage, identify that decision and use loom-design:design-research as needed. Reuse adequate evidence directly; return findings or uncertainty to this task without changing confirmed preferences, scope or ratification authority.

Run this before or during write-spec, for any product with a UI a user reads or types into. DESIGN.md is never required: an absent or unratified DESIGN.md never blocks a change, at any station — unlike PRINCIPLES.md, there is no reject rule for it. Run it on request, or when write-spec surfaces that the UI has no governing visual system yet and the user wants one before drafting flows.

Read PRINCIPLES.md at the consumer project's root first, when present, as the governing constraint every token must be defensible against. If it is absent, derive the direction from the user's own words in the interview below, say explicitly that the mood is derived rather than inherited, and proceed only on the user's say-so — never invent a constitution to satisfy this step.

Before inventing any color, type, or component convention not derivable from PRINCIPLES.md or the user's own words, check references/knowledge-triage.md and classify the question first; never guess a domain-semantic default.

Step 2 — Interview → DESIGN.md

Ask, in the user's own words:

  1. Brand and mood — a few adjectives for how the product should feel, and one committed visual direction (e.g. "editorial print weekly" / "utilitarian terminal").
  2. Palette — the brand color(s), and whether dark mode matters.
  3. Type — an existing type choice, or a general character (serif / sans / mono, tight / generous).
  4. Density and shape — compact or spacious, sharp or rounded.

Emit DESIGN.md at the consumer project's root (product-level, one per product — never per-feature), following references/design-md-schema.md for the section shape and content. Its YAML token blocks use the token groups scripts/interface/design_md_spec_keys.py freezes as the schema's source of truth — read TOKEN_GROUPS there for the exact set and do not retype it here; a value in this file that drifts from the script's is a defect in this file, not the script. Verify WCAG-AA contrast (body ≥ 4.5:1, large text ≥ 3:1) for every color pairing before presenting it; a failure is a blocker, not a note.

Then check the file's structure before showing it to anyone, with <loom-design> standing for this plugin's own checkout:

python3 <loom-design>/scripts/interface/validate_design_output.py DESIGN.md

Exit 0: go to step 3. Non-zero: fix what it names and run it again. Never read a DESIGN.md back to the user that has not exited 0 here — the restatement is the user's only view of the file, so a structural defect they cannot see is one they will ratify by accident.

Step 3 — Restate and ratify

Read the whole file back to the user in plain words — the committed direction, the palette, the type, the density — not a diff. On a correction, fix it and read back again. On "yes", write one line at the top of the file, directly under the title:

ratified-by: <name> <date>

<name> is the user's own name or handle; <date> is today, YYYY-MM-DD.

Step 4 — Commit

git add DESIGN.md
git commit -m "docs(loom): DESIGN.md ratified"

Downstream — how the rest of the flow uses it

write-spec reads DESIGN.md, when present, for its UI-flow vocabulary — the palette, component, and spacing tokens a flow's screens and states are described against — so its UI flows section names things this file already named, instead of inventing new visual vocabulary mid-spec. At closing-review, the design-conformance dimension scores the diff against DESIGN.md's tokens; with no DESIGN.md, or a finding it cannot speak to, the dimension is scored N/A with a one-line reason, never forced. A missing or unratified DESIGN.md never blocks any station.

<!-- gate: design-system.never-blocks --> This tool never rejects a change for lacking a ratified DESIGN.md. Only PRINCIPLES.md carries a reject rule (standing.product-principles-reject); DESIGN.md's absence is at most a WARN the checker prints, never a gate any station enforces.

04 同仓库更多 Skills