Google open-sourced DESIGN.md. Here's what's actually in the spec
By The WAALEE Team · · 5 min read
On April 21, 2026, Google Labs open-sourced DESIGN.md under Apache-2.0, turning what had been an internal convention for its Stitch design tool into an actual format spec with a CLI and a linter. The GitHub repo crossed 10,000 stars in eight days. That's a fast validation for a markdown file format, and it means the loose "drop a DESIGN.md in your repo root" pattern a few teams were already improvising is now something closer to a standard, with rules an agent (and a linter) can actually check.
One file, two jobs
The structure is the interesting part. A DESIGN.md file carries YAML front matter with the machine-readable tokens (exact hex codes, font sizes, spacing values, corner radii, component styles) and then, in the same file, markdown prose explaining the rationale behind them: when to use which weight, what the spacing rhythm is for, the taste rules a token file alone can't express. Earlier attempts at this problem, including a similarly-named convention some shadcn theme builders were already using, picked one or the other: either a token file with no explanation, or a brief with no exact values. Google's version asks for both, in one place, so an agent reading the file gets the number and the reason at the same time.
It's not inventing a new token language
The tokens themselves follow the W3C Design Tokens (DTCG) structure, and the CLI exports straight to `tokens.json` and to a Tailwind v4 theme, using the CSS-variable namespaces Tailwind already expects: `--color-*`, `--font-*`, `--text-*`, `--radius-*`, `--spacing-*`, and a few more. That's a sensible choice. It means a DESIGN.md file isn't a competing standard sitting next to DTCG, it's a wrapper around it, one that adds the human-readable half most agents were missing without asking teams to learn a second token schema on top of the one that already went stable last October.
What's genuinely new here
- A formal, versioned spec instead of an ad hoc convention, with Apache-2.0 licensing behind it.
- A CLI and linter that can actually validate a DESIGN.md file, not just eyeball it.
- Direct export to DTCG-format tokens.json and to a Tailwind v4 theme block, no manual translation step.
- Prose and tokens living in the same file, so an agent doesn't have to cross-reference two documents to get both the value and the intent.
The part it still doesn't do
The spec is explicit that it's at alpha, and that's honest, but the bigger gap isn't version stability. It's that DESIGN.md, like every brief format before it, describes a design system that already exists somewhere in someone's head or Figma file. It's a container, not a generator. If your brand's actual hex codes, type ramp, and spacing scale were never written down precisely, a DESIGN.md file just gives you a nicely structured place to guess at them. The linter will happily validate a spacing scale that's wrong, because "valid YAML" and "your actual brand" are two different questions, and the CLI only checks the first one.
Filling it in without guessing
The fastest way to populate a DESIGN.md file with real numbers, rather than plausible ones, is to pull them from a page that already renders your brand: your own live site, or a reference whose look you're building toward. Read the computed colors, the actual font sizes and line-heights, the real spacing rhythm off the rendered DOM, and you've got the machine-readable half of the file done correctly on the first pass. The prose half (why the accent is used sparingly, when to reach for the secondary weight) is still yours to write, because that judgment call doesn't live in a browser's computed styles. But you're writing rationale for values you know are right, not values you made up under deadline.
Three ways DESIGN.md gets its values filled in, in practice:
- google-labs-code/design.md: The official spec, CLI, and linter. Validates structure and DTCG compliance. Doesn't know your brand colors; you (or another tool) still have to supply them.
- awesome-design-md: A fast-growing community collection of example DESIGN.md files and patterns, useful for seeing the format in practice before writing your own from scratch.
- WAALEE: Paste a live URL and get the real colors, type scale, spacing, and radii as W3C DTCG tokens in seconds, ready to drop into the front matter of a DESIGN.md file instead of eyeballing them.
None of this is a knock on the spec, an open, lintable format for something every AI coding team was already improvising badly is a real improvement, and it's the right instinct to pair tokens with rationale in one file. The honest caveat is the same one that applies to every brief format so far: a well-formed DESIGN.md with the wrong numbers in it is still the wrong numbers, just tidier. Get the values right first, from a source you trust, then let the spec do what it's actually good at.