A DESIGN.md is a design system written for a machine to read: one plain-text markdown file that encodes colors, typography, spacing, and component rules explicitly enough that an AI agent can apply them without guessing. The format was introduced by Google Stitch and has since been released as an open spec — today it works far beyond Stitch, in tools like Claude Code, Cursor, and any agent that can read a text file.
What a DESIGN.md is
A DESIGN.md is a single Markdown file that encodes a complete design system in a structured, machine-readable form. It pairs machine-readable design tokens (typically a YAML block the machine reads first) with prose sections that lay out the look — colors, typography, spacing, shapes, components, motion — explicitly enough that an AI can apply them without guessing.
The name follows the convention of README.md: a plain-text file, versionable and portable, that any tool can open. The difference is the audience. A README explains a project to a human; a DESIGN.md explains a design to a machine — the AI that will dress your slides, your site, or your product in that style.
Instead of prompting an agent with vague adjectives — "make it look modern and clean" — you drop a DESIGN.md into your project, and the agent applies your exact styles to everything it builds.
Where the format came from: Google Stitch
DESIGN.md entered the mainstream through Google Stitch, Google Labs' AI design tool. Stitch uses a design.md file as the persistent memory of your design system: it stores the palette, fonts, and styling rules so that every screen the AI generates stays consistent instead of drifting with each prompt.
In 2026 Google Labs released DESIGN.md as an open spec, so the same file works across tools and platforms rather than being locked to Stitch. Since then an ecosystem has grown around the format — coding agents like Claude Code, Cursor, and Codex read it from a project root, and libraries of ready-made DESIGN.md files have appeared, from community GitHub collections such as awesome-design-md to curated catalogs like Curio.
That is why the format matters: it is becoming the common language between design systems and AI agents. One file, written once, understood by whatever AI tool you use next.
What's inside a DESIGN.md
Metadata comes first: the style's name, a one-line essence, and flags like whether it is light or dark. This is the orientation a machine reads before anything else.
Then the token sections, each stated as concrete values rather than adjectives: a color section (a named palette — background, ink, accents — as exact values like hex), a typography section (font families, weights, and a type scale in px/rem), a spacing section (a rhythm in px), and shape, shadow, and motion sections (radii, elevation, easing).
Finally, applied guidance: component logic (how buttons, cards, and inputs should look in this style) and usage notes (where the style fits and where it does not). The combination is what lets an AI go from 'I know the rules' to 'I built the screen' — without inventing values.
Curio ships every style in its library as a complete file of this shape. The structure is open so anyone can see how a DESIGN.md is put together; the precise token values for each style are the paid product. The skeleton is public; the exact hex and px are what you unlock.
Why machine-readable beats a screenshot
A screenshot or a 'vibe' is lossy: the AI has to infer what mattered, and it infers differently every time — copying a color but missing the spacing logic, borrowing the type but not the grid. A DESIGN.md removes the guessing. The values are stated, so the AI applies them exactly, the same way on every screen.
Because it is one deterministic file, it is also consistent and reusable. The same DESIGN.md governs slide one and slide forty, this week's landing page and next month's dashboard. That is the difference between a look you stumbled into once and a system you can rely on.
And because it is plain text, it fits the way software teams already work: it lives in the repo, travels through Git, and changes to the design system show up as reviewable diffs instead of mystery drift.
How an AI uses a DESIGN.md
You hand the file to your AI in whichever way fits your tool: drop it in your project root for a coding agent to find, paste it into a chat, send a share link, or connect over MCP so the AI can pull it on demand. From there the model reads the tokens and applies them — generating components, slides, or pages that already match the style instead of drifting toward the average.
Because the format is plain Markdown, it is not locked to any one assistant. The same DESIGN.md works whether your AI lives in a chat window, a coding tool, or an agent pipeline — the spec travels with the work.
Should you write one or pick one?
Write your own DESIGN.md when the design system already exists and belongs to you — your brand, your product's look. Encoding it once means every AI tool you use applies it faithfully from then on.
Pick a ready-made one when what you want is an established style — Bauhaus, Swiss International, a brand-grade contemporary look — and you would rather not reverse-engineer it yourself. That is what a DESIGN.md library is for: Curio ships hundreds of real design styles, each as a complete DESIGN.md your AI can apply in seconds over MCP, a share link, or a download.
Frequently asked questions
Who created DESIGN.md?
The format was introduced by Google Stitch, Google Labs' AI design tool, as the file where Stitch keeps your design system. Google Labs later released DESIGN.md as an open spec so it can be used across tools and platforms — which is why coding agents like Claude Code and Cursor, and libraries like Curio, all speak it today.
Is DESIGN.md an official standard?
It is an open spec released by Google Labs rather than a formal W3C-style standard. In practice that distinction matters little: the format is plain Markdown with structured tokens, which means any AI or tool can read it without a special parser or a proprietary file type.
Does DESIGN.md only work with Google Stitch?
No. Stitch is where the format started, but because the spec is open and the file is plain Markdown, it works with any AI that can read text: Claude Code, Cursor, Codex, chat assistants, or your own agent pipeline. Drop the file in your project or hand it over a link, and the agent applies it.
Can I see the real token values for free?
The structure of a DESIGN.md is open — you can see exactly how one is shaped and what sections it contains. On Curio, the precise values for each style (the exact colors, sizes, and font stacks) are the paid product, since those values are what make the style directly usable; free styles are included on the free tier.
How is this different from design tokens or a Figma file?
Design tokens and Figma files are built for design tools and pipelines. A DESIGN.md is built for an AI to read in one pass: tokens and applied guidance together, in a single plain-text file the model consumes directly — not a tool-locked format it would have to be exported from first.
Further reading
Originally published on Curio.
Top comments (0)