DESIGN.md is an open format from Google Labs that describes a design system to AI coding agents. It pairs machine-readable design tokens (YAML front matter) with human-readable rationale (markdown prose), so an agent generates UI that matches your brand instead of generic defaults.

Why agents need it

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.

DESIGN.md removes the "every single time." You describe your visual identity once, in a file the agent reads before generating any UI.

Where it lives

DESIGN.md is a plain file in your repo root. Because it is markdown with YAML front matter — formats every developer knows — it needs no build step and no special viewer. The agent reads it as-is, and it travels with your project.

The two parts

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
---

## Colors
High-contrast neutrals with a single warm accent. Use the
accent (tertiary) only for the primary action - never decoratively.

The front matter gives the agent exact values. The prose gives it the rules. Together they let the agent apply your system correctly, not just access its raw numbers.

How it relates to CLAUDE.md and AGENTS.md

If you use CLAUDE.md or AGENTS.md, this will feel familiar. DESIGN.md is to design what those files are to code conventions — persistent context the agent reads on every interaction. Complementary layers that do not overlap.

FAQ

Is it free? Yes — open format, free CLI.
Do I need a build pipeline? No. The agent reads the file as-is.
Which agents work with it? Any with a persistent-context mechanism: Claude Code, Cursor, Kiro, Windsurf.

The bottom line

DESIGN.md is a small, durable investment: describe your design system once, and every UI an agent generates starts from your brand instead of a generic default.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents

Have you tried DESIGN.md yet, or are you still re-explaining your design system to your agent every session? Curious where people are in the comments.