design-md

Authoring DESIGN.md

A DESIGN.md is a single, self-contained, plain-text file that hands a coding agent everything it needs to generate UI that looks intentional and on-brand. It pairs machine-readable design tokens (YAML front matter) with human-readable design rationale (Markdown body).

It exists because design quality, when an LLM is doing the building, is bottlenecked less by precise pixel values than by how clearly the intent is described. A hex code tells the model what to paint; the prose tells it why, and therefore how to make the hundred small decisions the tokens don't cover.

The one idea that matters most: prose carries the design

The single biggest lever on output quality is the Markdown body, not the token table. Two principles drive everything:

1. A specific reference beats a pile of adjectives. "1970s graduate-seminar

handout," "the dashboard of a high-end EV," "a Swiss pharmaceutical brochure," or "Bloomberg terminal meets a luxury watch catalog" each collapse thousands of decisions into one shared mental image. "Clean, modern, professional" describes a region so large it constrains nothing. Always reach for the concrete referent.

1. What you exclude defines the design as much as what you include. A good

reference carries its own negatives — "brutalist newsprint" already rules out drop shadows, gradients, and rounded corners without you listing them. When a constraint isn't implied by the reference, state it: "never use pure black (#000); the darkest ink is #1A1C1E," "no decorative shadows — depth comes from borders only."

If you internalize nothing else: write the prose like you're briefing a talented designer who has never seen the product, then let the tokens record the specifics.

Workflow

1. Establish the design intent

Before writing anything, get a vivid picture of the look-and-feel. The path depends on where the user is starting:

• •Net-new from a brief or vibe. Interview lightly for the essentials you can't

invent: product purpose, audience, emotional target, and any hard brand constraints (existing logo colors, required fonts, light/dark, accessibility bar). If the user gives you only a vibe ("cosmic music festival," "calm meditation app"), that's enough to start — propose a concrete reference back to them to confirm you're aligned ("So, think obsidian glass over a nebula, amber 'diamond-ring' accents — yes?").

• •Extracting from something that exists (code, a screenshot, a live site, a

Figma export). Pull the real values rather than guessing. See references/extracting.md for how to harvest tokens from CSS/Tailwind/components, sample colors from an image, and infer the prose rationale from observed patterns.

Don't over-interview. Two or three pointed questions, then draft — it's faster to react to a concrete draft than to answer twenty abstract questions.

2. Write the token front matter

The YAML captures the values that benefit from consistency. Keep it to what you'll actually reference; an exhaustive token dump that nothing uses is noise. The required shape and every field type live in references/spec.md — read it before writing the front matter so colors, typography, dimensions, and {token.references} are well-formed and will pass the linter.

Minimum viable front matter: name, a colors block, and a typography block. Add rounded, spacing, and components as the design calls for them.

3. Write the prose body

This is where the design actually lives. Use these sections in this order — they map to how a designer reasons from feel down to specifics:

## Brand & Style        — the core reference, personality, emotional target
## Colors               — what each role means and when to use it (not just hex repeats)
## Typography           — the type's voice; pairing logic; hierarchy rules
## Layout & Spacing     — grid, rhythm, density, how things breathe
## Elevation & Depth    — how layering is expressed (shadow? blur? border? glow?)
## Shapes               — corner language, stroke weights, geometric vs. organic
## Components           — how the signature components should feel and behave
## Do's and Don'ts      — the explicit guardrails, especially negative constraints

Drop sections that don't earn their place (a flat design needs no Elevation section). The prose should explain reasoning, not restate tokens — "font weight steps up one tier on frosted glass to survive the background blur" teaches the model something the fontWeight: 600 value alone cannot.

4. Validate

If the @google/design.md CLI is available, lint the file so token references and types are sound:

npx @google/design.md lint DESIGN.md

Then do the read-aloud test yourself: could a designer who has never seen the product build something recognizably on-brand from this file alone? If a key decision rests on a value with no explanation, add the why.

Worked examples

references/examples.md contains two complete, real DESIGN.md files (a glassmorphic weather UI and a "cosmic eclipse" festival site) showing the token-to-prose relationship end to end. Read it when you want a concrete model to pattern-match against — especially for how the prose references tokens and states negative constraints.

Common failure modes to avoid

• •Adjective soup in Brand & Style. "Modern, clean, sleek, professional, elegant"

constrains nothing. Replace with one concrete reference the model can picture.

• •Prose that just narrates the YAML. "The primary color is blue (#1E3A8A)." The

reader already has the token. Say what blue does and means here instead.

• •Token sprawl. Fifty colors no component references. Define the roles you use.
• •Silent assumptions. If the design forbids something common (gradients, shadows,

pure black), say so explicitly — the model's default is to add them.

• •Inventing values when real ones exist. When extracting from a real UI, measure;

don't approximate from memory.