Updated 5 September 2026 · Written for developers using Cursor, Claude Code, Lovable, Bolt and similar AI coding tools.
Why a DESIGN.md beats another vague prompt
“Make it clean and modern” is not a design system. It leaves the model to choose the font, colour, spacing, radius, layout and motion again on every screen. That is why one page gets a blue button, the next gets an indigo button, and every section slowly drifts.
A DESIGN.md fixes the decision layer. Your agent still writes the code, but it stops improvising the visual language.
One visual source
Every screen reads the same colour roles, type scale and spacing rhythm.
Fewer correction loops
You stop repeating “use the same button and spacing as before.”
Explicit boundaries
Do-not rules stop purple gradients, random shadows and invented components.
Why this keyword matters now
Google Stitch introduced DESIGN.md as an agent-friendly way to move design rules between design and coding tools, then open-sourced the draft format in 2026. Read Google’s announcement.
What a useful DESIGN.md should contain
Design direction
The product feeling, references, visual personality and defaults the agent must avoid.
Role-based colours
Not merely hex codes: base, structure, accent, muted and panel, with rules for each.
Typography hierarchy
Display, body and mono families, weights, sizes, line heights and where each belongs.
Layout and spacing
Container widths, spacing unit, section rhythm, breakpoints and approved hero structures.
Components and states
Buttons, cards, forms, navigation, hover, focus, disabled, loading and error states.
Accessibility and do-not rules
Contrast, keyboard focus, reduced motion and a hard list of generic patterns to reject.
Free DESIGN.md starter template
This free template gives you the correct structure without giving away a generated Pro system. Replace the placeholders manually, or use Pixel Perfect Pro to produce the filled visual brief and its companion exports.
# DESIGN.md — [PROJECT NAME] ## Design direction - Desired feeling: [calm, capable, precise] - Avoid: generic gradients, arbitrary colours, equal visual weight ## Colour roles --color-base: [#HEX] # 60% backgrounds --color-structure: [#HEX] # 30% text and dark sections --color-accent: [#HEX] # 10% primary actions only ## Typography - Display: [font / size / line-height] - Body: [font / size / line-height] ## Agent rule Read this file before generating UI. Reuse its tokens. Ask before inventing an undefined visual decision.
How to use DESIGN.md with Cursor
- Save
DESIGN.mdin the root of your project. - Create
.cursor/rules/design.mdc. - Tell Cursor to read the design file before any UI task.
- After generation, ask it to audit the result against the same file.
--- description: Apply the project design system to every UI change globs: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.css"] --- Before generating or editing any interface, read @DESIGN.md. Use only its approved colours, typography, spacing and component rules. Do not invent new gradients, shadows, radii or layout patterns. After the change, audit the result against DESIGN.md.
How to use the same file with Claude Code
Keep product instructions in CLAUDE.md and visual instructions in DESIGN.md. Connect them with one short rule:
# Visual system Before any frontend task, read DESIGN.md in the project root. Treat its colours, typography, spacing, components and do-not rules as constraints. Preserve application logic. If a visual decision is undefined, ask instead of guessing.
What Pixel Perfect generates
The companion is not a URL-to-style extractor. You intentionally choose a visual direction, preview it and then export a system. That distinction matters: the result reflects decisions you approved rather than colours scraped without context.
| Output | Free demo | Pro tool |
|---|---|---|
| Live palette, font and layout preview | Included, limited choices | All presets |
| CSS tokens | Included | Included |
| DESIGN.md | Locked | Generated |
| AI master prompt | Locked | Generated |
| Full HTML, Tailwind and tokens JSON | Locked | Generated |
| WCAG report and seven tuning controls | Locked | Included |
Frequently asked questions
What is a DESIGN.md file?
A DESIGN.md file is a Markdown document that gives AI coding agents a visual source of truth: colour roles, typography, spacing, layouts, components, motion, accessibility rules and explicit do-not rules.
Does Cursor read DESIGN.md automatically?
Do not rely on the filename alone. Put DESIGN.md in the project root and add a Cursor project rule that tells the agent to read it before generating or editing UI.
Can Claude Code use the same DESIGN.md?
Yes. Keep DESIGN.md in the repository and reference it from CLAUDE.md or directly in the task. The visual rules remain separate from engineering and product instructions.
Is the starter template the same as the Pro export?
No. The free starter is a blank structure you fill manually. Pixel Perfect Pro fills the system from your selected palette, typography and layout and supplies additional production exports.
What does Pixel Perfect Pro export?
Pro exports CSS tokens, DESIGN.md, an AI master prompt, a complete HTML hero, Tailwind configuration, design-tokens JSON and a WCAG accessibility report.