What is a DESIGN.md file? The format, the spec, the limits

Half the pages explaining DESIGN.md were written before the spec had a linter, an export command or a single published enterprise case study. All three exist now.

Quick answer: a DESIGN.md file has two layers in one plain markdown file: YAML front matter holding machine-readable design tokens, and a markdown body holding the human-readable reasoning for them. An AI coding agent reads both and builds UI in that visual language instead of defaulting to generic output. Google Labs open-sourced the draft specification on 21 April 2026, and it is still labelled version alpha. It is portable and free, it needs no plan or API, and the honest catch is cost: Atlassian measured their 80 KB DESIGN.md consuming roughly 92% more tokens than their own MCP server on the same task.

Where did DESIGN.md come from?

It started inside Google Stitch, where it did something narrow: "DESIGN.md in Stitch lets you export or import your design rules from project to project, so you don't have to reinvent the wheel every time you start a design in Stitch."

On 21 April 2026, Google announced that it was open-sourcing the draft specification so it could be used across any single tool or platform. The spec lives at github.com/google-labs-code/design.md under Apache-2.0, and it has picked up 28,342 stars since the repository was created on 10 April 2026 (checked 12 October 2026).

One correction worth making, because plenty of pages get it wrong: Google's own wording is "open-sourcing" a draft specification, not publishing a standard. The spec's own Status section says so plainly: "The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures."

What is actually inside the file?

The spec describes two layers, and the split is the whole idea: "A DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them why those values exist and how to apply them."

The front matter carries name, optional description and version, then colors, typography, rounded, spacing and components. Values can be any CSS color, a dimension with a unit, a typography object, or a reference to another token in {colors.primary} form.

The body uses ## headings. Sections are optional, but the ones you include have to appear in the spec's canonical order:

1. Overview (alias: Brand & Style)
2. Colors
3. Typography
4. Layout (alias: Layout & Spacing)
5. Elevation & Depth (alias: Elevation)
6. Shapes
7. Components
8. Do's and Don'ts

Component tokens are the part people under-use. A component maps a name to sub-properties, and those properties should point at tokens rather than literals:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

Valid component properties are fixed: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants like hover and pressed are separate entries, such as button-primary-hover.

The spec also tells consumers how to behave when they meet something unexpected: preserve an unknown section heading, accept an unknown color token if the value is valid, accept an unknown component property with a warning, and reject the file outright on a duplicate section heading.

Is there a tool that checks the file?

Yes, and almost nothing written about DESIGN.md mentions it. npx @google/design.md ships four commands:

• lint DESIGN.md validates structure and prints findings as JSON. Exit code 1 if there are errors.
• diff DESIGN.md DESIGN-v2.md reports token-level changes between two versions, and exits 1 on regressions.
• export --format <json-tailwind | css-tailwind | tailwind | dtcg> converts the tokens into a Tailwind v3 theme.extend object, a Tailwind v4 @theme { ... } block, or a W3C Design Tokens Format Module tokens.json.
• spec prints the specification itself, which is designed for pasting into an agent prompt as context.

