design-system
Ratify a visual DESIGN.md. Use for a UI design system: colors, type, layout, and component tokens. 視覺設計系統 / デザインシステム.
- License 许可
- MIT
- 最近更新
- 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
- 参考文档README.md1.4 KB
- 参考文档references/design-md-schema.md16.7 KB
- 参考文档references/knowledge-triage.md5.4 KB
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:
- Brand and mood — a few adjectives for how the product should feel, and one committed visual direction (e.g. "editorial print weekly" / "utilitarian terminal").
- Palette — the brand color(s), and whether dark mode matters.
- Type — an existing type choice, or a general character (serif / sans / mono, tight / generous).
- 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
using-loom-workflow
Route broad Loom workflow-tool requests to the right skill. Use when the request spans tools or the right workflow skill is unclear.
skill-retro
Review selected past or current Claude Code or Codex sessions against readable target skill sources and related integration. Produce source-linked proposals without applying changes.
recap-state
Give an in-session recap of current progress for 'where were we', '我們剛剛在幹嘛', '剛剛講到哪', '我跟丟了', 'ちょっと振り返って', '今どこだっけ', or '振り返り'. The built-in /recap is an away-summary.
project-retro
Review one current or specified coding session for source-backed project development improvements. Use for a requested retrospective, including 振り返り seeking improvements; not for current-progress recaps or recurring skill mining.
loom-visualization
Show comparisons, flows, decisions, states or reasoning chains as tables, ASCII or Mermaid in coding chat, including when a Loom station reports to the user (intent restatement, choices, acceptance test results); not Obsidian notes.
loom-memory
Record repo-wide lessons when saving to your own memory or asked to remember; recall, reconcile, or forget them when a task needs it.