Using a DESIGN.md with your coding agent

A coding agent that writes interface code without visual guidance picks colors, fonts and corner radii more or less at random, and the result changes from one session to the next. A DESIGN.md fixes that: it is a text file describing your product's visual identity, which the agent reads before it builds screens.

What the file contains

The format is published as open source by Google Labs. A DESIGN.md combines two things: exact values in YAML (the "tokens") and Markdown prose explaining why those values exist and how to apply them. The tokens are authoritative for values; the prose provides context.

The prose is split into ## sections, in this order. A section can be left out if it does not serve your project.

Here is the start of a file, with its tokens at the top:

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
rounded:
  sm: 4px
  md: 8px
---

A component can reuse a token by reference instead of repeating the value:

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    rounded: "{rounded.sm}"

The specification notes that the components part is still evolving: treat it as a base, not a fixed contract.

Where to put it

Put the file at the project root, named DESIGN.md. In an existing project, catalog resources are installed into the current project, as described in Install your first resource.

Placing the file is not always enough. Each agent loads its own instruction files by default, not other files:

• Claude Code reads CLAUDE.md (at the root or in .claude/). It can also read AGENTS.md when there is no CLAUDE.md. In a CLAUDE.md, a line reading @DESIGN.md imports the file: its content is loaded along with the instructions. Relative paths resolve from the file containing the import, with at most four levels of nesting.
• Codex reads AGENTS.md, walking from the project root down to your working directory.
• Cursor loads the rules in .cursor/rules (.mdc files) and also reads AGENTS.md.

The simplest approach is to name the file in your instructions:

## Interface
Every screen follows DESIGN.md at the project root.
Do not define any color, font or radius that is not in it.

With Claude Code, replace those two sentences with @DESIGN.md if you want the file always loaded. Keep in mind that imported content takes up context in every session: a concise DESIGN.md beats a ten-page one.

Asking the agent to follow it

Once the file is in place, say so in the request instead of hoping it gets read:

Read DESIGN.md. Build the pricing page using only its colors,
fonts and components. Tell me what is missing from the file
instead of inventing it.

Three habits help:

1. Ask it to flag gaps. If the file defines no alert style, the agent should tell you, not improvise one.
2. Check the result against Do's and Don'ts. It is your checklist: "one primary action per screen", "no more than two font weights".
3. Review the code, not just the screenshot. Look for hard-coded values (#3b82f6) that do not come from the file.

Validating and exporting the file

The command-line tool published with the specification checks a DESIGN.md: broken token references, insufficient WCAG contrast, incomplete structure.

npx @google/design.md lint DESIGN.md

It also exports the tokens to other formats, for example a Tailwind v4 theme as CSS:

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

The tool is optional: a DESIGN.md remains a plain Markdown file that any agent can read.

Adapting it to your brand

Someone else's file does not describe your brand. To make it yours:

1. Replace the tokens. Colors, fonts, radii, spacing: put in your values, keeping the token names so references keep working.
2. Rewrite the Overview. One sentence on tone and audience is worth more than a long paragraph: it guides the agent when no rule covers the case.
3. Delete what you do not use. A missing section is allowed; a wrong one misleads the agent.
4. Grow Do's and Don'ts from real mistakes. Each time the agent gets the same thing wrong twice, add a line.
5. Check contrast. A lint run or a manual check, before shipping.

DESIGN.md files inspired by real brands

The catalog offers DESIGN.md files inspired by the visual style of well-known products. Use them as a starting point to see what a complete file looks like, or to get a visual direction close to a product you admire.

These files are neither affiliated with the brands they mention nor endorsed by them. Names and logos remain the property of their owners. Do not ship a site that imitates another brand's identity: take the file as inspiration, then replace the tokens with your own. Each page lists the author, the original license and the link to the source.