What a DESIGN.md is and how to write one for your agent

A coding agent that builds UI without your design system makes one up. It picks a spacing scale and a shade of blue, then picks again the next session. A DESIGN.md is a single file at the root of your repo that tells the agent what those choices already are, and why.

The format comes from Google Labs. Stitch, its AI design tool, added DESIGN.md as a way to import and export design rules between projects, and on April 21, 2026 Google open-sourced the draft spec so other tools could use it. The spec, a linter and examples live at google-labs-code/design.md under the Apache 2.0 license. The format is still marked alpha and the repo says to expect changes.

What goes in a DESIGN.md

The spec describes the file as "a self-contained, plain-text representation of a design system." It has two layers.

Design tokens, in YAML. These are the exact values: colors, type styles, corner radii, spacing steps and component settings. They sit in front matter at the top of the file, or in fenced yaml blocks inside each section (the spec allows both since an October 2026 update). The spec calls the tokens "the normative values."

Prose, in Markdown. This is where you say what each value is for. The spec's philosophy doc argues the prose matters more than the numbers: "The quality of a generated design is determined less by the precision of its values than by how clearly the intent is described."

The prose goes under ## headings. You can leave sections out, but the ones you keep have to appear in this order:

1. Overview (or Brand & Style). The look and feel, the audience and the response the UI should get. The agent falls back on this when no token covers a decision.
2. Colors. The palettes and their roles. Only primary is required.
3. Typography. Families, sizes, weights and where each style is used.
4. Layout (or Layout & Spacing). The grid or margin model and the spacing scale.
5. Elevation & Depth. Shadows if you use them, or how a flat design shows hierarchy instead.
6. Shapes. Corner radius and the shape language.
7. Components. Buttons, inputs, chips and the rest, with their states. The spec says this part "is actively evolving."
8. Do's and Don'ts. Short guardrails for the mistakes you expect.

Tokens can point at other tokens with a {path.to.token} reference, so a button's background can be {colors.primary} and change when the color does. Variants like hover are separate entries with related names, for example button-primary and button-primary-hover.

Design tokens, and where DESIGN.md fits

A design token is a named design decision. Instead of #082014 in forty places, there is a primary color, and everything that should be that color says so. Tokens are how a design system stays one system when it lives in Figma variables, CSS custom properties, a Tailwind theme and a tokens file at once.

The W3C Design Tokens Community Group publishes a format for token files, and DESIGN.md borrows from it on purpose. The spec takes the idea of typed token groups and the curly-brace reference syntax, and its CLI exports to that format directly. The difference is the prose. A tokens.json file tells a build tool what the values are. A DESIGN.md also tells an agent when to use them, which is the part an agent gets wrong.

The same CLI turns your tokens into the files your code already uses:

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

The first writes a Tailwind v4 @theme block. The second writes W3C-format tokens.json. There is also json-tailwind for a Tailwind v3 config.

A template you can copy

This is an abridged DESIGN.md for shader.md itself, built from the site's real tokens. It passed npx @google/design.md lint (version 0.4.0) with no errors and no warnings on October 19, 2026. Swap in your own values and keep the shape.

---
version: alpha
name: Shader
description: A weekly design engineering newsletter. Reading-first pages on a light column beside generated pixel art.
colors:
  primary: "oklch(0.2201 0.0385 159.09)"
  neutral: "oklch(0.9825 0.0082 157.09)"
  muted: "#4c5951"
  on-primary: "oklch(0.9825 0.0082 157.09)"
typography:
  headline-display:
    fontFamily: Instrument Sans
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.03em
  body-md:
    fontFamily: Geist
    fontSize: 1rem
    lineHeight: 1.6
  label-sm:
    fontFamily: Fragment Mono
    fontSize: 0.875rem
    fontWeight: 400
rounded:
  none: 0px
spacing:
  pair: 4px
  bind: 8px
  cluster: 16px
  heading-md: 24px
  peer: 40px
  region: 60px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.none}"
    height: 40px
  body-text:
    textColor: "{colors.muted}"
    typography: "{typography.body-md}"
  page:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
