What Is DESIGN.md, and Why I'm Watching It Closely

Every time I ask an AI agent to add a component to this site, it does something subtly off-brand. The spacing is a little tighter than everywhere else. It reaches for a blue I never use. The corner radius doesn't match. The code works — it just doesn't look like my site. So I fix it by hand, the agent forgets by next session, and we do the dance again.

DESIGN.md is a fix for exactly that dance. It's an open file format from Google Labs (the Stitch team) that describes your whole design system to an AI agent in a single portable Markdown file. If you've used a CLAUDE.md to teach an agent your repo's conventions — the same way I lean on MCP, Skills, and Workflows to put Claude to work here — this is that idea pointed at design: one durable source of truth so the agent stops re-guessing your colors and spacing on every prompt.

The 20-second version

The rest of this is what's actually inside the file, the one independent stress-test worth reading, and whether it's worth adopting on a site this size.

What's inside a DESIGN.md file?

The clever part of the spec is that it puts two audiences in one file:

1. Machine-readable tokens — a structured block of exact values: hex codes, font sizes, spacing scale, corner radii, and per-component styles (including variants like hover, active, and pressed, each with its own entry). This is the part an agent reads to act.
2. Human-readable prose — Markdown explaining why those values exist and when to apply them. This is the part that stops an agent from technically-correct-but-wrong choices.

The current spec organizes this into roughly nine predefined sections — things like Visual Theme & Atmosphere (the overall tone and brand intent) and Color Palette & Roles (colors tagged with semantic roles: primary, surface, accent, error). The point of fixing the section names is that the agent knows exactly where to look instead of guessing — the structure itself is the contract.

Each component token maps a name to a set of properties — backgroundColor, textColor, typography, rounded, padding, size — and interaction states get their own keyed entries. So "what does a primary button look like when pressed" has one unambiguous answer the agent can read, rather than something it improvises.

The CLI is the part that sold me

A spec is just a convention; the tooling is what makes it real. DESIGN.md ships an npx CLI with three commands that matter:

# Validate structure, catch broken token references,
# and auto-check WCAG AA contrast ratios
npx @google/design.md lint
 
# Compare two versions and flag token-level regressions
npx @google/design.md diff
 
# Generate a Tailwind theme.extend straight from your tokens
npx @google/design.md tailwind

That last one is why this is more than a curiosity for this site specifically. As I wrote in Building This Website, this blog runs on Tailwind v4 with a CSS-first @theme — my tokens already live in CSS, by hand. design.md tailwind generates exactly that layer from the spec, which means a DESIGN.md could become the upstream source my Tailwind theme derives from, rather than two copies of the truth drifting apart. The contrast-checking in lint is a nice bonus: accessibility regressions become a failed command instead of something I notice three weeks later.

Is the single-file approach a problem? What Atlassian found

This is where most write-ups stop, because the spec sounds great in the abstract. But Atlassian published a genuinely useful stress-test — they ran DESIGN.md against their own internal MCP-based design tooling on a real design system, and the tradeoffs are real:

Three findings worth internalizing:

• A static file loads everything, every time. Because DESIGN.md isn't fetched on-demand, the agent ingests the whole system on every task — about 92% more tokens than their MCP approach, which pulls only the relevant context.
• Portability forces compression. Squeezing a large design system into one shareable file meant cutting "plenty of details that could be useful" — and with the usage guidance gone, the LLM got less accurate, not more.
• No code-level guidance means agents rebuild instead of reuse. Without pointers to existing component implementations, the agent was more likely to re-implement a component from the tokens than import the one you already maintain — a maintainability trap.

Their verdict, which I think is correct: DESIGN.md shines for one-off prototyping and customer-facing theming, and underperforms richer tooling for large, established production systems.

So is it worth it here?

Here's the thing — every limitation Atlassian hit is a large-system problem. And this site is the opposite of a large system.

• The "92% more tokens" tax is a function of system size. My token set is small enough that loading all of it is cheap.
• The "lossy compression" problem only bites when your system is too big to fit without cutting things. Mine fits comfortably, uncompressed.
• The "no MCP server to compete with" point cuts the other way for me: I don't have a design MCP server, so a static file isn't losing a comparison — it's the only structured option on the table.
• The "rebuilds instead of reuses" risk is smallest when there are few components to reuse in the first place.

In other words, a solo personal site with a small, stable design system is close to the ideal case for DESIGN.md — almost the exact inverse of where Atlassian found friction. The core value I want from this site is "minimal and clean — elegant simplicity" (the restraint and small details I've written about before), and right now that aesthetic is implicit, living in my head and scattered across components. A DESIGN.md would make it explicit and machine-readable, so the next agent edit defaults to it instead of guessing and forcing me to correct.

I haven't adopted it on this repo yet — but it's the first design-for-agents format I've seen that earns the effort, and the Tailwind generator makes the migration path obvious. When I do wire it up, that'll be its own post: the actual file, the lint output, and whether design.md tailwind really replaces my hand-written theme. If you're building with an AI agent and care how the result looks, it's worth a serious look now rather than after it becomes a standard.

Sources

• What is DESIGN.md? — Stitch docs
• Stitch's DESIGN.md is now open-source — blog.google
• DESIGN.md format reference — Stitch docs
• What we learned testing portable design context — Atlassian