7 DESIGN.md Tips for Taming AI-Generated UI
A single Markdown file can be the difference between AI-generated UI that looks random and one that feels like your brand. Here's how to write a DESIGN.md that actually works.
A DESIGN.md file is a portable design system you drop into your project folder so that AI coding tools like Claude Code stop guessing your visual language and start following it. If you've ever watched an AI generate a button with the wrong corner radius or a heading in the wrong weight, this is the fix.
The thesis here is simple: a well-written DESIGN.md is the closest thing designers have right now to a design token handoff that AI actually reads. Getting it right means your vibe-coded app stops looking like it was assembled from five different Figma kits.
What DESIGN.md Actually Is
The file is split into two parts. The top section is YAML frontmatter — think of it as a table of exact values: your hex codes, font sizes, spacing steps, border radii. The bottom section is plain Markdown prose — this is where you explain how those values get used together. Color the button primary blue; use the large spacing token between sections; reserve the bold weight for CTAs only.
AI tools like Claude Code read both parts together, which is what makes it more powerful than just pasting your style guide into a prompt.
7 Things That Make Your DESIGN.md Actually Work
1. If it can be a number, make it a number.
The single most important rule. Don't write "buttons should have slightly rounded corners." Write rounded-md: 8px in YAML, then reference that token everywhere. The AI picks the exact value instead of improvising. This applies to colors, type sizes, spacing — anything that has a concrete pixel or hex answer.
2. Give typography real roles, not just sizes.
Text drives the majority of how a product feels to use. Don't just list font sizes — label them. heading-1, body, caption, label. When the AI knows a role, it picks the right size and weight and line height for context, rather than guessing.
3. Define a spacing scale and stick to it. List your spacing steps (say, 4, 8, 16, 24, 32px) in YAML. Then in the prose section, explain the logic — tight spacing inside components, looser spacing between sections. A consistent scale is what separates "designed" from "assembled."
4. Name your components and describe their variants. If you have a Button, say so. List its states: default, hover, disabled, destructive. The more specific you are here, the less the AI invents variants you didn't ask for.
5. Explain your color intentions, not just your palette.
Listing #2563EB is fine. Saying "primary: #2563EB — use for CTAs and active states only; never use on body text" is much better. Intent beats inventory.
6. Call out what NOT to do. This is underrated. A short "avoid" section — no drop shadows on flat components, no more than two typefaces, no color outside the defined palette — acts like a guardrail. AI tools respond well to explicit constraints.
7. Keep it in the project root and keep it updated. DESIGN.md only works if the AI tool can find it and if it reflects your current decisions. Treat it like a living document, not a one-time setup. When you change a token in Figma, update the file.
How to Actually Get Started
You don't need to write the whole file before you build anything. Start with just the YAML section — colors, one type scale, one spacing scale — and a few sentences of prose about your primary button. Drop the file in your project root. Then prompt Claude Code to build a component and ask it to follow DESIGN.md. See what comes back.
From there, add to the file incrementally. Every time the AI makes a decision you didn't want, that's a signal: something wasn't specified. Add the rule. Over a few sessions you'll end up with a DESIGN.md that's genuinely tuned to your project.
This is a much lighter lift than writing a full design system from scratch, and it fits naturally into the way most designers already vibe-code — iterating in short loops.
The Honest Limits
DESIGN.md is only as good as the AI tool that reads it. Not every tool treats the file the same way, and complex layout logic (think: responsive grid behavior, motion design, conditional states) is still hard to specify in plain text without getting verbose. You'll also need to re-test after major Claude Code updates, since model behavior can shift.
That said, for the most common pain point designers hit in vibe-coding — why does every component look slightly different? — this file is the most direct solution available right now. It's a Markdown file. You already know how to write one.