---

## Overview

A reading room for designers who build with AI agents. Pages are quiet and text-first, set on a pale green paper with dark green ink, and the only loud thing on screen is the generated pixel art in the right column. It should feel like a well-kept printed newsletter, calm and dense enough to read straight through.

## Colors

One ink and one paper. Everything else is a step between them.

- **Ink** {colors.primary} sets headlines, body links and the primary button. It is never pure black.
- **Paper** {colors.neutral} is the page ground, never pure white.
- **Muted** {colors.muted} is for body copy and captions, so headlines sit one step darker.
- Color beyond these comes from the week's art. The interface borrows it only for the sign-up button's hover.

## Typography

Instrument Sans for headlines only. Geist for every sentence and every control. Fragment Mono for small meta like dates, at one weight, never bold.

## Layout

A 50/50 split above 1024px: words on the left column at a 60ch measure, art on the right, sticky. Below that the art is hidden and the text column is the whole page. Vertical spacing uses named rungs (pair, bind, cluster, peer, region), so the gap says how related two things are.

## Shapes

Square corners everywhere, buttons and inputs included.

## Components

The sign-up form is one field and one button in a row, and the button takes a color from the week's art on hover.

## Do's and Don'ts

- Do keep one primary action per screen
- Do use a named spacing rung instead of a raw pixel value
- Don't round a corner
- Don't put a second accent color in the interface

The site's colors are written in oklch() because that is how its CSS defines them. The spec accepts any CSS color, and the Tailwind export converts them, so the ink above comes out as #082014.

Three habits in it carry over even if none of the values fit you.

The Overview names a thing. "A well-kept printed newsletter" carries more than "clean, modern, minimal." The philosophy doc puts it this way: "Adjectives describe a region. A specific reference describes a point."

The color prose gives each color a job. An agent that knows muted is for body copy won't use it on a headline, and a token list alone can't tell it that.

The Do's and Don'ts are short. The spec's own examples run four lines. A long list usually means the Overview was too vague to rule the bad options out on its own.

How agents use it

An agent reads DESIGN.md the way it reads any file in the repo, so the work is making sure it reads this one first. With Claude Code, put a line in CLAUDE.md:

Before any UI work, read DESIGN.md. Use its tokens by name and follow
its Do's and Don'ts. If nothing in it fits, ask before adding a value.

For tools that read an AGENTS.md instead, put the same line there. If you use Anthropic's frontend-design skill, DESIGN.md becomes the brief the skill is told to follow. The frontend-design skill guide covers how the two work together.

Three CLI commands help keep the file honest. lint and diff print JSON, so an agent can run them and act on the result.

• lint checks references, flags text and background pairs below WCAG AA contrast (4.5:1), warns about colors no component uses, and warns when sections are out of order.
• diff compares two versions and exits with an error if the new one has more errors or warnings than the old one, which makes it usable as a check on a pull request.
• spec prints the format itself, so an agent that has never seen DESIGN.md can be handed the rules in its prompt.

Stitch reads and writes the format natively, which is how the file started. Google's Stitch announcement from March 2026 describes extracting a design system from any URL, and using DESIGN.md to move design rules to and from other design and coding tools.

Not every design.md is this format

The name is simple enough that people use it for other files. Vercel publishes one at vercel.com/design.md, and it is written as an agent skill, with a name and description header and instructions for designing Vercel-authored report websites. That is a useful file, and it works differently from the Google spec. If a tool says it supports DESIGN.md, check which one it means. Google's is the one this page covers, with a published spec and a linter.

What to write first

If you only have ten minutes, write the Overview and the Do's and Don'ts and skip the tokens. Those two sections carry the intent, and the agent can read token values from your CSS in the meantime.

The essay Teach the agent your system once suggests three lines to write before any prompt. List what already exists that the agent must use, what it must not invent, and how you will know the screen is finished. The first two belong in a DESIGN.md almost word for word, and the third is a fair test of whether the file did its job.