What Is DESIGN.md and Why Your Agent Needs One

Google quietly open-sourced something in April that has already changed how coding agents handle UI. It is called DESIGN.md — a plain-text format specification for describing a visual identity to coding agents. The repo hit 18,700 stars in its first two months, gaining 5,200 in the first 72 hours alone. The community collection awesome-design-md crossed 64,000 stars. A third-party library at designmd.app now indexes 454 documented design systems you can drop into any project.

📖 Read the full version with charts and embedded sources on AgentConn →

Those numbers would be notable for any developer tool. They are remarkable for a format that contains zero executable code. DESIGN.md is a markdown file. It sits at the root of your project alongside README.md and CLAUDE.md. And it solves a problem that every team using a coding agent has hit: the agent writes working code, but the output does not match your design system.

The Problem DESIGN.md Solves

LLMs process each prompt in isolation. Without a persistent reference in the repository, every generated component uses different visual decisions — different spacing, different border radii, different type scales, different color values. The agent is not wrong. It is guessing, because you never told it what right looks like.

This is the exact pain that Anthropic's Claude Design Sync addresses for Claude Code users. But Design Sync is proprietary to Anthropic's ecosystem. If you work across Claude Code, Cursor, Gemini CLI, Codex, or any other harness, you need a portable format — one that lives in the repo, not in the tool.

That is what DESIGN.md is. Google's official announcement frames it plainly: "We're open-sourcing the draft specification for DESIGN.md, so it can be used across any tool or platform." David East from Google put it more concisely: "DESIGN.md is now an open specification. A shared format to capture design intent and token values in any project."

The analogy that keeps surfacing in community discussions is clean: README.md explains your codebase to human contributors. DESIGN.md explains your design system to AI agents.

What Goes in a DESIGN.md

The format has two layers. YAML front matter between --- fences at the top carries machine-readable design tokens — colors, typography, spacing, breakpoints, component patterns. Markdown prose below carries the human-readable rationale — why those values were chosen, what constraints they encode, what the UI must never do.

Here is the minimal structure from the spec:

---
name: "Your Product"
version: "1.0"
tokens:
  colors:
    primary: "#1a73e8"
    background: "#ffffff"
    text: "#202124"
  typography:
    font-family: "Inter, system-ui, sans-serif"
    base-size: "16px"
    scale: 1.25
  spacing:
    unit: "8px"
    scale: [4, 8, 12, 16, 24, 32, 48, 64]
---

Below the front matter, you write prose that explains the design system's intent:

## Typography

Inter is the primary typeface. Use JetBrains Mono for code blocks.
The type scale follows a 1.25 ratio from a 16px base.
Never use font weights below 400.

## Color

