What Is DESIGN.md? A Practical Guide to Design Systems for AI Agents

Google Labs has introduced DESIGN.md, an open format that allows AI coding agents to read a project's design system from a single file, ensuring generated UI matches brand guidelines instead of generic defaults. The format uses YAML front matter for machine-readable tokens and markdown prose for human-readable rules, requiring no build step. It works with agents like Claude Code, Cursor, Kiro, and Windsurf that support persistent context.

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. 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. 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. --- 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. 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. 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. 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 https://promptmasterstore.gumroad.com/l/design-md-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 https://promptmasterstore.gumroad.com/l/design-md-guide 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.