What is DESIGN.md? Letting AI read your design system

DESIGN.md is a Markdown file at the root of a project that describes its design system in a form AI coding agents can use. The top of the file holds tokens (colour, type, radius, spacing) in YAML. The body explains in plain prose why those values exist and how to apply them. Google Labs open-sourced the format in April 2026.

I'm Hai Le, a UI/UX designer who writes code. This site is built with Next.js and Tailwind, and every visual rule it follows lives in a DESIGN.md at the repo root. I'll use that file as the running example.

Where does DESIGN.md come from?

DESIGN.md is a specification published by Google Labs in the google-labs-code/design.md repository. It came out of Stitch, Google's AI interface design tool, but the format itself has no dependency on Stitch. Any agent that can read files in your project can use it.

The README calls it "a format specification for describing a visual identity to coding agents". In practice it is the brand guide you would hand a new teammate, written for a teammate who happens to be a language model.

The basics, checked on 2026-10-04:

• Apache 2.0 licence.
• The version field is currently alpha.
• A CLI ships with it, run through npx @google/design.md, with lint, diff, export and spec commands.

Why would an agent need it?

Ask an AI to build a page with no other context and it falls back on defaults: a familiar blue-violet, a drop shadow under every card, semibold headings. The result looks fine and looks like nobody's product in particular.

That happens because the agent can't see your system. Your variables live in Figma, your reasoning lives in your head or a wiki page, and the only thing the agent reliably reads is the project folder.

DESIGN.md puts both halves there. Tokens give exact values. Prose gives intent, so when the agent hits a case the file never mentions, it guesses in your direction instead of the internet's.

A concrete case from this site. The brand magenta #FF009D measures 3.66:1 against white. With tokens alone, an agent will happily set a 14px link in it, and that link fails WCAG AA. My DESIGN.md says magenta text at 20px or below must use primary-text (#be0074, 6.09:1). That one paragraph removes a whole class of bug.

What goes inside the file?

Two layers.

YAML front matter, between two --- lines at the top. The spec defines version, name, description, and five token groups: colors, typography, rounded, spacing and components. Tokens can reference each other with curly-brace paths such as {colors.primary}.

The opening of this site's file, trimmed:

---
version: alpha
name: Haile-design-analysis
description: The Haile design language — a portfolio site whose surface
  pairs a pure-white canvas and a strictly neutral grey ladder with a
  single saturated magenta accent (#FF009D) ...

colors:
  background: "{neutral.50}"
  foreground: "{neutral.950}"
  primary: "{primary.500} / {primary.400}"
  primary-text: "{primary.700} / {primary.400}"   # extension — magenta at body size
  muted: "{neutral.100}"
  border: "{neutral.200}"

rounded:
  sm: 8px
  md: 12px
  pill: 9999px
---

A Markdown body with eight canonical sections, in this order:

Extra sections are allowed. The README says an unknown heading is preserved rather than treated as an error. Mine adds a "UI & Design System" preamble and a "Motion" section.

How is it different from Figma variables, tokens JSON and CLAUDE.md?

The row that trips people up is the last one. Claude Code loads CLAUDE.md at session start and, per the docs, can read AGENTS.md too. It does not load DESIGN.md on its own. You have to point at it.

If tokens are new to you, start with what a design token is. DESIGN.md is one way to package tokens, and the raw, alias and semantic layering in that post makes the colour section much shorter to write.

How does this site use it?

Three files, three jobs:

1. DESIGN.md is the source of truth for design.
2. app/globals.css translates the tokens into the CSS variables Tailwind reads. It's the only one of the three a browser ever sees.
3. AGENTS.md holds project conventions for agents, and its first rule points to DESIGN.md. CLAUDE.md is a single line, @AGENTS.md, which is Claude Code's import syntax.

When I ask Claude Code to build a new section, it loads AGENTS.md, follows the pointer and works inside the rules. Three of them earn their keep more than the rest.

Three surfaces, four text greys. The whole site uses three background values (#ffffff, #f8f8f8, #efefef) and four grey text tiers. The file adds: "If a design needs a fifth value, the layout is wrong." That sentence gives the agent a self-check before it invents a new tint.

No box-shadow anywhere. This is the rule agents break most without guidance, because nearly every UI sample online has shadows. My Elevation section lists the only allowed ways to separate layers and spells out that a modal separates from the page with a scrim.

A grey ramp numbered by distance from the background. I follow Radix here: neutral-50 is always the page and neutral-950 is always the strongest text, in both light and dark mode. That's the opposite of Tailwind's convention, so it gets its own section. Without it, an agent assumes neutral-50 is the lightest grey and dark mode breaks.

My full Figma-to-code loop is in Claude Code for designers, and pulling tokens straight out of a Figma file is covered in Figma MCP with Claude Code.

How do you write your first one?

You don't need a codebase to start.

1. Write a three-sentence Overview. What is the interface's character, what is the primary colour for, and what will you never do?
2. Copy your semantic colours out of Figma. Background, text, border, primary. Skip the raw ramps on a first pass.
3. Give each semantic colour a reason. Where it's used, where it isn't, what contrast it hits on which surface.
4. Add the type scale. Size, line height, weight, letter spacing, plus the governing rule (mine: weight 400 at every size, hierarchy from size and colour).
5. Write Do's and Don'ts from real mistakes. Ask an agent for a screen, note what it gets wrong, write that down. This is the section I edit most.
6. Point to it from CLAUDE.md or AGENTS.md. One line will do.

The spec includes a structural check. This command is copied from the official README. I haven't run it against this site's file yet, so I can't tell you how it scores.

npx @google/design.md lint DESIGN.md

Its rules include broken-ref, missing-primary, contrast-ratio and section-order. On Windows PowerShell the README recommends the designmd alias instead of design.md to avoid a file-association clash.

If Claude Code isn't installed yet, installing Claude Code starts from opening a terminal.

What mistakes should you avoid?

Tokens with no prose. A file that is all YAML is a JSON file with extra steps. The reasoning is the part only DESIGN.md carries.

Brand-deck adjectives. "Modern, clean, friendly" gives an agent nothing to decide with. Write rules you could check: "headings are always weight 400", "hover changes the fill to muted and nothing else".

Letting it go stale. I switched this site's typeface from Be Vietnam Pro to Google Sans Flex in September 2026. Had I updated the CSS and not DESIGN.md, every screen an agent built afterwards would have asked for the old font.

One rule, two answers. See the weight 600 example above. Choose one file as the source of truth and have the other point to it.

Putting code conventions in it. Folder structure, i18n libraries and file naming belong in CLAUDE.md or AGENTS.md. DESIGN.md should cover what a user can see.

Where to start

If you have a Figma file with variables, open a blank Markdown file and give the Overview ten minutes. Then ask an agent for one simple screen, see where it drifts, and record the drift under Do's and Don'ts. A few rounds of that and the file grows into exactly what your interface needs.

I built a 50-plus component system for Joyme before this format existed, and the hard part was always getting the reasoning across to engineers. You can see how in the Joyme case study. If your team needs someone to build a design system that both people and agents can follow, here's more about me.

Sources

• google-labs-code/design.md on GitHub: spec, section order, CLI, lint rules. Accessed 2026-10-04.
• DESIGN.md specification on the Stitch docs. Accessed 2026-10-04.
• The Decoder: Google's open-source DESIGN.md gives AI agents a prompt-ready blueprint: release date (23 April 2026).
• Claude Code docs: How Claude remembers your project: CLAUDE.md, AGENTS.md and @path imports.
• DESIGN.md, AGENTS.md, CLAUDE.md and app/globals.css in this site's repository.