Design with a token contract

Machine-generated UI fails in a specific way. Not ugliness — incoherence. The third section introduces a fourth grey, the modal invents a shadow the rest of the page never uses, tomorrow's session picks a different blue, and the result reads as assembled rather than designed.

The fix is to make the design system an artifact instead of a memory. A DESIGN.md at the project root holds the tokens and the reasoning, gets validated, and gets read by whoever touches the project next — including you, next session. Every value in the code traces back to it. That single constraint is most of what separates a system from a pile of CSS.

Match the ceremony to the task. A fresh project that needs a whole visual identity earns the full path below. A single component in a repo that already has a DESIGN.md is Step 0 → Step 5 → Step 7, and that is the whole job. Do not make someone sit through a design exercise to get a button restyled.

If frontend-design also applies, use both. They do different jobs: frontend-design decides the taste — what makes this page distinctive rather than templated. This skill makes that decision durable, checkable, and consistent across sessions. Do the aesthetic thinking in Steps 1–2, then encode the result as tokens.

Step 0 — Is there already a DESIGN.md?

ls DESIGN.md docs/DESIGN.md .design/DESIGN.md 2>/dev/null

If one exists, it is the contract — read it in full and build from it. Do not quietly redesign around it. If it genuinely does not cover what you need, extend it (Step 6) rather than working outside it. If the user is explicitly asking for a redesign, say what you are replacing before you replace it.

Also worth a look: an existing tailwind.config, theme.ts, globals.css, or brand assets. A project often already has a de-facto system that nobody wrote down, and reverse-engineering it into a DESIGN.md is usually the highest-value thing you can do.

Step 1 — Pin the subject, then the direction

Design decisions come from the subject. If the brief does not say what the product is, who it is for, and what the page's single job is, decide it yourself and state your choice in one line — an unpinned brief is what produces generic output.

Then name the direction in plain words before touching any color: the canvas (dark, light, warm, paper), the density (dense and technical, or airy and editorial), the voice (precise, editorial, cinematic, playful, institutional), and what carries the page — photography, product screenshots, type, or data.

Two failure modes to steer around:

• The industry match. A fintech dashboard usually wants a data-dense reference, not another fintech's marketing site. Choose on character, not on category.
• The three AI defaults. Cream #F4F1EA + high-contrast serif + terracotta; near-black + one acid-green accent; broadsheet with hairline rules and zero radius. All three are legitimate when the brief asks for them, and all three are what you produce by reflex when it does not. If you land on one by default, that is a signal to look harder.

Step 2 — Source the system

Path A — adapt a reference. Read references/catalog.md and pick one or two systems whose character matches the direction. Read those files from references/library/<slug>.md in full, paying most attention to Do's and Don'ts — that section encodes what the designers deliberately ruled out, which is the part a palette dump can never give you.

Then extract the system logic and leave the identity behind. Keep the structure: how many surface levels, how scarce the accent is, how tracking curves across the type scale, what the system refuses to do. Replace the identity: accent hue, display face, photographic subject. A page wearing another company's exact palette and typeface is a knockoff, not a design — and it is also just worse work, because those choices were made for their brand and not for this one.

python scripts/design_md.py catalog --mode dark
python scripts/design_md.py catalog --grep 'editorial|gradient|mono'

Path B — author from scratch. When the brief has its own brand, or nothing in the library fits, derive tokens directly. references/format.md has the derivation method: surface ladders, ink steps, accent scarcity, the tracking curve, spacing base.

Either path, decide these five before writing anything:

1. Canvas — the anchor surface, and whether the system is single-mode or dual.
2. Surface ladder — 3–5 evenly stepped levels, each with exactly one job.
3. Accent — one chromatic accent, plus a written rule for where it may appear. Two accents is almost always a mistake.
4. Type — display face, text face, optional mono, plus the tracking curve. If a face is proprietary, name the licensed-free substitute now.
5. Depth — what carries hierarchy: surface ladder, shadow, or border. Pick one primary.

Step 3 — Write the DESIGN.md

