AI Coding Agents and DESIGN.md

AI coding agents generate UI code quickly but start each session without knowledge of your brand. A DESIGN.md at the repository root provides persistent, machine-readable design context that any agent can read before generating components. The approach works independently of which agent or tool you use because it relies on file access, not a proprietary integration.

The persistent-context problem#

AI coding agents produce markup, styles, and component structure from a natural-language description. They do this well. What they do not have is any memory of your brand between sessions.

Begin a new session and the agent starts with no knowledge of your palette, your type scale, or your corner-radius system. Without explicit context, it makes reasonable defaults: a generic font, a commonly used accent color, rounded corners that feel plausible. If you want your actual brand values, you have to describe them again, every time.

This is the persistent-context problem. It applies regardless of which agent-assisted coding tool you use.

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

A DESIGN.md stores design decisions in a plain-text file the repository persists across sessions, so any agent reading the working directory can access your brand tokens without re-briefing. For a detailed breakdown of format, mechanics, and worked examples, see DESIGN.md for AI Coding Agents: Persistent Design Context.

What the file gives an agent#

A minimal DESIGN.md tells an agent:

  • The exact hex values for each named color role (primary, secondary, tertiary, surface, etc.).
  • The type scale: font families, sizes, weights, and line-heights for each named style.
  • The corner-radius scale and spacing scale.
  • The default visual properties for key components (buttons, inputs, etc.), expressed as token references.
  • Prose context for how the design language is meant to feel and what it avoids.

With this file in context, an agent generating a button knows to use {colors.tertiary} for the background, {typography.label-md} for the label, and {rounded.md} for the corner radius. Without it, those choices are arbitrary.

For the full token model including the three-tier architecture, see Design Tokens: The Complete Guide.

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

The mechanics of providing file context to a coding agent depend on the specific tool and version you use. These details change as tools evolve, so this guide describes the general approaches rather than tool-specific steps.

Reference the file explicitly in your prompt. Most agent-assisted tools let you include files as part of the context you pass with a request. Pointing the agent at your DESIGN.md, or including its contents directly, gives it immediate access.

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

Include an instruction in a persistent instructions file. Some tools support a persistent configuration or instructions file that is read at the start of every session. Adding a line that directs the agent to read DESIGN.md for design tokens carries the instruction forward without repeating it in every prompt. The exact mechanism varies by tool and version.

The defensible, durable principle: a DESIGN.md is a plain file any agent can read. Make it accessible, tell the agent it exists, and the agent can apply your brand values without repeated briefing.

For a detailed walkthrough of these approaches, including worked examples for Claude Code and Cursor, see DESIGN.md for AI Coding Agents: Persistent Design Context.

The spec command#

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

npx @google/design.md spec

This outputs the DESIGN.md format specification as Markdown. Including this in a system prompt or instructions file helps an agent understand how to author or modify DESIGN.md files, not only how to read and apply them.

Why this approach is durable#

The file-in-repo approach has properties that survive tool changes:

Version-controlled. The file lives in git alongside the code it describes. Design decisions are reviewable as diffs. Branches carry their own design context. Pull requests can include token changes.

Format-agnostic. Plain text survives migrations between tools. If you change from one coding agent to another, the DESIGN.md remains and remains readable. There is no re-export step and no proprietary lock-in.

Lintable. Run npx @google/design.md lint DESIGN.md before committing to surface broken token references, missing required keys, and WCAG AA contrast failures. Silent inconsistencies become visible errors.

Exportable to other formats. The same DESIGN.md can export to a Tailwind v4 @theme block for the implementation layer, or to W3C DTCG JSON for design-tool pipelines. The agent-facing file and the build-facing output are derived from the same source. See DESIGN.md vs DTCG for a comparison.

DESIGN.md and broader brand guidelines#

A DESIGN.md covers the token-and-component layer of a visual identity: colors, typography, spacing, rounded corners, component defaults. It does not cover logos, photography, motion principles, icon systems, or verbal identity. For how these layers relate, see Brand Guidelines and DESIGN.md.

Rendering a DESIGN.md to check it#

Once you have a DESIGN.md, the viewer at /tool renders it as a navigable brand guideline so you can confirm every token resolves before an agent relies on it. Parsing runs entirely in your browser, so nothing is uploaded. If you do not have a file yet, How to Write a DESIGN.md walks through authoring one, and DESIGN.md Tools Compared covers generators that create a starting file from a brand or a site. Whichever route you take, render the result in the tool to validate it.

Where to go next#

Try it in the tool

Was this page helpful?