What Is DESIGN.md?

There's a moment most people hit around their fourth or fifth screen.

The first page looked good. The second one, also good — slightly different shade of blue, but fine. By the fifth, your buttons have three different corner radii, two fonts have appeared from nowhere, and the spacing on one page is roomy while the next is cramped.

Nothing broke. Every screen works. It just doesn't look like one product any more.

The instinct is to blame the tool, but the tool didn't do anything wrong. It made a reasonable choice each time you asked, because it has no memory of the choices it made last time. Every prompt starts from a blank slate, so every prompt reinvents your design language slightly.

Your project already has a visual identity — colours, fonts, spacing, component styles. Traditionally that lives in a Figma file, a brand PDF, or somebody's head. None of those are readable by an AI agent.

DESIGN.md is what changes that.

DESIGN.md was introduced by Google Stitch, an AI design tool from Google Labs that generates interfaces from descriptions. It's best understood as the design counterpart to a file you may already know.

Three files, three audiences. The pattern is deliberate.

It's also explicitly designed as a foundation, not a prescription — a shared vocabulary that agents, tools and teams can rely on, while leaving you free to extend it. Unknown sections and custom tokens are accepted rather than rejected.

One more framing worth carrying: DESIGN.md is a living artifact, not a static config file. The agent generates it, you refine it, and it gets re-applied as you iterate. It's meant to change.

This is the central idea, and the thing that makes the format work. Every DESIGN.md has two parts.

YAML front matter — machine-readable design tokens. Exact hex values, font properties, spacing scales. These are the normative values: what agents enforce.

Markdown body — human-readable rationale, organised into ## sections. This explains why those values exist and how to apply them.

The split does real work. Tokens give agents precision. Prose gives them judgement for everything the tokens don't cover.

A neat consequence: the prose can use expressive names — "Midnight Forest Green" — while the tokens use systematic ones — primary. Both point at the same colour. Humans get the evocative name, machines get the hex.

That's the whole format. Nothing exotic — standard markdown, standard YAML.

The token system is inspired by the W3C Design Token Format, which is why tokens convert cleanly to and from tokens.json, Figma variables, and Tailwind theme configs. You're not locked into anything.

The front matter block opens and closes with a line containing exactly three dashes.

A scale level is a named level in a sizing or spacing scale. Common names are xs, sm, md, lg, xl and full — but any descriptive string is valid.

Most design systems end up with 9 to 15 typography levels, each combining a semantic role — headline, body, label — with a size variant.

A reference is wrapped in curly braces and points at another value in the YAML tree. This is how you avoid repeating yourself.

For most token groups a reference must point at a primitive value, not a group. Inside components, references to composite values are permitted — so {typography.label-md} is valid there.

States are defined as separate component entries with a related key name, not as nested objects.

The recognised component properties are backgroundColor, textColor, typography, rounded, padding, size, height and width. Anything else is accepted, but with a warning.

These names aren't required, but following them keeps you compatible with what tools expect.

The markdown body uses ## headings. Sections may be omitted if irrelevant, but the ones present should appear in this order — the linter warns if they don't. An optional # heading can title the document; it isn't parsed as a section.

A holistic description of the product's look and feel: brand personality, target audience, and the emotional response the UI should evoke.

This is the section people skip, and it's arguably the most valuable. It's the fallback when a specific rule or token isn't defined — which happens constantly, because no file anticipates everything.

For example: "A calm, professional interface for a healthcare scheduling platform. Accessibility-first design with high contrast and generous touch targets."

Colors: the palettes. At minimum, define primary. Beyond that you're free, though primary, secondary, tertiary and neutral is the common convention.

The prose does the important work here — not just what a colour is, but what it's for. "Tertiary (#B8422E): the sole driver for interaction." Saying blue is #185FA5 tells an agent a colour exists. Saying it's used only on the single most important action per screen tells it when to reach for it, which is what you actually need.

Typography: font families and the full hierarchy — what a page title is versus a section heading versus body text versus a caption. Typography drifting between screens is the most common inconsistency in AI-built UI, so this section pays for itself fast.

Layout: grid models, spacing scales, containment principles. For example: "The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width Grid for desktop (max 1200px). A strict 8px spacing scale is used." Tokens are a map of scale identifiers to dimensions or unitless numbers — the latter useful for column counts and ratios.

Elevation & Depth: how visual hierarchy is conveyed. If you use shadows, define them. If your design is flat, explain the alternative — borders, tonal layers, colour contrast. That second half matters. Left unexplained, agents default to adding shadows.

Shapes: corner radii, edge treatments, overall shape language. "All interactive elements use a minimal 4px corner radius. Modern enough to feel current, rigid enough to feel engineered." That second sentence is doing real work: it gives the agent a principle to extend to shapes you never mentioned.

Components: style guidance for component atoms. The spec names buttons, chips, lists, inputs, checkboxes, radio buttons and tooltips — and encourages you to add whatever else your domain needs.

