AI Coding Agents and DESIGN.md

The persistent-context problem#

AI coding agents produce markup, styles and component structure from a natural-language description. They have no memory of your brand between sessions. Start a new session and the agent knows nothing of your palette, type scale or corner-radius system, so it falls back on plausible defaults: a generic font, a common accent color, rounded corners that feel right.

A DESIGN.md stores those decisions in a plain-text file that lives in the repository. Any agent that can read the working directory can read it, and it is versioned in git next to the code it describes. The file does not enforce anything by itself. The agent has to be told it exists, and the way to do that differs per tool.

Agent reference#

Every row below was taken from the vendor's own documentation page linked in the last column. md-design.io is independent and not affiliated with any of these vendors. Behavior changes between releases, so check the linked page for your version.

Not every agent supports an import syntax. Where the vendor documents none (Codex, Copilot cloud agent, Jules, Windsurf, Cline), the reliable wiring is an instruction in plain words that names the file and its path.

One AGENTS.md for many agents#

AGENTS.md is a plain Markdown file with no required fields, and the closest file to the edited path applies. The agents.md site lists Codex, Jules, Gemini CLI, Windsurf, Copilot coding agent, Zed, Amp, Cursor, Aider, VS Code and others as supporting it (the site marks the list as partial). The vendor docs above confirm it for Claude Code, Cursor, Copilot, Codex, Windsurf, Kiro, Cline, Zed, Jules and Amp. Gemini CLI and Aider need a one-line setting. See DESIGN.md vs CLAUDE.md and AGENTS.md for how the two files divide the work.

A snippet that works in AGENTS.md:

## Design

Before generating or modifying any UI, read DESIGN.md at the repository root.
Use its color, typography, rounded and spacing tokens and its component
definitions exactly. Do not introduce values that are not in DESIGN.md.
Run `npx @google/design.md lint DESIGN.md` after editing it.

Keep the instruction short. The tokens stay in DESIGN.md, so there is one source of truth and a design change is a diff to one file.

Agents with their own instruction file#

Claude Code#

Claude Code loads ./CLAUDE.md or ./.claude/CLAUDE.md at the start of every session. CLAUDE.md files can import other files with @path/to/import, resolved relative to the importing file. Per the memory docs, a repository's AGENTS.md is read only when no CLAUDE.md exists in the working directory or above it (this needs Claude Code v2.1.277 or later), so a project that has both should import AGENTS.md from CLAUDE.md.

@AGENTS.md
@DESIGN.md

Imported files load into context together with the CLAUDE.md that imports them, so a large DESIGN.md counts against your context budget. Setup details are in DESIGN.md with Claude Code. Source: Claude Code memory docs.

Cursor#

Cursor reads project rules from .cursor/rules as .mdc files (a plain .md file there is ignored) and also supports AGENTS.md in the project root, including nested files. A rule can mention a file by path, such as @DESIGN.md. The docs state that the file's contents are not inlined into the prompt: the agent reads it with its tools when it needs the content. Set the rule to Always Apply so the pointer is present in every chat. Details are in DESIGN.md with Cursor. Source: Cursor rules.

GitHub Copilot#

GitHub documents three kinds of repository instructions: .github/copilot-instructions.md (repository-wide), .github/instructions/NAME.instructions.md with an applyTo glob in frontmatter (path-specific), and agent instructions in AGENTS.md, plus a single CLAUDE.md or GEMINI.md in the root. Support differs by surface. As of November 2026, GitHub's support matrix lists, for example:

• VS Code, Copilot Chat: repository-wide, path-specific, and AGENTS.md only for agent instructions.
• VS Code, cloud agent: repository-wide, path-specific, and AGENTS.md, CLAUDE.md and GEMINI.md.
• Copilot CLI: personal, repository-wide, path-specific and agent instructions.
• Code review: repository-wide instructions in VS Code; path-specific and agent files on GitHub.com.

