What Is DESIGN.md? The File That Gives AI Agents Your Design System
DESIGN.md is an open format from Google Labs that describes a design system to AI coding agents. It combines machine-readable design tokens (in YAML front matter) with human-readable rationale (in markdown prose), so an agent generates UI that matches your brand instead of generic defaults. Released in 2026 under an open license, it lives in your repository and is read by agents before they generate any interface.
Why do AI agents need DESIGN.md?
Left alone, an AI coding agent draws on the most common patterns in its training data — generic blues, default fonts, arbitrary spacing. It has no way to know your design system unless you tell it, every single time. The result is UI that looks plausible but not like yours: the wrong shade, a font that does not match, spacing pulled from nowhere.
DESIGN.md removes the "every single time." You describe your visual identity once, in a file the agent reads before generating any UI, and from then on it has a persistent, structured reference to consult.
Where does DESIGN.md live?
DESIGN.md is a plain file in the root of your repository. Because it is just markdown with YAML front matter — formats every developer already knows — it needs no build step and no special viewer. An agent can read it as-is, and it travels with your project across branches and sessions.
How does DESIGN.md relate to CLAUDE.md and AGENTS.md?
If you already use CLAUDE.md or AGENTS.md, DESIGN.md will feel familiar. It belongs to the same family of plain-text, repository-resident context files for agents. The analogy is exact: DESIGN.md is to design what AGENTS.md and CLAUDE.md are to code conventions. They are complementary layers — code context, capabilities, and now design context — that do not overlap.
What goes inside a DESIGN.md file?
A DESIGN.md has two parts. The YAML front matter holds design tokens — colors, typography, spacing, rounded corners, and components — as exact values. The markdown body holds the rationale: what each color is for, how the type scale works, and the rules to follow. Tokens give the precise values; prose gives the intent.
FAQ
Is DESIGN.md free? Yes. It is an open format released by Google Labs under an open license, with a free official CLI.
Do I need a build pipeline? No. An agent reads the file as-is; the CLI adds validation and export when you want them.
Which agents support it? As a plain repository file, it works with any agent that has a persistent-context mechanism, including Claude Code, Cursor, Kiro and Windsurf.