A DESIGN.md only works if the machine reading it never has to guess. That is the whole craft of writing one: put orientation before detail, state values instead of adjectives, and cover the components the agent will actually build.
If you're new to the format, start with What is a DESIGN.md? — this post is the practical sequel: the structure that works, and the mistakes that quietly break it.
Start with orientation, not detail
The first thing in the file should tell the machine what it is looking at: the style's name, a one-line essence — the sentence you would use to describe the look to someone who has never seen it — and the flags that change everything downstream, like whether the style is light or dark.
Most specs put this in a small structured block at the top (YAML frontmatter is the common convention, and the one Google's open DESIGN.md spec uses). An agent reads that block first and interprets every later section through it. A file that opens with fifty color values and no orientation makes the model reconstruct the intent — which is exactly the guessing you are trying to eliminate.
---
name: <style name>
essence: <one sentence: the look, to someone who has never seen it>
isDark: false
---
State values, not adjectives
"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.
Name your tokens by role, not by appearance: background, ink, accent, line — not "light gray" or "blue". Role names survive theme changes and tell the agent where a value belongs, not just what it is.
Keep prose in the file, but give it a job: explain why the values are what they are and how they combine. "The accent is reserved for one action per screen" is prose an agent can obey. "The palette feels calm" is not.
Cover the components the agent will build
Tokens alone underdetermine a UI. Two styles can share a palette and still look nothing alike, because the difference lives in component logic: are buttons filled or outlined, sharp or rounded? Do cards float on shadows or sit inside hairline borders? Is emphasis done with weight, size, or color?
Write these as short declarative rules for the handful of components that appear everywhere — buttons, cards, inputs, navigation. Then add usage bounds: where the style fits and where it does not. An agent that knows a style is built for editorial pages will not force it onto a dense dashboard.
The mistakes that quietly break a spec
Adjectives without values. The most common failure: a beautifully written mood description with no numbers. The agent nods along and then invents its own palette.
Dumping the whole brand book. A DESIGN.md is a working spec, not an archive. If the file takes longer to read than the screen takes to build, the agent will skim — and skimming is guessing with confidence. Keep it to what changes the output.
No usage bounds. A spec that never says where the style should not go gets applied everywhere, badly.
Letting it rot. The file is plain text in your repo; treat it like code. When the design changes, the DESIGN.md changes in the same commit — otherwise the agent faithfully applies last quarter's design.
Inconsistent internal references. If the type section says one scale and a component example implies another, the agent has to pick one — and it will not tell you which it picked.
FAQ
How long should it be? As short as it can be while still deciding every visual question the agent will face. In practice that is usually a page or two: one orientation block, the core token sections, component rules for the recurring elements, and usage bounds. If a section would not change what the AI builds, cut it.
Where does the file live? The project root, next to README.md — that is where coding agents look first, and it follows the convention the name implies.
One file or several? One. The point of the format is that an agent reads the whole design system in a single pass. The moment the spec is spread across files, you are relying on the agent to find and reconcile them — reintroducing the guessing the format exists to remove.
Do I need YAML frontmatter? It is the convention Google's open spec uses and the easiest block for a machine to parse, so it is a good default. But the deeper rule is orientation-before-detail: whatever the syntax, the file should open with what the style is before it lists values.
Or skip the writing: pick a ready-made one
Writing a DESIGN.md is worth it for a design system you own. But if what you want is an established style — Bauhaus, Swiss International, a contemporary brand-grade look — writing the file means reverse-engineering a whole movement's rules yourself, and getting them subtly wrong is the default outcome.
That is the case for a library. Curio ships hundreds of real design styles, each already encoded as a complete DESIGN.md — researched, structured, and ready for your AI to apply over MCP, a share link, or a download. Pick the style; the file is already written.
Originally published as How to Write a DESIGN.md on Curio. Related: a complete DESIGN.md example · Google Stitch's DESIGN.md, explained.
Top comments (0)