DESIGN.md: The Agent-Native File Format That Makes AI Coding Agents Follow Brand Design Rules on Their Own
If you've used CLAUDE.md or AGENTS.md, you'll grasp the concept quickly. If those files tell an agent "how to code in this project," there's now a dedicated visual design layer that tells it "how things should look." In April 2026, Google Labs open-sourced DESIGN.md under the Apache 2.0 license — by storing brand colors, fonts, spacing, and accessibility standards in a single file, major AI coding tools like Claude Code, Cursor, GitHub Copilot, and v0 can all reference the same file for design rules. The official spec is still in Alpha and subject to change, but it's already becoming a de facto convention in the agent ecosystem.
Until now, every time I delegated UI work to an agent, I'd paste use #1A73E8, border-radius 8px, use IBM Plex Sans into the prompt over and over. That gets exhausting, and I've had the experience more than once where changing the prompt even slightly caused the agent to pick its own blue. This article explores what DESIGN.md is, how agents actually read it, and how to manage color, typography, spacing, and accessibility rules in a single file.
Core Concepts
The Dual Structure of YAML Tokens + Markdown Prose
Open a DESIGN.md and you'll find two distinct parts. At the very top is a YAML frontmatter block wrapped in ---, followed by a regular markdown body. YAML frontmatter may be unfamiliar to some, but it's the same format used to write page metadata in Jekyll blogs or Hugo sites — key: value pairs with indentation for structure.
---
name: "MyBrand"
colors:
primary: "#1A73E8"
secondary: "#34A853"
error: "#EA4335"
typography:
body-md:
fontFamily: "Google Sans"
fontSize: "16px"
fontWeight: "400"
heading-lg:
fontFamily: "Google Sans"
fontSize: "32px"
fontWeight: "700"
spacing:
sm: "8px"
md: "16px"
lg: "32px"
border-radius:
button: "8px"
card: "12px"
---
## Color Usage
`primary` is used only for interactive elements like buttons and links.
`secondary` is exclusively for success states. Do not use it for other purposes.
When placing primary on a dark background, always verify WCAG 4.5:1 contrast ratio.
## Typography
Headings always use the `heading-lg` token.
`body-md` is the default for body text; 0.875rem is permitted for supplementary descriptions.This separation is actually the heart of the format. The YAML frontmatter holds precise values for machines to read — agents pull HEX codes, px values, and font names directly from here. The markdown body provides context for both humans and AI to read together — it explains in natural language "why this color is used," "what the exceptions are," and "what the accessibility standards are."
A JSON file with only values can't explain the "why." A Figma link is something an agent can't even open without an API. DESIGN.md puts both in a single markdown file.
Agent-Native Design System: Where traditional Figma-based design systems were built for human designers, DESIGN.md is designed with the assumption that AI agents consume it directly. Humans can read it too, but agents are the priority.
How Agents Read DESIGN.md
One important point to address upfront: DESIGN.md is currently a convention-level format. When we say "agents read it automatically," the actual behavior varies by tool.
- Claude Code: The common approach is to explicitly reference DESIGN.md from CLAUDE.md, or to inject the file as context by attaching it to the prompt. If you write
Refer to DESIGN.md for UI workin CLAUDE.md, Claude Code will find and read that file. - Cursor: It's used by specifying it as a context file in project settings or referencing it from
.cursorrules. - v0 / Lovable: v0 is Vercel's AI UI builder, Lovable is an AI full-stack app builder. Both tools either have their own mechanism for recognizing DESIGN.md or operate via file attachment.
"Reads it automatically" doesn't mean it works identically across all tools. But the value of DESIGN.md as a tool-neutral convention is that any tool you give it to as context can receive your brand rules in the same file format.
Where DESIGN.md Sits in the Metafile Ecosystem
As AI coding tools have become widespread, files that "tell an agent the rules of this project" have formed an ecosystem. These files are collectively called "metafiles" — they don't contain code itself, but rather rules for how code should be written and how things should look.
When I first encountered this concept, a puzzle piece clicked into place. The directory structure below shows why:
project-root/
├── CLAUDE.md ← coding conventions, architecture rules (for Claude Code)
├── AGENTS.md ← GitHub Copilot-specific settings
├── GEMINI.md ← Gemini CLI-specific settings
├── DESIGN.md ← visual design rules (colors, typography, spacing)
└── src/If CLAUDE.md holds "how to code," DESIGN.md holds "how things should look." Now an agent can reference both files to build components with "the right architecture, following the right design rules."
Practical Application
Example 1: Generating a New Dashboard Component That Matches the Brand
This is the most basic usage pattern. Place DESIGN.md in the project root and ask the agent to generate a component — no need to include color values in the prompt.
First, write DESIGN.md in the project root like this:
---
name: "Acme Dashboard"
colors:
primary: "#0F62FE"
surface: "#F4F4F4"
text-primary: "#161616"
text-secondary: "#525252"
success: "#24A148"
danger: "#DA1E28"
typography:
heading-sm:
fontFamily: "IBM Plex Sans"
fontSize: "20px"
fontWeight: "600"
body:
fontFamily: "IBM Plex Sans"
fontSize: "14px"
fontWeight: "400"
spacing:
xs: "4px"
sm: "8px"
md: "16px"
lg: "24px"
xl: "40px"
border-radius:
sm: "4px"
md: "8px"
---
## Color Usage
`primary` is used only for primary action buttons and active state indicators.
`surface` is the card background color. Use `surface` instead of pure white (#FFFFFF).
`danger` is exclusively for error states and delete actions. Do not use it for warnings.
## Accessibility
All text-background combinations must meet WCAG AA standard (4.5:1).
When placing `text-secondary` on `surface`, always verify the contrast ratio.With this file in place, you can ask Claude Code something like:
Create a dashboard card component that shows user stats, following the DESIGN.md rulesBelow is an ideal example of what you can expect when this DESIGN.md is provided as context. Actual agent output may vary in how styles are expressed depending on the project's CSS environment (CSS Modules, Tailwind, styled-components, etc.).
// Ideal result example for a component referencing DESIGN.md tokens
// Actual output may use CSS variables or Tailwind classes depending on the project CSS environment
const StatsCard = ({ title, value, trend }: StatsCardProps) => {
return (
<div style={{
backgroundColor: '#F4F4F4', // surface token
borderRadius: '8px', // border-radius.md token
padding: '24px', // spacing.lg token
}}>
<h3 style={{
fontFamily: 'IBM Plex Sans', // typography.heading-sm
fontSize: '20px',
fontWeight: '600',
color: '#161616', // text-primary token
}}>
{title}
</h3>
<span style={{
color: trend > 0 ? '#24A148' : '#DA1E28', // success/danger tokens
}}>
{trend > 0 ? '▲' : '▼'} {Math.abs(trend)}%
</span>
</div>
);
};I was skeptical at first — "will the agent actually read the file and use these values?" — but when the context is clearly provided, it often even adds comments with the token names, which was quite impressive. The same DESIGN.md works in Vue, Svelte, or plain CSS environments too. Just tell the agent what styling approach you're using and it'll apply the same token values for that environment.
Example 2: Team Environment — Google Stitch Handoff Pipeline and Automated Accessibility Verification
For teams working with designers, the Stitch → DESIGN.md → agent pipeline is especially valuable. If you're developing solo, this section is worth reading as a reference.
1. Designer: Explore UI mockups in Google Stitch
↓
2. Export from Stitch to DESIGN.md
↓
3. Developer: Commit DESIGN.md to project root
↓
4. Request component generation from Claude Code
↓
5. Code review & mergeDESIGN.md generated by Stitch adds a components section to the base structure, including default styles per component.
---
name: "Stitch Export"
generated-by: "Google Stitch"
generated-at: "2026-04-15T09:30:00Z"
colors:
brand-blue: "#1A73E8"
brand-green: "#34A853"
neutral-100: "#F8F9FA"
neutral-900: "#202124"
typography:
display:
fontFamily: "Google Sans"
fontSize: "57px"
lineHeight: "64px"
body-large:
fontFamily: "Google Sans"
fontSize: "16px"
lineHeight: "24px"
components:
button-primary:
backgroundColor: "brand-blue"
textColor: "#FFFFFF"
borderRadius: "24px"
padding: "10px 24px"
---Compared to the traditional Figma → Zeplin → manual developer implementation workflow, this reduces typos and interpretation gaps that occur during handoff.
Including accessibility standards in DESIGN.md also offers additional benefits. WCAG (Web Content Accessibility Guidelines) is the international web accessibility standard; the AA level requires a contrast ratio of at least 4.5:1 for normal text against its background. Public sector websites in South Korea are legally required to comply with this standard.
---
name: "AccessibleUI"
colors:
background: "#FFFFFF"
text-default: "#212121"
text-muted: "#757575"
interactive: "#0063B1"
---
## Accessibility Requirements
This project complies with WCAG 2.1 AA standards.
- Body text (`text-default` on `background`): contrast ratio 15.8:1 ✓
- Secondary text (`text-muted` on `background`): contrast ratio 4.6:1 ✓ (passes minimum)
- Interactive elements (`interactive` on `background`): contrast ratio 7.2:1 ✓
When adding new color combinations, it is recommended to verify a contrast ratio of at least 4.5:1 and record the result in this file.
The same standards apply when an agent proposes color combinations.When contrast ratio values are explicitly stated in the file, agents are more likely to include feedback like "this combination may have low contrast and could violate WCAG" when proposing new color combinations. This reduces the overhead of running a separate checker tool every time.
Pros and Cons Analysis
Here's what we've found from actually using it on a team.
Advantages
| Item | Details |
|---|---|
| Tool neutrality | Claude Code, Cursor, Copilot, v0, Lovable — a single file works regardless of which AI tool you use |
| Git version control | Pure text, so it can be managed in version control alongside code. Design change history appears in PRs |
| Precision + context together | YAML tokens (exact values) and Markdown prose (reasons and exceptions) coexist in one file |
| Fewer repetitive prompts | No need to paste design rules into every prompt — they're permanently referenced via file |
| Accessibility automation | Stating WCAG standards in the file prompts the agent to review compliance on its own |
| Low barrier to entry | Unlike JSON schemas or Figma token export formats, it's markdown that anyone can edit |
Disadvantages and Caveats
| Item | Details | Mitigation |
|---|---|---|
| Not a complete design system | Component logic, interactions, state transitions, etc. are not included | Use alongside existing systems like Storybook and Figma |
| Spec still in Alpha | Official spec is in alpha, so breaking changes are possible | Monitor the changelog for important projects |
| Auto-reading not guaranteed | Whether an agent automatically includes DESIGN.md in its context varies by tool | Explicitly reference it in CLAUDE.md or attach the file in the prompt |
| Initial setup cost | Manual conversion work is needed to migrate from an existing Figma system to DESIGN.md | Auto-generation tools are available, but verify behavior if the Alpha spec changes |
| AI interpretation variance | Agents interpret Markdown differently, which can cause inconsistencies in edge cases | Write prose descriptions concretely and explicitly state exception cases |
| Team discipline required | If the file isn't kept current alongside code, trust in it degrades | Set a rule requiring DESIGN.md updates in any design-change PR |
| Limits with complex brands | The more complex the identity, the larger the file grows, and it can hit agent context limits | Include only core tokens and consider splitting into per-component files |
The Most Common Mistakes in Practice
-
Filling in only the YAML frontmatter and leaving the markdown prose empty — When only token values exist and there's no "why," the agent makes incorrect judgments in exceptional situations. Describing constraints like "this color is only used in this context" in prose dramatically improves results.
-
Creating the file once and never updating it — A situation can arise where brand colors have changed but DESIGN.md still has old values. There are cases where the agent faithfully follows outdated rules and causes even greater confusion. Including a DESIGN.md update as a checklist item in design-change PRs is a good practice.
-
Putting too many tokens in one file — Packing 100+ color tokens and 50 typography variations into a single file means the latter half gets cut off in the agent's context window. In practice, focusing on 20–30 core tokens the agent references frequently is more realistic.
Closing Thoughts
"Coding rules go in CLAUDE.md, design rules go in DESIGN.md." The idea itself is simple, but its impact is quite tangible. The repetitive work of pasting color values into every prompt disappears, and brand rules are tracked in the same Git history as the code. Even when team members use different AI tools, everyone can share the same design standards. It's still an Alpha spec that may change, and not all tools behave in exactly the same way. Even so, DESIGN.md is the simplest, most Git-friendly way to tell an AI agent about your brand rules once and have it remember them indefinitely.
There are three steps you can take right now:
-
Identify the core tokens in your existing project — Start by writing down the 3–5 primary colors you're currently using, your font family, and your default spacing values. You can find these in Figma or CSS files, or input your site URL into the DESIGN.md Generator at
design.devfor automatic extraction. However, ecosystem tools at the Alpha spec stage may behave differently if the spec changes, so it's worth keeping an eye on the official repository as well. -
Create a DESIGN.md file and place it in the project root — You can reference example files for similar brands at
getdesign.mdorawesome-design-mdto get started. Fill in the token values in the YAML frontmatter, and even two or three lines in the markdown body explaining "why these values" is sufficient. -
Ask your AI agent to reference DESIGN.md — In Claude Code, you can write
Refer to DESIGN.md for UI workin CLAUDE.md, or directly request something likeCreate a login form component following the DESIGN.md rules. In Cursor, the natural approach is to specify it as a context file in project settings. Compare the first results with your previous approach and you'll feel the difference immediately.
References
- Stitch's DESIGN.md format is now open-source | Google Blog
- google-labs-code/design.md official spec repository | GitHub
- DESIGN.md official spec documentation | GitHub
- Google's open-source DESIGN.md gives AI agents a prompt-ready blueprint | The Decoder
- DESIGN.md Explained - The Format Reshaping How AI Builds | Department of Product
- DESIGN.md collection for AI coding agents | getdesign.md
- Library of 423 design systems for AI | designmd.app
- How to Use Google Stitch's Design.md File with Claude Code | MindStudio
- VoltAgent/awesome-design-md | GitHub
- design.md file - how to write a design system AI agents actually follow | designproject.io
- DESIGN.md Generator | design.dev