The primary blue (#1a73e8) is for interactive elements only.
Do not use it for decorative backgrounds or large text blocks.
Destructive actions use #d93025. Success uses #1e8e3e.

## Don'ts

- No rounded avatars. All profile images are square with 4px radius.
- No gradients on buttons. Flat color only.
- No skeleton loaders. Use a centered spinner with primary blue.

The tokens are what agents parse programmatically. The prose is what agents use for judgment calls. Both layers matter, and the failure mode is always in the same place.

The Fabrication Problem

The most important insight in the DESIGN.md ecosystem comes from a UX Collective tutorial that cuts past the hype: "The part that makes the file actually good is the interview — the questions that establish what the product does, who uses it, what the UI must always do, and what it can never do."

The tutorial describes what happens when you skip the interview and let the agent generate a DESIGN.md from a Figma export or a set of screenshots: "The tokens were perfect. The reasoning layer was fabricated."

This is the authoring mistake that turns a useful spec into noise. The agent sees your colors and type scale and border radii and infers them correctly — those are mechanical observations. But the agent cannot know why you chose a 1.25 type scale instead of 1.333, or why destructive actions use red instead of a muted warning, or why profile images are square. Without those decisions from a human, the agent invents plausible-sounding rationale that happens to be wrong. Then the next agent reads that fabricated rationale and treats it as authoritative constraint.

The fix is straightforward: write the prose yourself, or use a structured interview that forces human input before any generation happens. The Stitch skills library implements exactly this pattern — its skill starts with four mandatory questions that establish product context, existing tokens, the UI's core job, and the constraints, before generating anything. The tokens can be extracted from code. The reasoning must come from the team.

The Ecosystem That Built in Two Months

The velocity of the DESIGN.md ecosystem is the strongest signal that this is not a niche Google experiment. In the two months since open-sourcing:

Community libraries exploded. awesome-design-md at 64K stars contains pre-built DESIGN.md files for major design systems — Material, Tailwind, Shadcn, Radix, Chakra. designmd.app indexes 454 systems with documented tokens. These are the mattpocock/skills pattern applied to design — community-maintained markdown directories that make the format useful before you write a single line.

Cross-tool adoption is real. DESIGN.md works with Claude Code, Cursor, Gemini CLI, Codex, Windsurf, Kiro, and anything else that reads markdown from the project root. Meng To captured the value proposition: "Google wants a shared design language for AI. DESIGN.md gives designers, developers, and agents one standard way to describe how a product should look, instead of translating taste through prompts, screenshots, and scattered notes."

Google integrated it into their own agent stack. The Google Codelabs tutorial demonstrates how Stitch + Antigravity + the design-md MCP skill form a pipeline: design in Stitch, export DESIGN.md, hand off to a coding agent that reads the spec and generates implementation code. The Stitch account on X confirmed: "DESIGN.md lets you easily export and import your design rules from project to project."

The "Complete Guide" articles are already shipping. Marco Kotrotsos wrote: "Not a novelty — design.md is one of the most significant developer experience improvements for AI-assisted coding." The Design Systems Collective framed it as a workflow shift: "Google Stitch and Claude Code quietly changed the design-to-code handoff with DESIGN.md as the shared context layer."

How DESIGN.md Relates to Other Context Files

If you are already using coding agents seriously, your project root probably has several context files:

File	What it tells the agent	Who maintains it
README.md	What the project is, how to run it	Engineering
CLAUDE.md / AGENTS.md	Coding conventions, tool preferences, workflow rules	Engineering
DESIGN.md	Visual identity — tokens, rationale, constraints	Design + Engineering
.cursorrules	Cursor-specific behavior overrides	Engineering

DESIGN.md occupies a distinct slot. CLAUDE.md tells the agent how to work. DESIGN.md tells the agent how things should look. The two are complementary — you want both.

The relationship to skills is also worth clarifying. DESIGN.md is not a skill. It does not contain procedural instructions or slash commands. It is a context file — static reference material that the agent reads once and applies throughout a session. Skills orchestrate behavior; DESIGN.md informs judgment. In the three-layer architecture (skills for orchestration, MCP for registry, CLI for execution), DESIGN.md sits alongside CLAUDE.md as part of the context layer that shapes how all three layers operate.

How to Write One That Works

Based on the tutorials, the community patterns, and the spec itself, here is the practical authoring guide.

Start with the interview, not the tokens. Answer four questions before writing anything:

1. What does this product do, and who uses it?
2. What existing design tokens does it have (colors, type, spacing)?
3. What must the UI always do? (e.g., "always show a loading state," "always left-align form labels")
4. What must the UI never do? (e.g., "never use modals for confirmations," "never auto-play media")

Questions 3 and 4 are the most valuable. They encode the judgment that agents cannot infer from screenshots.

Organize in four sections:

1. Brief — one paragraph describing the product, audience, and design posture
2. Tokens — YAML front matter with colors, typography, spacing, breakpoints, shadows
3. Components — patterns the agent should follow (card layouts, form structures, navigation)
4. Don'ts — explicit prohibitions that prevent the agent from generating plausible but wrong UI

Keep it under 2,000 tokens. DESIGN.md gets injected into every agent context window. A 5,000-token DESIGN.md means 5,000 fewer tokens for the agent to think with. The token compression work we covered at AgentConn applies here — every context-window byte has a cost. Be terse. If you are writing paragraphs of rationale, you are writing too much.

Use one of the 454 library files as a starting point. Go to designmd.app/library, find the design system closest to yours, copy it, and customize. You will get the structure right and save an hour of formatting. The awesome-design-md collection is another good starting point — "drop one into your project and let coding agents generate a matching UI."

Version it. DESIGN.md lives in git. When your design system changes — and it will — the DESIGN.md changes with it. The spec includes a version field in the YAML front matter for exactly this reason.

The Supply Chain Question

One risk worth flagging: community DESIGN.md files carry the same supply chain risks as community skill files. A malicious DESIGN.md could contain prose instructions that look like design rationale but actually direct the agent to inject code, add external dependencies, or modify security-sensitive files.

The mitigation is the same as for skills: read what you import. DESIGN.md files are short — most are under 200 lines. Review them before committing. Do not blindly copy a 454-system library entry into a production project without reading it. The format is plain text. The attack surface is the agent's willingness to follow instructions embedded in what looks like a context file.

The Bigger Picture

DESIGN.md matters because it signals a convergence in how the agent stack handles context. Six months ago, every tool had its own way of ingesting design information — Cursor had .cursorrules, Claude had Design Sync, Copilot had nothing. Now there is a portable, tool-agnostic spec backed by Google, adopted by the community, and compatible with every major coding agent.

The pattern is familiar. README.md standardized how projects explain themselves to humans. package.json standardized how projects declare dependencies. DESIGN.md is standardizing how projects explain their visual identity to agents. It is a small file with an outsized effect — the difference between an agent that generates working code and an agent that generates working code that looks like it belongs in your product.

If you are using a coding agent and you do not have a DESIGN.md in your project root, you are relying on the agent's default aesthetic judgment. For some projects, that is fine. For anything with a brand, a design system, or users who will notice when the button radius changes between pages — write the file. It takes thirty minutes. The spec is Apache 2.0. The library has 454 starting points. The agent is already reading your project root. Give it something useful to find there.

Originally published at AgentConn