The VS Code docs say to use Markdown links to reference files in instructions, with relative paths resolved from the instructions file, and the chat.includeReferencedInstructions setting governs linked instructions (the docs do not state its default). In .github/copilot-instructions.md:

For UI work, follow the design tokens in [DESIGN.md](../DESIGN.md).

GitHub documents no import syntax for the cloud agent or the other surfaces, so state the path in words there too. Sources: repository instructions, support matrix, VS Code custom instructions.

OpenAI Codex#

Codex reads AGENTS.md from ~/.codex (or CODEX_HOME) and then walks from the project root to the current directory, taking at most one file per directory: AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. Files are concatenated root-down, so files closer to the working directory override earlier guidance. The combined size is capped by project_doc_max_bytes, 32 KiB by default. The docs describe no import syntax, so the AGENTS.md snippet above is the wiring. Source: Codex AGENTS.md guide.

Gemini CLI#

Gemini CLI loads ~/.gemini/GEMINI.md, GEMINI.md files in the workspace and its parent directories, and scans for more when a tool touches a directory. GEMINI.md supports @file.md imports with relative or absolute paths. To reuse an AGENTS.md instead, set the file name list in settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

With a GEMINI.md, add @./DESIGN.md on its own line. Source: Gemini CLI GEMINI.md docs.

Windsurf#

Windsurf's docs list AGENTS.md (and AGENTS.local.md for personal rules) as always-on rules, read at the workspace root and in each directory down to the file being worked on. Legacy .windsurf/rules/*.md, .windsurf/global_rules.md and .windsurfrules files are imported by default, and rule files take a trigger: value (always_on, glob, model_decision or manual). The page documents no file reference syntax, so use the AGENTS.md snippet. Source: Windsurf Cascade memories and rules, which docs.windsurf.com redirects to.

Kiro#

Kiro steering files live in .kiro/steering/ (workspace) or ~/.kiro/steering/ (global), and the default inclusion mode is always. Steering files can pull in another file with #[[file:<relative_file_name>]], resolved from the workspace root for workspace steering. Kiro also reads AGENTS.md from the workspace root, always included, with no inclusion modes. A file .kiro/steering/design.md containing the following loads the whole DESIGN.md:

#[[file:DESIGN.md]]

Source: Kiro steering docs.

Cline#

Cline reads workspace rules from .clinerules/ or .cline/rules/ and, per its docs, AGENTS.md at the project level (~/.agents/AGENTS.md globally). It also detects .cursorrules and .windsurfrules. The docs define no reference syntax and show plain paths in prose, such as "follow the pattern in /src/utils/errors.ts". Source: Cline rules.

Zed#

Zed uses the first matching file from this list: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. Because only the first match is used, put the DESIGN.md instruction in whichever file Zed will actually pick. A repository with both .rules and AGENTS.md loads only .rules. Source: Zed rules.

Jules#

Jules automatically looks for a file named AGENTS.md in the root of the repository. The docs mention no other instruction file and no import syntax. Source: Jules getting started.

Amp#

Amp includes AGENTS.md from the working directory and its parents up to $HOME, plus subtree files when the agent reads a file there. If a directory has no AGENTS.md, it falls back to AGENT.md or CLAUDE.md. Inside AGENTS.md, @doc/style.md mentions include other files, resolved relative to the mentioning file (absolute paths are not supported, and mentions in code blocks are ignored). A mentioned file with globs: frontmatter is included only after Amp reads a matching file. In AGENTS.md:

For UI work, see @DESIGN.md

Source: Amp AGENTS.md docs.

Aider#

Aider does not read an instruction file by default. Load files read-only with aider --read DESIGN.md, or /read DESIGN.md in a session, or always through .aider.conf.yml:

read: [AGENTS.md, DESIGN.md]

Read-only files are cached when prompt caching is enabled. The agents.md site documents the read: AGENTS.md form. Source: Aider conventions.

App builders#

These tools keep instructions in their own interface rather than in a repository file, so the DESIGN.md content has to be copied in.