The linter runs eleven rules. The four that catch the most real problems: broken-ref (an error, for a {colors.primary} that resolves to nothing), contrast-ratio (a warning when a component's background and text pair falls below WCAG AA 4.5:1), missing-typography (a warning, because colors with no type tokens means "agents will use default fonts"), and orphaned-tokens (a warning for colors defined but never referenced).

That export --format dtcg path matters more than it looks. It means a DESIGN.md is not a dead end: the tokens convert into the same W3C format a conventional design token pipeline already consumes.

Does it actually improve agent output?

The only published measurement from a company with a real design system is Atlassian's, from their 15 June 2026 write-up. They ran a login-screen task four ways:

Approach	Design system context available	Average token usage	Average time	Average turns
No context	~5%	4.20 million	6m 19s	43
ADS MCP	~80%	3.75 million	5m 1s	35.1
ADS skill	~80%	4.43 million	5m 23s	36
DESIGN.md	~30%	7.21 million	6m 46s	45.3

Read that honestly. For a company that already runs an MCP server over a 50-plus component library, DESIGN.md was the most expensive option and surfaced the least context. Their file is "80 KB, or roughly 19,800 LLM tokens (~10,700 without frontmatter)", and fitting a system that size into one file meant cutting usage guidance for their components.

Atlassian still published theirs, at atlassian.design/DESIGN.md with a dark mode variant, and named where it wins: high-level artistic direction, quick prototyping in an unfamiliar environment, interoperability with design tools, and customer theming.

That is the accurate shape of the trade. A DESIGN.md is not a replacement for an in-house MCP server you already own. It is the format that works when there is no server, no component library, and no plan gate, which is most projects most of the time.

What do people building with it say?

The discussion has two distinct camps, and both are worth quoting directly.

Useful, not magical. A LinkedIn post from TJ Pitre with 480-plus reactions puts the deflation bluntly: "Everyone's freaking out about DESIGN.md files like Google just invented context. They didn't. It's a markdown file."

And from designers with mature documentation, in r/UXDesign's We made AI-readability a requirement for our design system: "What I mean is .md files are text heavy, whereas good design system documentation for humans has visual examples with code."

The other camp is builders, and it is noticeably larger. In r/vibecoding, DESIGN.md spec and get design.md: "Google just came out with the design.md spec (https://github.com/google-labs-code/design.md) and it's very useful for defining a unique look ...". In r/SideProject, a free database of good Design.md files states the motive in one line: "The idea is simple a free and easy way to make websites/ apps not look like AI. Download 1 design md file and plug it into cursor, claude or any ...".

Both things are true. It is only a markdown file, and a markdown file is exactly the right size of intervention when the alternative is describing your brand in a prompt every session. The reason AI-built apps converge on the same look is covered in why AI-generated apps look the same, and a specific named target is the fix.

When should you use one?

✅ Reach for a DESIGN.md when:

• You are starting a project with no design system and no Figma library for the agent to read.
• You want a specific visual language, not the average of everything the model has seen.
• You are switching tools often, since the same file works in Cursor, Claude Code, v0, Lovable, Bolt or a plain chat.
• You want the look to survive a new session, a new repo or a new teammate.

❌ Skip it, or expect limits, when:

• You already run an MCP server over a mapped component library. Atlassian's numbers say the server wins on cost and coverage.
• Your system is large enough that one file cannot hold it. At 50-plus components you are cutting guidance to fit.
• You need the agent to reuse specific existing components rather than recreate them. That is Figma Code Connect territory, not a markdown file's.
• You need a frozen, versioned contract. The format is still alpha and the spec says to expect changes.

DESIGN.md compared with the alternatives

• A screenshot shows what something looks like, and the agent guesses every value. Results drift between sessions.
• Raw design tokens are precise but ruleless. The agent knows your blue, not when to use it.
• An MCP server loads context on demand and can expose a whole component library, which is why it beat DESIGN.md in Atlassian's test. It also needs building, hosting and, for the Figma one, a plan that allows it.
• A DESIGN.md is tokens plus the rules for applying them, in one portable file with no infrastructure. Less context than a server, far more than a prompt.

How to use one with your agent

1. Pick a design whose look you want from the duply library, for example Linear, Stripe or Vercel.
2. Copy the DESIGN.md and save it in your project root.
3. Tell the agent to use it: "Build this page using the design system in DESIGN.md. Use the tokens, follow the do's and don'ts."
4. Run npx @google/design.md lint DESIGN.md if you have edited it, so a broken token reference fails fast instead of silently.
5. For a deeper setup, including what to put in CLAUDE.md or AGENTS.md versus DESIGN.md, follow give your AI agent a design system.

FAQ

What is a DESIGN.md file in one sentence? A single markdown file that pairs machine-readable design tokens in YAML front matter with human-readable design rationale in the body, so an AI coding agent has both the exact values and the rules for applying them.

Is DESIGN.md an official Google standard? It is an open-sourced draft specification from Google Labs, published 21 April 2026 under Apache-2.0, and its own Status section labels it version alpha with changes expected. Calling it a finished standard overstates it.

Where do the sections go, and does the order matter? Yes. Sections are optional, but any you include must follow the spec order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. The linter raises a section-order warning when they are out of sequence.

Is a DESIGN.md the same as design tokens? No. Tokens are the raw values. A DESIGN.md wraps them in usage rules and component specs, and it can emit plain tokens on demand with npx @google/design.md export --format dtcg.

Can I use it with any AI coding tool? Yes. It is plain markdown with no API, so it works in Cursor, Claude Code, v0, Lovable, Bolt and general chat assistants.

Is DESIGN.md better than an MCP server? Not for a team that already has one. Atlassian measured 7.21 million average tokens for DESIGN.md against 3.75 million for their own MCP server on the same task, about 92% more. DESIGN.md wins on portability, zero setup and no plan gate, which is a different question from winning on efficiency.

How big should the file be? Small enough to sit in context every session. Atlassian's is 80 KB, around 19,800 tokens, and they had to remove per-component usage guidance to get there. If yours is growing past that, you want a server, not a longer file.

Do I have to write one myself? No. duply documents real products' design systems as ready-to-use files. Browse the library, copy one, hand it to your agent. Several other public catalogs exist too, which is a good sign for the format rather than a problem.

Are these official brand files? No. Each DESIGN.md in the duply library is an independent analysis of publicly observable design choices, not an official asset. See our terms for the full framing.

Summary

• A DESIGN.md is YAML tokens plus markdown rationale in one file, read by any agent that accepts text.
• Google Labs open-sourced the draft spec on 21 April 2026; it is Apache-2.0, has 28,342 stars, and is still version alpha.
• The official CLI does more than people realise: lint with eleven rules, diff, spec, and export to Tailwind v3, Tailwind v4 or W3C DTCG.
• Atlassian's published test is the honest counterweight: against their own MCP server, DESIGN.md cost about 92% more tokens and exposed less of the system.
• It is still the right tool when there is no server, no mapped library and no plan gate, which describes most projects on most days.

Pick a system from the duply library, drop its DESIGN.md in your repo, and stop describing your brand in prompts.

Related reading

• Give your AI agent a design system
• What are design tokens?
• Why AI-generated apps all look the same