Google's DESIGN.md turns your design system into a file the AI reads

Google Labs open-sourced DESIGN.md on April 21, and the file has traveled further than the spec that describes it. The idea is one markdown file sitting in your repo root that tells an AI coding agent what your design system looks like: the colors, the type, the spacing, and the thinking behind all of it. Google's own repo is at 25,945 stars this week. A community list of 73 DESIGN.md files, reverse-engineered from brands like Stripe, Linear and Vercel, is at 102,088.

The format grew inside Google Stitch, the AI design tool Google Labs runs in beta, where it started as a way to carry design rules from one project to the next instead of restating them every time. In April it went out under Apache 2.0 so it could work anywhere.

What's actually in the file

Two layers. YAML front matter at the top carries the tokens: hex values, font families, sizes, weights, spacing steps, corner radii, named components. Under it, markdown prose explains what those values are for. The spec is blunt about the division of labor. Tokens are "the normative values"; the prose "provides context for how to apply them".

Section order is fixed: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Skip any you don't need, but keep the ones you have in that order. The single hard requirement is a primary color. Google calls the whole thing "a foundation, not a prescription", which reads like a spec author who has watched people fight about design tokens for a decade.

The prose carries more than the numbers

PHILOSOPHY.md is the document worth your time, and it makes a claim most design system docs would never risk: "The quality of a generated design is determined less by the precision of its values than by how clearly the intent is described."

Then it explains why, with a line worth stealing. "Adjectives describe a region. A specific reference describes a point." Tell a model your product is modern, clean, trustworthy and premium, and it builds something in the middle of everything those words cover, which is where generic lives. Tell it the design is a graduate lecture handout from an old university and you've handed over the one ink color, the wide margins, the serif set at reading size, and the missing decoration. You also get the restrictions for free. A lecture handout doesn't glow and doesn't do gradients. Nobody has to write that down, the same way naming a dog tells you it won't meow.

That's a real position on craft, sitting inside a file format. The token block is the part everyone will copy. The paragraph underneath it is the part that decides what gets built.

It lints

npm install @google/design.md gets you a CLI that validates a file against the spec, catches token references pointing at nothing, checks WCAG contrast ratios, and exports tokens to Tailwind or the W3C DTCG format. It returns structured JSON, so an agent can read its own homework and fix it.

Three releases so far: 0.1.1 on April 21, 0.2.0 on May 26, 0.3.0 on June 15. It's still alpha, and it still moves. The last commit landed yesterday.

Why a designer should care

Handoff has always leaked somewhere between the file and the build. What changed is who's on the receiving end. Some of the people writing your CSS this year are agents that will never open Figma, never join the critique, and never absorb the reason the accent color only ever appears on interaction. They read text files. DESIGN.md is a bid to make that text file the place your design decisions live, in version control, reviewable in a pull request, sitting next to the code it governs.

Whether Google's format wins is open. A 102,088-star list of brand lookalikes measures enthusiasm, and a good share of it is people minting design systems for side projects they'll abandon by August. The premise underneath still holds: if an agent is going to build your interface, someone has to write down what the interface is supposed to feel like, in words. That was always the job. Now it has a filename.