GUIDE
What is Design MD?
What is design md? It is the missing layer between a design reference and the code an AI agent produces: a plain markdown file that carries your colors, type rules, component states, and prohibitions into every generation session. This guide covers the format, the evidence behind it, and the workflow that makes agents follow it.
The missing design context
A DESIGN.md is a markdown file that encodes a product’s design system — color roles, typography rules, spacing, component states, and hard constraints — in language an AI coding agent can read and apply. It converts visual decisions that normally live in screenshots, a designer’s memory, or scattered CSS into a single artifact the agent consults before it writes code.
So what is design md in practice? It is the contract between whoever owns the visual decisions and the model that implements them. Without it, every prompt re-litigates the brand; with it, the design conversation happens once, in a file that ships with the repository.
Why AI agents need it
Claude Code, Cursor, Windsurf, and Codex can all produce valid JSX and CSS without understanding your hierarchy, your token roles, or the difference between a quiet secondary action and a primary conversion path. Left unguided, they default to generic choices: a random blue, rounded-lg on everything, shadow-md cards.
A DESIGN.md replaces vague requests like “make it clean” with checkable constraints: “never exceed font-weight 600”, “#0072F5 appears only on interactive elements”. Constraints like these are things a model can obey while generating and audit afterwards — which is exactly what makes agent output reviewable.
The anatomy of the file
The format used across this site — and by the generator — covers nine sections: visual theme and atmosphere, color palette and roles, typography, spacing and layout, components, shadows and elevation, borders and radius, motion, and a closing list of do’s and don’ts.
Two writing rules separate useful files from decorative ones. First, hard values early: tokens and rules at the top, prose rationale later, because agents and truncated context windows read top-down. Second, roles over adjectives: every color, weight, and radius gets a job description, not a mood word.
Evidence before interpretation
Anyone asking what is design md eventually asks the harder question: where do the values come from? The answer must be observation. Record the colors, fonts, radii, and shadows that actually appear in the product — from DevTools, from the CSS custom properties on :root, from computed styles — then describe the system those facts imply.
Our generator automates this step: it fetches a URL, mines the real stylesheets with occurrence counts, and writes the file from extracted evidence. However the draft is produced, the rule stands — an agent may adapt an interpretation, but it should never invent the evidence.
Using it with Claude Code, Cursor, Windsurf, and Codex
Commit DESIGN.md to the repository root and make it impossible to ignore: reference it from CLAUDE.md for Claude Code, from .cursor/rules for Cursor, or from the agent’s instruction file for Windsurf and Codex. From then on every session starts with the same visual constraints.
Scope prompts to one surface at a time, and after each UI diff ask the agent to audit its own changes against the file and list violations before fixing them. Models are notably better at auditing against a written spec than at remembering one they were never shown.
Keeping the reference current
A design file rots the day the design changes and the file does not. Update DESIGN.md in the same pull request as any visual change, and when you accept an agent’s deviation, write the exception into the file so it becomes a rule instead of precedent-by-accident.
Teams that treat the file like code — versioned, reviewed, owned — stop reviewing hex values in pull requests entirely. The file is the reviewer.
What is design md — FAQ
What is design md in one sentence?
A DESIGN.md is a markdown contract that encodes a product’s design system — tokens, component rules, and prohibitions — so AI coding agents produce on-brand UI instead of generic defaults.
Is a DESIGN.md the same as a design system?
No. A design system is the full set of decisions, components, and tooling; a DESIGN.md is the compact, agent-readable description of it. Think of it as the design system’s API documentation for language models.
Does it replace a component library?
No — it complements one. The component library enforces decisions in code; the DESIGN.md explains the decisions so an agent extends the system correctly instead of working around it.
How long should the file be?
Long enough to constrain code, short enough to consult while building — typically 1,200 to 2,000 words. Put tokens and hard rules in the first 80 lines; context windows and attention both favor the top of the file.
Where do I get one for my product?
Generate one from your live site with the free generator on this site, adapt a reference from the 54-brand library, or write one by hand following the nine-section format.
Get a DESIGN.md for your product
Paste your URL into the free design md generator or start from one of the 54 systems in the library.