DESIGN.md Gives AI Agents a Memory for Your Brand

If you use Claude Code, Cursor, or GitHub Copilot to build UIs, you’ve hit this wall: the agent builds something technically correct and visually generic — wrong font weights, placeholder blue where your brand color should be, spacing pulled from nowhere. You paste in your Figma exports. You re-explain the color palette. Next session, same problem. On April 21, 2026, Google Labs open-sourced DESIGN.md, a plain-text format specification designed to give AI coding agents a persistent, structured understanding of your visual design system — so they stop guessing every time.

The format is now at v0.3.0 (released June 15), is trending on Hacker News today with over 200 upvotes, and has crossed 18,900 GitHub stars. It’s early, it’s alpha, and it’s already changing how developer-designer handoffs work.

What Is DESIGN.md and How Does It Work?

DESIGN.md is a single plain-text file that lives in your repository alongside your code. It combines two layers: YAML front matter containing machine-readable design tokens (exact hex codes, font sizes, spacing units), and markdown prose below it that explains the reasoning behind each decision. As Google’s official specification states: “Tokens give agents exact values. Prose tells them why those values exist and how to apply them.” That dual structure is what separates DESIGN.md from a simple token export — the rationale tells an agent when not to use your primary color, not just what the hex value is.

A minimal DESIGN.md looks like this:

---
version: alpha
name: YourBrand
colors:
  primary: "#1A73E8"
  surface: "#FFFFFF"
typography:
  h1:
    fontFamily: "Google Sans"
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
---

## Overview
A clean, modern interface built for clarity and trust.
Primary blue is the sole interaction driver — use it only on clickable elements.
Never apply it to decorative elements or backgrounds.

The file covers eight sections: Overview, Colors, Typography, Layout, Elevation, Shapes, Components, and Do’s/Don’ts. Each component entry maps properties to token references using {colors.primary} syntax, so agents follow your system rather than inventing values. The spec is open under Apache 2.0 and published at google-labs-code/design.md.

How to Add DESIGN.md to Claude Code and Cursor

Three ways to create a DESIGN.md: generate one automatically through Google Stitch (free, outputs a complete file from your Figma project), grab a template from the community awesome-design-md repo, or write it manually following the spec. Manual takes 30–60 minutes for a basic system; Stitch takes two minutes.

For Claude Code, reference it in your CLAUDE.md file with an @DESIGN.md instruction. For Cursor, add it to .cursorrules. Once it’s in either context file, your agent reads it automatically at session start — no re-explaining, no pasting tokens mid-conversation. The CLI gives you validation and export:

# Validate structure and WCAG contrast ratios
npx @google/design.md lint DESIGN.md

# Export to Tailwind config
npx @google/design.md export --format tailwind

# Check what changed between versions
npx @google/design.md diff v1.md v2.md

The lint command includes built-in WCAG AA contrast validation — every color pair you define gets checked automatically. That alone is worth the five minutes it takes to add a DESIGN.md to an existing project.

Related: Claude Code Dynamic Workflows: The Complete Guide

DESIGN.md Performance: What Atlassian’s Real Test Shows

Atlassian tested DESIGN.md against their internal MCP-based design system server and published the results. DESIGN.md consumed 92% more tokens (7.21 million vs 3.75 million) and took 35% longer to generate output. The core reason: DESIGN.md loads your entire design system into context at once, while their MCP server fetches only relevant details on demand. For teams with mature design systems and MCP infrastructure, DESIGN.md isn’t the most efficient path.

However, the quality gap was unambiguous. Atlassian’s own team noted: “DESIGN.md turned the generated interface from generic slop to something recognizably Atlassian, using expected values for color, spacing, shape and typography.” The tradeoff is real — more tokens, better output. For smaller teams without MCP servers running, the token overhead pays for itself in reduced iteration time on design corrections. Our verdict: use DESIGN.md now for prototyping and new projects. If your team has a mature component library and the engineering capacity to run an MCP design server, that’s the better production choice — but most teams don’t.

Related: The Two-Tool Stack: Cursor and Claude Code in 2026

Is DESIGN.md the OpenAPI Standard for Design Systems?

Google open-sourced DESIGN.md under Apache 2.0 with one explicit goal: make it a de facto standard. The OpenAPI parallel is apt. Before OpenAPI, every API had its own bespoke documentation format. After, tools could generate clients, mocks, and docs from a single spec file. DESIGN.md is attempting the same move for design systems — one format any agent can read, regardless of which tool you’re using.

Early signals are positive. The community getdesign.md curates DESIGN.md files for popular brands so developers can drop one in and instantly get brand-aware output. Atlassian has shipped their own. Google has positioned it as the default alongside Claude Code and Cursor integration guides. The format is still alpha — the spec will change before 1.0 — but this is precisely how standards form. If you want a say in the outcome, shipping a DESIGN.md file today and opening issues on the spec is how you influence it.

Key Takeaways

• DESIGN.md is an open Apache 2.0 format from Google Labs that gives AI coding agents (Claude Code, Cursor, Copilot) a persistent memory of your visual design system — ending the brand amnesia problem.
• The format combines machine-readable YAML tokens with markdown prose explaining design rationale. The prose is what makes it work: agents need context, not just values.
• Add it to your project in under an hour. Reference it in CLAUDE.md or .cursorrules for automatic session-level context. The CLI validates WCAG contrast automatically.
• Atlassian’s test showed 92% more token usage vs. MCP. For most teams without MCP infrastructure, that overhead is still worth it — the quality improvement is real and immediate.
• Google is betting this becomes a de facto standard like OpenAPI. Still alpha, but Atlassian adoption, community templates, and cross-agent support point in that direction.