| name | design-workflow |
| description | Use when building or redesigning a product UI/visual system — creating a design system, writing or following a DESIGN.md contract, generating screens in a design tool (Stitch/Figma) then porting to code, or doing a branded visual redesign. |
Design Workflow
For building a product's look — a design system and the screens that follow it —
as opposed to wiring features (milestone-workflow) or shipping a library
(artifact-build). The spine: a DESIGN.md contract is the source of truth;
tool-generated screens and ported code both conform to it.
Read the repo's CLAUDE.md first for the stack and where design docs live.
1. The DESIGN.md contract (write it first, read it every time)
A single DESIGN.md is the design source of truth, written to be read
end-to-end before generating any page — "do not paraphrase, summarize, or skip
sections." It hard-codes:
- Creative north star — one named, opinionated direction (e.g. "The Sovereign
Vault"), anti-generic. Not "clean and modern."
- Signature patterns — the 2–4 distinctive components that ARE the product
(e.g. a Vulnerability Dossier, a Coverage Ledger, a verdict hero). Name them.
- Token palette + type — exact colors/tokens, fonts (e.g. mono for
addresses/hashes/codes), spacing. A locked semantic color contract where
meaning matters (e.g. severity → fixed hexes).
- Structural rules — e.g. a "No-Line rule" (sectioning via background shifts,
not 1px borders), depth via tonal layering vs shadows — whatever the north star
implies, stated as a rule.
- Honesty + anti-clichés — an explicit forbid list: no "Powered by AI" copy,
no emoji icons, no gradient-text headings, no "Welcome back, 👋", no
three-up feature-card filler, no fabricated numbers in the UI. A number on
screen is real or absent.
2. Tool → contract → code
When using a design tool (Stitch, Figma) to generate screens:
- The generated screens are the spec for layout/visuals — keep the export
(
code.html + a rendered screen.png per screen) as the reference.
- Port screen-by-screen into real components, each verified against BOTH the
screen.png AND the DESIGN.md contract (not a paraphrase of it). Verify in the
live local stack at the real target viewport (e.g. 390×844 mobile).
- Generate a separate design-system spec for the tool if it has one
(taste-design/design-md output), distinct from the hand-authored contract.
- For generated imagery (illustrations, scene art), keep the generation prompts
in a script and the honest-frame guardrails with them.
3. Versioned redesign / supersession
A visual system v2 doesn't silently overwrite v1 — write a new spec that
explicitly supersedes the old contract and names which rules it overrides
(e.g. "v2 supersedes v1, specifically its no-shadows rule"), validate it
visually against an example before porting, then roll it
across all surfaces. Brainstorm → spec → plan, same as any build.
Companion: aesthetic judgment
This skill is the process/contract layer. For the aesthetic-judgment layer —
making distinctive, non-templated visual choices — Anthropic's official
frontend-design skill is the companion (brainstorm → critique → build, signature
element, and the anti-default calibration: avoid the AI-cliché looks of
cream+serif+terracotta, near-black+acid accent, or broadsheet hairlines unless the
brief asks for them). Use it for the look; use this for the workflow.
Cross-cutting
Honesty in copy and numbers above all; match the surrounding code's idioms when
porting; verify each screen against the contract before moving on; respect
prefers-reduced-motion for any motion; don't ship a screen the contract forbids.
See PROVENANCE.md for sources.
