DESIGN.md for AI Coding Agents

The core problem: agents forget#

AI coding agents are powerful at generating UI code. Given a component description, they produce markup, styles, and structure quickly. But they have no inherent memory of your brand.

Start a new session and the agent starts fresh. Without explicit context, it makes its own choices: a generic sans-serif font, a blue accent color, rounded corners that happen to feel right. If you want your brand's actual palette and typography, you have to describe them again, every time.

This is the persistent-context problem. It applies whether you are using Claude Code, Cursor, or any other agent-assisted coding tool.

A DESIGN.md is design context that lives in the repo#

The solution is to store design decisions in a file the agent can read, rather than repeating them in every prompt.

DESIGN.md (@google/design.md, Apache 2.0, v0.3.0) is an open format for encoding a visual identity in plain text. A DESIGN.md file sits at the project root alongside README.md. It has two layers:

1. YAML frontmatter: machine-readable tokens (colors, typography, spacing, rounded corners, component styles).
2. Markdown body: human-readable rationale explaining how and why to apply the tokens.

Because it is a plain file in the repository, any coding agent that can read files from the working directory can read your DESIGN.md.

What goes in the file#

A minimal DESIGN.md with enough information for an agent to produce consistent UI:

---
name: Vault
version: alpha
colors:
  primary: "#0F172A"
  secondary: "#475569"
  tertiary: "#3B82F6"
  neutral: "#F8FAFC"
  surface: "#FFFFFF"
  on-surface: "#0F172A"
typography:
  headline-lg:
    fontFamily: "Inter"
    fontSize: 36px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Inter"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.65
  label-md:
    fontFamily: "Inter"
    fontSize: 12px
    fontWeight: 500
    letterSpacing: "0.06em"
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 12px
---

## Overview

Vault is a document management tool. The design language is calm and
professional: dark navy on white, with a single blue accent for interactive
elements. No gradients. No decorative borders.

## Colors

- **Primary (#0F172A):** Deep navy for all body text and chrome.
- **Tertiary (#3B82F6):** Cerulean blue, used exclusively for interactive
  elements (links, buttons, focus rings).
- **Surface (#FFFFFF):** Card and panel backgrounds.

## Typography

Inter at three scales. Headline tracks tight (-0.02em). Label tracks open
(0.06em) for legibility at small sizes.

An agent that reads this file knows the palette, the type scale, the corner radius system, and the component defaults before you write a single prompt about the UI.

How to give a DESIGN.md to a coding agent#

The mechanics depend on which agent or tool you are using, and they change as tools evolve. The general approaches are:

Include it in context explicitly. Most coding agents let you reference files as part of the context you provide. Pointing the agent at your DESIGN.md file, or pasting its contents into the prompt, gives it immediate access to your design system.

Keep it at the project root. Agents that read the working directory often surface files from the root automatically. A DESIGN.md at the root has a reasonable chance of being included in the agent's project-level context, depending on the tool's behavior.

Reference it in a system prompt or instructions file. Some tools support a persistent instructions file (the exact mechanism varies and changes between tool versions). If you can add a line like "Read DESIGN.md for design tokens and apply them to all generated UI," the agent will carry that instruction across sessions.

The exact behavior of any particular tool is outside this document's scope: it changes frequently and varies by version. The defensible, durable principle is simpler: a DESIGN.md is a plain file that any agent can read. Make it available, tell the agent it exists, and let the agent use it.

For step-by-step, tool-specific setup (the exact instruction file and a copy-paste snippet), see DESIGN.md with Claude Code and DESIGN.md with Cursor.

What the agent spec command produces#

The @google/design.md package includes a spec command that formats the DESIGN.md specification for direct injection into an agent context:

npx @google/design.md spec

This outputs the DESIGN.md format specification as Markdown. You can include this in a system prompt to help an agent understand how to author or modify DESIGN.md files, not just read them.

Why this approach is durable#

A DESIGN.md carries several properties that make it a reliable foundation for AI-assisted UI work:

Version-controlled. The file lives in the repo and travels through branches, pull requests, and forks. Design decisions are reviewable as diffs.

Format-agnostic. Plain text survives tool changes. If you switch from one coding agent to another, the DESIGN.md is still there and still readable.

Lintable. Run npx @google/design.md lint DESIGN.md to validate the file before committing. Broken references and missing required tokens surface as errors rather than silent inconsistencies in generated UI.

Exportable. If you also need DTCG JSON for a design-tool pipeline, the CLI handles the conversion: npx @google/design.md export DESIGN.md --format dtcg. See DESIGN.md vs DTCG for a comparison of the two formats.

Practical starting points#

Once you have a DESIGN.md, render it in the viewer at /tool to confirm it is well-formed: paste or drop the file and see it rendered as a navigable brand guideline, with nothing uploaded. If you do not have a file yet, author one by hand or use a generator, then render it to validate it.

For a field-by-field guide to authoring the file yourself, see How to Write a DESIGN.md. For the tools that create a starting file, see DESIGN.md Tools Compared.

Try it in the tool

Read the DESIGN.md guide