v0#

v0 documents Instructions: reusable prompts created from + in the prompt bar, then Instructions, then New Instruction, with a title and rule text. Checked instructions apply to your messages and are available across all chats and projects. The page does not mention file upload or a repository file, so paste the DESIGN.md content (or the part that matters for the task) into an instruction. Source: v0 Instructions.

Lovable#

Lovable has workspace instructions and project instructions, both plain text fields limited to 10,000 characters. The docs also note that instruction files such as AGENTS.md or CLAUDE.md in the project repository can provide guidance to the Lovable agent. A complete DESIGN.md can exceed 10,000 characters, so paste a condensed token summary there or keep the full file in the repository and reference it from AGENTS.md. Source: Lovable knowledge.

Bolt#

Bolt's help center describes project knowledge, text that persists across conversations and context resets and suits information that always applies, and an agents.md file: after you attach one in the chatbox, Bolt finds and uses it automatically. Attach an agents.md that contains the snippet above, or paste the tokens into project knowledge. Source: Bolt, manage project context.

Tools that work with design systems directly#

Google Stitch#

Stitch reads DESIGN.md when it generates screens and includes the file in a project's export zip (Stitch docs). The exported file is a normal file you can commit and wire into any agent above. In the other direction, Stitch's documentation offers a prompt for coding agents (it names Gemini, Claude Code, Cursor and Antigravity) that reads a codebase and writes a DESIGN.md, and a remote MCP server for connecting coding tools to Stitch projects. See Stitch and DESIGN.md. Sources: Import from your codebase, Google, Stitch DESIGN.md.

Claude Design#

Anthropic's setup guide does not mention DESIGN.md. Claude Design builds a design system from codebases, uploaded files, Figma files, decks, logos and fonts, and /design-sync in Claude Code covers React component libraries. As of November 2026, treat DESIGN.md as one of the files you can upload or keep in the codebase it reads. See Claude Design vs Google Stitch.

The spec command#

The @google/design.md package includes a spec command that prints the format specification as Markdown:

npx @google/design.md spec

Including that output in an instructions file helps an agent author or modify DESIGN.md files, not only read them. See the CLI reference for the other commands.

What the file gives an agent#

A DESIGN.md tells an agent the exact hex values for each named color role, the type scale, the corner-radius and spacing scales, default properties for key components expressed as token references, and prose on how the design language should feel. This minimal file passes npx @google/design.md lint with zero warnings:

---
name: Vault
version: alpha
colors:
  primary: "#0F172A"
  secondary: "#475569"
  tertiary: "#2563EB"
  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
  card:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.lg}"
    padding: 24px
---

## 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 (#2563EB):** Blue, used exclusively for interactive
  elements (links, buttons, focus rings).
- **Neutral (#F8FAFC):** Card backgrounds.
- **Surface (#FFFFFF):** Page and panel backgrounds.

## Typography

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

With this file in context, an agent generating a button uses {colors.tertiary} for the background, {typography.label-md} for the label and {rounded.md} for the corner radius. For the token model, see Design Tokens: The Complete Guide.

Check the file before an agent relies on it#

Run npx @google/design.md lint DESIGN.md to surface broken token references, missing required keys and WCAG AA contrast failures. The viewer at /tool renders an existing DESIGN.md as a navigable brand guideline and lints it in the browser, so you can confirm every token resolves. It never generates a file, and files are never uploaded or stored. To write a first file, see How to Create a DESIGN.md File, and Examples shows finished ones.

Where to go next#

• DESIGN.md with Claude Code and DESIGN.md with Cursor: the two deeper setup guides
• DESIGN.md vs CLAUDE.md and AGENTS.md: what belongs in which file
• DESIGN.md as an Agent Skill and DESIGN.md vs MCP: other ways to deliver design context
• Brand Guidelines and DESIGN.md: what a DESIGN.md captures compared with a brand book
• The DESIGN.md spec: frontmatter fields and section order