Start from assets/DESIGN.template.md — a greyscale structural skeleton with every slot marked REPLACE. It is deliberately colorless so it cannot become a default look; you supply the identity, it supplies the shape. Full schema and section-by-section guidance in references/format.md.

Write it to the project root as DESIGN.md. Two things people get wrong:

• Quote every value containing #. YAML reads # as a comment, so primary: "#5e6ad2" is required and primary: #5e6ad2 # brand silently loses data. This is the most common corruption in real DESIGN.md files.
• components: hold token references, never literals. "{colors.primary}", not "#5e6ad2". A literal there means the token has stopped being a single source of truth.

The prose is not decoration. A generator that knows primary: #5e6ad2 but not "used only on the brand mark, focus ring, and one CTA" will paint the accent across the page. Write the rules down.

Step 4 — Check it before you build

python scripts/design_md.py check DESIGN.md

Validates structure, resolves every {token} reference, and runs WCAG AA contrast on every component declaring a background/text pair. Base states are errors; interaction states are warnings; disabled is a note.

Fix what it reports now, while it is one file — not after it is spread across forty components. Expect the accent-on-white CTA to be the failure: mid-tone accents need dark text, not white. Running this across the bundled library finds real WCAG failures in roughly half of it, because marketing sites optimize for brand voltage over contrast. Inheriting a contrast bug from a famous brand is still a contrast bug.

Step 5 — Build only from tokens

Generate the variable layer rather than retyping values:

python scripts/design_md.py export DESIGN.md --format css      -o src/styles/tokens.css
python scripts/design_md.py export DESIGN.md --format tailwind -o src/styles/theme.css
python scripts/design_md.py export DESIGN.md --format json     -o src/design-tokens.json

That file is a generated artifact — never hand-edit it; regenerate when DESIGN.md changes. references/building.md covers wiring into Tailwind v3/v4, CSS-in-JS, shadcn/ui and React Native, and the quality floor every direction owes regardless of style (focus-visible, 44px touch targets, reduced motion, 360px with no horizontal scroll, semantic HTML).

When you need a value the system does not have, add it to DESIGN.md and regenerate. It takes ten seconds, and it is the entire difference between a system and a pile of CSS.

Step 6 — Extend deliberately for product surfaces

Reference systems come from marketing sites, so they document heroes and pricing cards and say nothing about tables, form errors, modals, empty states, or disabled controls. This gap is where generated UI usually falls apart, because each new surface invents its own greys.

Derive from what exists rather than inventing: table headers sit on surface-1, row rules use hairline, error borders use semantic-danger, disabled text drops to ink-tertiary on an unchanged surface. references/building.md has the full derivation set. Whatever you add, write it back into DESIGN.md as a component entry — a system that grows in the code but not in the document stops being a contract after one session.

Re-run check after extending. When the change is substantial, the official CLI can tell you whether it regressed anything: npx @google/design.md diff OLD.md DESIGN.md reports token-level adds, removals and modifications, and exits 1 if the new file has more findings than the old.

Step 7 — Audit, then look again

python scripts/design_md.py audit src/ --design DESIGN.md

Reports color literals outside the palette and fonts outside the type system, with file and line. Exit code 1 means drift. Run it before calling the work done, and fix what it finds — either pull the value back to a token, or promote it into DESIGN.md if it earned its place.

Then look at the result, ideally rendered. Ask the two questions that matter: is the accent still scarce, and does every section obey the same spacing rhythm? Those two are where coherence dies first. Cut one decorative element that is not serving the brief.

Reference files

The library, honestly

The 74 systems in references/library/ come from VoltAgent/awesome-design-md (MIT) and record publicly visible CSS values from production sites. Three things to keep straight:

• Typefaces are usually proprietary. Linear Display, Sohne, SF Pro, Airbnb Cereal and most other custom faces are not licensed for your project. Most files carry a Note on Font Substitutes naming a free equivalent — use it. Never ship a font-family naming a face you have no right to serve.
• Logos, wordmarks and brand names are trademarks. Borrowing a system's structure is normal design practice; shipping its wordmark is not.
• Adapt rather than clone when the work is someone's own product. Cloning is the right call for a deliberate pastiche or a study; for a real product it produces a page that belongs to somebody else.