How to write a DESIGN.md for your coding agent

A DESIGN.md is a Markdown file in your repository that tells a coding agent what your interface looks like: the colors and what each is for, the type scale, spacing and radii, the components and their states, and the rules nobody should break. The agent reads it before it builds a screen, so the new page uses your values instead of whatever a model reaches for when it has none. You can write it by hand from the tokens you already have, ask an agent to describe screenshots, or measure the live site and have an agent write the document from the measurements. Each is covered below, with what it costs.

Where the format comes from

DESIGN.md comes from Google Stitch, Google Labs' AI design tool. Inside Stitch it let you carry design rules from one project to the next, and on April 21, 2026 Google announced it was "open-sourcing the draft specification for DESIGN.md" so any tool could use it. The specification lives in the google-labs-code/design.md repository, under Apache-2.0, and describes itself as "a format specification for describing a visual identity to coding agents". It is marked alpha, and the repository warns that the spec, the token schema and the CLI "are under active development".

The format has two layers in one file:

• YAML front matter with the tokens: colors, typography, rounded, spacing and components, where a component can point at a token with a reference such as {colors.primary}.
• A Markdown body with the reasoning, in ## sections. The spec lists Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components and Do's and Don'ts. Any of them can be left out, but the ones present keep that order, and an unknown heading is preserved rather than treated as an error.

The README puts the split in one line: "Tokens give agents exact values." The prose says why those values exist and when to use them. The same repository ships a command that checks a file against the spec, including the WCAG contrast of a component's text over its background:

npx @google/design.md lint DESIGN.md

It also has diff and an export to Tailwind or the W3C Design Tokens format.

What makes one worth reading

A useful DESIGN.md has:

• Exact values with roles. #1c1c1c is not a rule; "--foreground, body text on every surface" is.
• Both color schemes, if the site has a dark mode. Half a palette gets you pages that look right until someone switches.
• Components with their states. What a button looks like on hover and on focus is the part an agent guesses first.
• Do and don't, with reasons. "Don't put gray-500 text on the muted surface: it fails AA" is a rule an agent can check its own work against.
• What is not known. A section that admits a gap stops the agent from filling it with a guess.

Short beats complete: an agent reads it before every change.

Way 1: write it by hand from your own tokens

If your project already has a token file, a Tailwind config, a theme.css or exported Figma variables, the values are there. Copy them into the front matter, then write the part a file cannot hold: which surface each color is for, which size is body text and which is a caption, when the outlined button is used instead of the filled one.

This is the most accurate way: the values and the names come from your source. It takes time, and it starts drifting the day someone edits the CSS without touching the document. The fix is procedural: change the tokens and DESIGN.md in the same commit, and run the lint in your pre-commit hook.

Verdict: the right way for a design system you own and maintain.

Way 2: ask an agent to read screenshots

Paste a few screenshots into a multimodal agent and ask for a DESIGN.md. It is fast, it works on any site, and it can describe mood and hierarchy well.

The values are the weak part, and the reason is the input. A screenshot holds pixels, not styles. It carries no custom property names, so every color gets a name the model made up. Hover and focus states are not in it unless you took a screenshot of each. Dark mode is not in it unless you took that too. Sizes are measured in image pixels, which depend on the screen's pixel density, and colors at the edge of text are blended with the background. What comes back is an estimate that reads like a specification, and an agent will build from it as if it were one.

Verdict: fine for the Overview section and a first draft; check every value before an agent builds from it.

Way 3: measure the live site, then have an agent write it

The third way splits the job. A tool measures what the browser draws; a model does the writing. Page Scanner's design extract does the measuring, in your own Chrome through the extension, and its design-md agent skill tells the agent how to turn the files into a DESIGN.md.

Install the skills once. In Claude Code, the plugin brings the skills and registers the MCP server:

claude plugin marketplace add sbd530/page-scanner-skillsclaude plugin install page-scanner@page-scanner-skills