Do's and Don'ts: practical guardrails, described in the spec as acting during generation. Do use the primary color only for the single most important action per screen. Don't mix rounded and sharp corners in the same view. Do maintain WCAG AA contrast ratios, 4.5:1 for normal text. Don't use more than two font weights on a single screen.

Negative rules are unusually powerful here, because AI tools have strong defaults and will reach for them unless told not to. Naming what you never want is often faster than describing what you do.

The spec defines exactly what a tool should do when it meets something it doesn't recognise — which is what makes "extend it freely" a real promise rather than a hope.

One hard failure, and everything else degrades gracefully. That's a sensible design.

Let the agent generate it. Describe the vibe and let it translate aesthetic intent into tokens — "a playful coffee shop ordering app with warm colors, rounded corners, and a friendly feel". Stitch produces a complete design system and summarises it as a DESIGN.md.

Derive it from existing branding. If you already have a brand, hand over a URL or an image. The agent extracts palette, typography and style patterns from what exists rather than inventing something new.

Extract it from a codebase. If you've already built something, your design language is already in there — colours scattered across stylesheets, spacing buried in components, typography locked in a Tailwind config. Any coding agent can be pointed at the project and asked to write a DESIGN.md from what it finds.

Write it by hand. Perfectly reasonable, and the most precise option. It's just markdown and YAML.

Google publishes a recommended prompt for extracting DESIGN.md from a codebase, and the instructions behind it are worth understanding because they're a lesson in themselves.

The repo is the source of truth — pull real product names, taglines and copy from the README; real labels and terminology from config files, CLI help text, schemas and error messages. Nothing invented, nothing placeholder. Collect scattered values, even undocumented ones, because they reveal visual intent. Read the core logic, not just the docs: data structures reveal the product's native shape — a timeline, a graph, a catalog, a pipeline — and that shape should organise the page instead of a generic section template. And find what the README leads with, because that feature dominates the page.

Three tips that improve results noticeably: point the agent at specific directories, name your stack, and iterate afterwards — "the accent should be the teal from the navbar, not the blue from the footer."

For a more thorough job, Google publishes an open-source collection of 13 agent skills in three plugins, following the Agent Skills open standard and working with any compatible agent.

The extract-design-md skill detects your stack automatically — Tailwind config, CSS custom properties, theme files, styled-components — and works through atmosphere, colour, typography, components and layout in turn.

There's a real command-line tool: @google/design.md. It validates against the spec, catches broken references, checks contrast ratios, and exports tokens elsewhere. Output is structured JSON, so agents can act on it.

Three commands worth knowing. lint parses the front matter, resolves every token reference, runs eight rules and reports findings, exiting 1 if there are errors — it accepts stdin, so you can pipe in a generated file. diff compares two versions and reports which tokens were added, removed or modified; it also flags regressions, meaning more errors or warnings in the newer file, and exits 1 when it finds one. export converts your tokens for use elsewhere: --format tailwind produces a theme.extend object you drop into tailwind.config.js, and --format dtcg produces a W3C Design Tokens compliant tokens.json.

There's also npx @google/design.md spec, which prints the specification itself — handy for injecting spec context into an agent prompt so it knows exactly what structure to produce. The linter is available as a TypeScript library too, if you want it inside your own tooling.

The through-line in those warnings is worth noticing. missing-primary and missing-typography both carry the same message in different words: anything you don't define, the agent will decide for you. The linter isn't checking correctness so much as checking how much control you've actually taken.

contrast-ratio is the quiet standout — an accessibility check running automatically on your design system, before a single screen exists.

Two conventions, both in use. The project root — DESIGN.md, alongside README.md and AGENTS.md — is the most discoverable. Or .stitch/DESIGN.md, which is what Stitch's own tooling writes to.

Either works. Whichever you choose, tell your tool once — "follow DESIGN.md" — or put that reference wherever your builder keeps standing instructions, and you'll never mention it again.

There's a bigger idea behind the file.

For twenty years, design systems have been built for humans: Figma libraries, style guides, component documentation. All of it assumes a person will read it, interpret it, and apply judgement.

DESIGN.md assumes the reader is a machine that will apply it literally, every time, without getting bored — and pairs that with prose for the parts literalism can't reach. That's a genuinely different design goal, and it changes what a good design system looks like.

This is a window into a broader shift: documentation written to be read by agents rather than people. Expect more of it.

Some honesty, since the enthusiasm around this is running slightly ahead of the reality.

Yes, if you're building more than a couple of screens, working across several sessions, or you have brand colours and fonts that need respecting.

Not yet, if you're building one small internal tool this afternoon. Writing a design system for a single expense form is procrastination with extra steps.

A reasonable middle path: build your first two screens however you like. Once you're happy with them, ask your agent to extract a DESIGN.md from what you made, tidy it up, run the linter, and use it from screen three onwards.

That way the file describes something real rather than something you imagined in advance — which is usually the better order to do things in anyway.