Every AI design tool ships with the same pitch: "describe your UI, get a design." Then you use it, and it hands you back a screen with the wrong colors, rounded corners that don't match, and buttons that look nothing like your brand. The tool isn't the problem. You never gave it the brief.
A design.md file is the brief. It's a plain-text version of your design system, written specifically for AI agents to read and apply. And in a year where every AI tool you use — Claude Code, Google Stitch, v0, Lovable, Cursor — is reaching for your design system, the design.md file is quietly becoming the most leveraged artifact a product team can own.
Table of contents
- What is a design.md file?
- Why design.md matters for AI-driven design
- What goes inside a design.md file
- How to write a design.md with your engineering team
- design.md template and tools
What is a design.md file?
A design.md file is a markdown document that describes a product's design system — colors, typography, spacing, components, and rules — in a format AI agents can read and apply when generating UI. Think of it as a design system blueprint rewritten for machines instead of designers. Colors become tokens with hex values. Typography becomes a ruleset. The do's and don'ts that usually live in a senior designer's head become explicit lines in a file.
Sometimes called a DMD file, design system markdown, or AI design spec, the core idea is the same: give AI tools a single, structured source of truth so they generate UI that actually looks like your product.
In practice, a design.md file looks like:
- A top-level description of the product, tone, and design principles
- Color tokens with hex values and usage rules (primary, secondary, semantic)
- Typography specs (font families, sizes, weights, line heights)
- Component rules (button radii, input states, card patterns)
- A list of explicit don'ts ("don't use full-uppercase text," "don't nest cards")
If that sounds like a Figma design system written in text, that's exactly what it is — with the addition of behavioral rules that are hard to encode in Figma but easy to encode in plain English.
design.md vs. Figma design system
A Figma design system is optimized for humans: designers pulling components, engineers inspecting specs. A design.md file is optimized for agents: LLMs reading tokens and rules to generate consistent UI. Both can coexist — the design.md is often a distilled, text-native mirror of the Figma library, plus the explicit rules that never made it into Figma.
design.md vs. design tokens JSON
Design tokens (JSON, Style Dictionary, W3C format) are machine-readable values — colors, spacing, type scales. A design.md file wraps tokens in context and rules. Tokens tell an agent what values exist; a design.md tells it when to use them and when not to. For AI prompts, that context is the difference between "pick a primary color" and "use the primary button color on one CTA per screen, never stacked."
design.md vs. a style guide PDF
A PDF style guide is a reference document. A design.md is a live instruction file. AI agents can read markdown directly in a prompt or repo context; they can't practically parse a branded PDF. If you already have a style guide, the design.md is the distilled, text-first version of it.
Why design.md matters for AI-driven design
AI design tools are only as good as the context you give them. When I tested Google Stitch on a real brand without a design.md, it invented a green color palette for a design system that has no green. When I pasted in the design.md, it corrected the typography to the right font family on the first try. That gap — between "ignores your brand" and "respects your brand" — is almost entirely upstream of the tool.
This isn't a silver bullet. AI tools still hallucinate corner radii, misapply colors, or over-index on parts of the file. But a design.md file moves the baseline from "unusable output" to "usable with a few nudges," which is the difference between AI tools being a toy and being part of your workflow.
If you build one well, you get:
- Consistent output across tools. The same design.md works in Claude Code, Cursor, v0, Lovable, and whatever AI tool ships next quarter. You write it once.
- Better prompts, fewer iterations. Explicit don'ts cut bad generations dramatically. Every correction you'd otherwise type in a prompt becomes a rule in the file.
- Real alignment with engineering. A shared, living file beats a Figma library nobody opens. Engineers read markdown. So does the AI writing their code.
What goes inside a design.md file
The best design.md files I've seen read like a senior designer briefing a junior designer on day one: here's the product, here's the personality, here's what we do, here's what we never do. Below is the structure I use:
1. Product and principles
The problem: AI tools default to a generic aesthetic — rounded corners, pastel gradients, SaaS template vibes. Without context, every product ends up looking like every other product.
The solution: Open the file with 3-5 sentences on what the product is, who it's for, and the tone. Then list 3-5 design principles: "clarity over density," "motion sparingly," "high contrast for data-heavy views." Short, opinionated, specific.
The result: Output that feels like your product, not a Dribbble shot.
2. Color tokens with usage rules
The problem: Raw hex values aren't enough. An AI will happily use your primary color on every button, inflating visual weight and breaking hierarchy.
The solution: List every color token with its hex, its role (primary, neutral, semantic: success, warning, destructive), and when to use it. Example: "primary.900 — used only for the highest-emphasis action on a screen. Never two per view."
The result: Correct colors and correct hierarchy. The second one is the harder problem.
3. Typography rules, not just a type scale
The problem: Dumping a type scale in gives the AI options. Options lead to inconsistent use across generations.
The solution: List the type styles by name and purpose: display/xl — page titles only, body/md — default paragraph text, label/sm — form labels and metadata. Specify the font family once at the top so the tool can't drift.
4. Component and layout rules
The problem: AI-generated components drift over sessions. Button radii change, input heights shift, card patterns mutate.
The solution: Pin the rules. Button radius: 8px, always. Card padding: 24px, always. Form field height: 40px. Write them as absolutes, not ranges.
5. The don'ts section
The problem: Telling an AI what to do is easy. The hard part is telling it what not to do — and the don'ts are often where your brand's specificity lives.
The solution: A dedicated section of explicit don'ts. "Don't use full-uppercase headers." "Don't stack more than two CTAs." "Don't use drop shadows on cards — we use borders." This was the single biggest accuracy improvement I saw across every AI tool I tested.
The result: Fewer re-prompts. I noticed this pattern across Stitch, Claude Code, and v0 — the don'ts pulled more weight than the do's.
How to write a design.md with your engineering team
You don't need a quarter-long design systems initiative to start. A usable v1 takes an afternoon. The trick is writing it with engineering, not handing it over.
1. Start from your real product, not an aspiration
Open the product you ship today. Screenshot five core screens. Pull the actual hex values, font sizes, and radii from the code. Write the file to match reality, not the redesign you wish you'd shipped. Aspirational design.md files generate aspirational UI that doesn't match your repo.
2. Write it in the repo, not in Notion
The file should live in your codebase, alongside the code that references it. /design.md at the root, or /docs/design.md. This is the single decision that makes the difference between "a file we wrote once" and "a file the team (and the AI) actually uses."
Ask yourself: can Claude Code read this file from the repo in one command? If yes, you're set up right.
3. Co-author with engineering from the start
This is the part most teams skip. The design.md is not a design deliverable — it's a shared contract. Get an engineer in the room while you draft it. They'll catch the rules that don't match the code, the tokens that don't exist in the theme, and the components you forgot you renamed six months ago.
At TDP we build design.md files alongside client engineering teams as part of prototype projects — half an afternoon with both sides in the room beats a month of one-sided documentation.
4. Lead with don'ts, not just do's
Once the structural sections are in place (colors, type, components), add the don'ts section last and make it specific. Walk through a handful of real AI generations from your tools and write a don't for each bad output. That's how you turn the file from documentation into a working filter.
5. Test it with the AI tools you actually use
Paste the file into Claude Code, Cursor, v0, or whichever tool your team is on. Ask it to generate a simple screen. Compare output with and without the design.md in context. The delta is the proof. Iterate the file based on what the AI still gets wrong — that's your real feedback loop, and it's much faster than waiting for humans to file tickets.
Doing this well doesn't require a huge lift. A first-pass design.md that covers colors, type, spacing, and ten don'ts will outperform a generic design system spec in every AI tool you feed it.
design.md template and tools
There's no single canonical format for design.md yet — the ecosystem is still early. What matters is that the file is readable by an AI in context and covers the categories above.
A few starting points:
- W3C Design Tokens format — the emerging standard for token structure. Pair a tokens JSON file with your design.md for the best of both worlds. See the spec
- Style Dictionary by Amazon — generates tokens across platforms; useful as the source your design.md references. styledictionary.com
- Your existing Figma library — your design.md should mirror your Figma components and tokens, not diverge from them
- Claude Code's
CLAUDE.mdpattern — if you're already using Claude Code, your design.md can sit alongsideCLAUDE.mdin the repo and be referenced from it
If your team is spending more time correcting AI-generated UI than shipping it, the problem is almost always upstream of the tool. We help B2B SaaS teams set up design.md files and AI design workflows as part of our prototype projects at TDP — most clients see the bad-generation rate drop by more than half in the first week after adopting one.
Want help writing your first design.md with your engineering team? We run hands-on workshops walking product teams through the full design-to-code AI stack — including how to structure a design.md that your AI tools actually follow. Sign-up for a design-to-code workshop
