DESIGN.md in plain English
**DESIGN.md** is a project-root markdown file that documents your brand for humans and AI coding tools: colors, fonts, spacing, component notes, and do/don't rules. Unlike a PDF brand book or a Figma file, it lives in the repo where Cursor, Claude Code, and similar agents already look for context.
Think of it as a brand kit written for agents. When the model opens DESIGN.md before styling a page, it stops inventing a new blue, a new font stack, and a new border radius on every chat. That is why teams treat DESIGN.md as the missing layer between "looks good in the playground" and "ships consistent UI."
If you only remember one thing: a logo PNG is not enough. Agents need **named tokens and written rules**. DESIGN.md is that format — and you can generate it free with the DESIGN.md generator or full AI brand kit.
Why DESIGN.md beats vibe prompts
Prompting "make it look premium" fails because the model has no durable memory of your tokens. DESIGN.md gives every session the same source of truth.
- **Repo-native** — committed next to AGENTS.md so every clone and every agent sees it
- **Human-readable** — designers and PMs can edit markdown without opening Figma
- **Agent-readable** — plain text loads into Cursor/Claude context without plugins
- **Export-friendly** — pairs with tokens.json and CSS variables for production
- **Versioned** — brand changes are pull requests, not Slack screenshots
- **Portable** — same file works for Cursor, Claude Code, Windsurf, and v0 brand kit workflows
What to put in DESIGN.md
Keep the file short enough that agents always load it. Aim for one screen of tokens plus clear component guidance — not a novel.
- **Product vibe** — one sentence: who the product is for and the visual tone
- **Color tokens** — semantic names (primary, muted, border, surface) with hex values and usage notes
- **Typography** — headline + body Google Fonts, weights, and when to use each
- **Spacing & radius** — a small scale agents should not invent outside of
- **Component rules** — buttons, cards, forms: reuse existing components, no raw hex in JSX
- **Don'ts** — Inter-by-default, purple gradients, emoji icons, random new fonts
- **Export hooks** — pointer to tokens.json / Tailwind `@theme` if you use them
When you need DESIGN.md
Use DESIGN.md whenever AI writes UI more than once. Solo founders use it to stop dashboard drift. Agencies drop a client DESIGN.md into every repo. Product teams treat it as the bridge until a full design system ships.
- Indie SaaS — generate once, reuse for landing + app + admin
- Client builds — export brand kit for AI agents with DESIGN.md in the zip
- Design-to-code — hand engineers tokens without a Figma seat for every contractor
- Multi-agent teams — Cursor, Claude Code, and v0 share one brand file
FAQ
- Is DESIGN.md an official standard?
- It is a community convention popularized by AI coding workflows — not a W3C spec. The format works because markdown is universal and agents already read repo docs. AI Brand Kits generates a consistent structure so teams do not invent incompatible layouts.
- Where should DESIGN.md live?
- At the repository root (next to README.md and AGENTS.md) so agents discover it without path guessing. Monorepos can add a short pointer in the root file to packages/ui/DESIGN.md.
- How is DESIGN.md different from tokens.json?
- DESIGN.md explains intent and rules in prose plus examples. tokens.json is machine-readable values for imports and theme providers. Use both — see tokens.json brand kit.
- Can I generate DESIGN.md automatically?
- Yes. Use the free DESIGN.md generator or full brand kit generator, refine in the playground, and download. URL import can seed colors and fonts from an existing site.
- Does DESIGN.md work with Claude Code?
- Yes. Place it in the repo and reference it from CLAUDE.md or AGENTS.md. See brand kit for Claude Code for the full workflow.
Related
Free tools
Interactive utilities you can use without an account. Each tool links to related guides and export workflows across the site.