DESIGN.md: Google's missing piece for AI coding agents

If you have used AI coding agents for anything visual, you know the problem. You describe a page, the agent builds it, and it works but looks like a government website from 2003. You tweak the prompt. It gets worse. You paste in a screenshot. It sort of copies the layout but misses every detail that makes the design coherent.

Google just released an open spec called DESIGN.md that tries to fix this. It gives coding agents a file they can read that contains your entire design system: colors, typography, spacing, components, and the reasoning behind them. Not a screenshot. Not a Figma link. A structured document the agent can parse and apply consistently.

It picked up 2,400 stars in its first day on GitHub. That tells me this problem is universal.

What DESIGN.md actually is

A DESIGN.md file has two parts. The top is YAML front matter with machine-readable design tokens: hex colors, font families, border radii, spacing scales. The bottom is markdown prose explaining why those values exist and how to apply them.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI
evokes a premium matte finish: a high-end broadsheet or
contemporary gallery.

## Colors

The palette is rooted in high-contrast neutrals and a single
accent color.

An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons. Not because you told it to in a prompt. Because it read the tokens and the prose and applied them.

Why this is different from pasting a Figma link

I have tried every approach you can think of. Screenshots. Figma embeds. Long prose descriptions. Style guide URLs. They all have the same weakness: the agent has to interpret them. A screenshot is a raster image. The agent guesses at the hex values. A Figma link is a web page; the agent may or may not be able to fetch it, and even if it can, extracting design tokens from rendered CSS is unreliable.

DESIGN.md is different because the tokens are explicit and machine-parseable. The agent does not guess that the background is "off-white." It reads neutral: "#F7F5F2" and uses exactly that. The prose section handles the parts that tokens cannot: tone, mood, the difference between "corporate" and "approachable."

As a format, it splits the job. Tokens handle precision. Prose handles judgment. You need both.

Token references and composability

One thing I like: tokens can reference other tokens. You define your primary color once and then reference it throughout component definitions.

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

This is how real design systems work. Your primary button color is not a random hex value; it is a reference to a semantic color token that maps to a palette entry. If you change the palette entry, every component that references it updates too. Agents get this for free.

The CLI tool

Google shipped a CLI alongside the spec. Two commands matter.

npx @google/design.md lint DESIGN.md validates your file against the spec, catches broken token references, checks WCAG contrast ratios, and outputs structured JSON that agents can act on.

{
  "findings": [{
    "severity": "warning",
    "path": "components.button-primary",
    "message": "textColor (#ffffff) on backgroundColor (#1A1C1E)
      has contrast ratio 15.42:1 - passes WCAG AA."
  }],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

npx @google/design.md diff DESIGN.md DESIGN-v2.md compares two versions of a design system and reports token-level changes. This is useful in CI: if someone changes a color or a font size, the diff tells you exactly what moved.

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Running the linter as a pre-commit hook or CI check means design drift gets caught before the agent ships inconsistent UI. That is a real workflow, not just a demo.

Component tokens

The spec defines a set of valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants like hover, active, and pressed are separate component entries with related names, not nested properties.

This is a deliberate choice. Flat component entries are easier for agents to parse and diff. No nested conditionals. No "if state is X then use Y." Just a flat list of named states with their values.

The spec also defines consumer behavior for unknown content. Unknown section headings are preserved. Unknown color token names are accepted if the value is valid. Unknown component properties get a warning instead of an error. This is pragmatic. The spec can evolve without breaking existing files.

What I am not sure about

DESIGN.md solves the "agent does not know the design system" problem. But it does not solve the "agent does not know the design system is wrong" problem. If your tokens describe a clean, accessible system, but the real product has 47 shades of gray accumulated over three years of development, the agent will faithfully apply the clean system and nothing will match the existing pages.

This is a documentation problem more than a specification problem. A DESIGN.md is only as good as its accuracy. If it drifts from reality, it becomes a fiction that agents treat as truth. The diff command helps detect drift, but someone still has to maintain the file.

I also wonder how far this goes before it becomes a full component library spec. Right now it handles colors, typography, spacing, rounding, and basic component properties. It does not handle animations, responsive breakpoints, or interaction patterns. You can write about those in the prose section, but prose is not machine-readable. At some point, you might want tokens for "drawer slides in from left over 300ms" or "breakpoint-lg is 1024px." The spec does not cover that yet.

The Windows compatibility note made me wince. The .md suffix in the CLI package name collides with the Windows Markdown file association. You have to use a designmd alias instead. It works, but it is the kind of friction that makes you question whether you want to bet on this tooling for a team that includes Windows users.

How it compares to what came before

Design tokens as a concept are not new. Figma exports tokens. Style Dictionary tokenizes them. Salesforce's design-token framework has been around for years. I have used Style Dictionary and it works well for generating CSS variables from a single source of truth.

What those tools do not have is a prose layer and an agent-first consumption model. Style Dictionary outputs CSS custom properties and iOS/Android resources. It does not explain to an agent why the tertiary color should only be used for interaction elements. DESIGN.md does.

I think of it like this: Style Dictionary is a compiler. DESIGN.md is a README with a typed config section. The compiler is more powerful for pipeline work. The README is more useful for an agent that needs context to make judgment calls.

When to use it

If you are using AI coding agents to build UI and you keep getting inconsistent results, try it. Write a DESIGN.md for your project, put it in the repo root, and see if the agent's output gets more consistent. The up-front cost is writing the file, which takes maybe an hour for a medium-size project.

If your design system lives in Figma and is maintained by a designer who does not touch code, DESIGN.md might not be worth it yet. There is no Figma-to-DESIGN.md exporter. The designer would have to manually keep two sources of truth in sync, and that never lasts.

If you are building agent tooling, this is worth supporting as an input format. The spec is small and well-defined. Adding DESIGN.md parsing to an agent takes an afternoon, and it gives users a standard way to express design intent without relying on screenshots or long prompts.

Getting started

npm install @google/design.md
npx @google/design.md lint DESIGN.md

The full spec is at github.com/google-labs-code/design.md. The repository includes examples, the CLI, and the formal specification document. Worth reading even if you do not adopt the format, because it is a clear articulation of what agents need to know about your design system that a color palette alone cannot tell them.