For other agents (Codex, Cursor, GitHub Copilot, Gemini CLI and the rest):

npx skills add sbd530/page-scanner-skills

Then connect Chrome once, as the pairing page describes, and ask: "Write a DESIGN.md for https://example.com/." The skill has the agent run the extract, through the MCP server's extract_design tool or the command line:

page-scanner design --crawl https://example.com/ --components --out ./example-design --json

--crawl reads one page of each kind the site links to, 10 unless you say otherwise, so the pricing table and the docs sidebar are in the same design. Each page is read twice, in its light scheme and its dark one. What the files hold, and how this compares with other extraction tools, is in How to extract a website's design system; this post is about the document that comes after.

The skill then reads the files in a fixed order and writes under a few rules:

1. tokens.json first. A token the site declared as a custom property keeps its name exactly, -- and all. A value the site uses often but never named arrives numbered by use, color-1 being the most used, and the agent names it by role (text-primary, surface-card) while a Provenance table maps each name it gave back to the number it had. You can always tell the site's names from the agent's.
2. audit.md next. Two grays a hair apart, or a 5 px radius among 4s and 6s, are reported as probable slips. They are never promoted to tokens.
3. contrast.md. Every text color over the background it is drawn on, with its WCAG 2 ratio. Pairs below AA become Do and don't rules. Text over a gradient or a picture was not measured, and the document says it needs a look by eye.
4. components.json, with --components: each component, its variants, and what changes on hover and focus. The skill writes one table per component and says "not seen" rather than "none" for a state it has no measurement of.
5. The outline: Provenance, Color, Typography, Shape and space, Components, Do and don't, and Gaps. Every hex value and size in the document has to be in one of the files. A value the agent wants and no file has goes under Gaps.

The skill also tells the agent never to copy the site's logo, icons, images, fonts or text. It names a font family; it does not bundle one.

What it costs. You need Chrome with the extension, Node.js 24 and the @page-scanner/cli package; there is no button for this in the extension. Each page is read over Chrome's debugger, so Chrome's debugging bar shows while it runs. It reads each page's top document, not the frames inside it. States are read on the first instance of each component only, and a component that appears only after a click, such as a closed menu, is not seen. A site that switches theme only from its own toggle, not from the system setting, reads the same in both passes. A page behind a login is read only from a tab you have open (--tab).

One honest mismatch: the skill's outline is its own, not the Stitch section order, and it writes no YAML front matter. If a tool of yours expects the Stitch format, ask the agent to restructure the document into it and run the lint above. The values carry over; only the layout changes.

Verdict: the way to document a site whose source you do not have, or whose tokens nobody wrote down, with every value traceable to a measurement.

Which should you use?

Use your own tokens if you own the design system and its tokens are in the repository.

Use screenshots if you want a quick first draft of the Overview and will check the values yourself.

Use a measurement if the design lives only in production, or you inherited it, or you want the dark scheme, the component states and the contrast failures written down from what the browser actually draws.

They combine well: measure for the values, then edit the prose by hand where you know the intent better than any measurement.

Frequently asked questions

Where should the file go? Where your agent looks for project instructions, usually the repository root, named DESIGN.md. If your agent reads an AGENTS.md or CLAUDE.md, add a line there saying to read DESIGN.md before touching UI.

Can I make a DESIGN.md from someone else's site? The extract measures styles any browser computes when it draws the page. The skill keeps the identity out: no logo, no images, no fonts, no copy. Whether you should build on another company's design is a question for you, not the tool.

Does Page Scanner send the site anywhere? The extract runs on your machine and asks no model anything; the CLI writes the files to a folder you choose. The agent you hand them to is a separate question, and depends on the agent.

Where this comes from

• Google: Stitch's DESIGN.md format is now open-source and the google-labs-code/design.md repository, with its specification.
• Page Scanner: page-scanner design, extract_design, the agent skill and pairing, and the design-md skill in sbd530/page-scanner-skills.