DESIGN.md with Claude Code

That one instruction is the core of the setup. But the wording of the instruction, the size of your file, and how you verify the output decide whether Claude Code follows your design system or quietly improvises around it. This page covers all three.

If the format is new to you: DESIGN.md is an open-source file format from Google that stores a complete design system in a single Markdown file: machine-readable design tokens (colors, typography, spacing, components) in YAML frontmatter, plus human-readable rationale in Markdown prose. AI coding agents like Claude Code, Cursor, and Copilot read it to generate UI that consistently matches your brand. For background, read what DESIGN.md is; for the full format reference, see the DESIGN.md guide.

Quick setup#

1. Put DESIGN.md in your repository root, next to CLAUDE.md and README.md. A minimal, spec-valid file looks like this:

   ---
   version: alpha
   name: Heritage
   colors:
     primary: "#1A1C1E"
     tertiary: "#B8422E"
     neutral: "#F7F5F2"
   typography:
     body-md:
       fontFamily: Public Sans
       fontSize: 1rem
       fontWeight: 400
       lineHeight: 1.6
   rounded:
     sm: 4px
   components:
     button-primary:
       backgroundColor: "{colors.tertiary}"
       textColor: "{colors.neutral}"
       rounded: "{rounded.sm}"
       padding: 12px
   ---
   
   ## Overview
   
   Architectural minimalism: deep ink text on warm limestone, with a single
   earthy red reserved exclusively for primary actions.
   

   Copy

2. Add the reference snippet to CLAUDE.md (full snippet below). Claude Code loads CLAUDE.md automatically at session start, so the instruction persists across sessions without re-prompting.

3. Test it. Start a fresh session and prompt: "Build a settings page with a primary button and a form. Use only tokens from DESIGN.md." Then check the generated code for your exact values: in this example, a #B8422E button with #F7F5F2 text and a 4px radius. If you see a Tailwind default blue instead, the reference isn't working; see troubleshooting below.

Does Claude Code read DESIGN.md automatically?#

No. As of July 2026, Claude Code has no native DESIGN.md feature: it treats the file like any other Markdown in your repo. Google's Stitch is reported to consume the format natively, but coding agents like Claude Code, Cursor, and Copilot need an explicit pointer. For Claude Code, that pointer belongs in CLAUDE.md, which is loaded automatically; an AGENTS.md reference works the same way if you standardize on that file (see DESIGN.md vs CLAUDE.md and AGENTS.md).

Mechanically, DESIGN.md is plain context: the agent reads the file, and the YAML tokens plus prose rules inform every subsequent UI decision. The spec is built for exactly this: "the tokens are the normative values; the prose provides context for how to apply them."

Context has a cost, so file size matters. In our July 2026 analysis of all 74 files in the awesome-design-md collection, the median DESIGN.md weighs in around 7,050 tokens (546 lines), with the largest around 11,000. That is an affordable slice of a modern context window, but not free. In Atlassian's published test, a DESIGN.md file covered only about 30% of their large design system, while their MCP server and skills covered about 80%, and using the file as the sole source needed roughly 92% more tokens than the MCP approach. Their counterpoint: the file still gave them the best one-shot prototypes, taking output "from generic 'slop' to something recognizably Atlassian". Atlassian's own conclusion was that DESIGN.md suits high-level art direction, quick prototyping in unfamiliar environments, design-tool interoperability, and customer theming, and that MCP or skills give better results at lower cost when your agent supports them. The practical takeaway here: keep the file focused (see troubleshooting) rather than encyclopedic.

The recommended CLAUDE.md snippet#

Copy this into your CLAUDE.md:

## Design system

- Before writing or modifying any UI code (components, styles, layouts,
  themes), read DESIGN.md in the repository root.
- The YAML frontmatter in DESIGN.md is the single source of truth for
  colors, typography, spacing, radii, and component styles. Use token
  values exactly as written: never approximate a color, font size, or
  spacing value, and never introduce new ones.
- If a value you need is not defined in DESIGN.md (for example a warning
  color or an extra radius step), do NOT guess or invent one. Stop and
  ask me which token to use or whether to add one.
- Treat the "Do's and Don'ts" section of DESIGN.md as hard constraints,
  not suggestions.
- After completing UI work, list which DESIGN.md tokens you used.

Each line targets a specific failure: the "before any UI code" trigger makes the read unconditional, "exactly as written" blocks near-miss approximations, the "ask, don't invent" rule prevents token fabrication when your file has gaps, and the closing self-report makes violations visible in the transcript instead of only in the rendered page.

How do you verify the output?#

Treat DESIGN.md as your acceptance spec, not just an input:

• Lint the source of truth first. Run npx @google/design.md lint DESIGN.md. An ambiguous or broken file (unresolvable {token} references, contrast failures) gives the agent room to improvise. Exit code 0 means the agent's instructions are at least internally consistent.
• Compare visually in the viewer. Paste your DESIGN.md into the DESIGN.md viewer to see your tokens rendered (palette, type scale, component styles) and hold the generated UI next to it. Mismatched values jump out faster in swatches than in code review.
• Use screenshots in the loop. Claude Code accepts images, so screenshot the generated screen and prompt: "Compare this against DESIGN.md and list every deviation." The agent is good at catching its own drift when explicitly asked.

Troubleshooting#

Advanced: skills and subagents#

Two patterns worth adopting once the basics work; the specifics of skill and subagent configuration vary by Claude Code version, so treat these as patterns rather than exact recipes:

• A design-system skill. Claude Code skills bundle instructions the agent loads when relevant. Packaging the snippet above plus a lint step into a skill (a SKILL.md that says "read DESIGN.md, apply tokens, run npx @google/design.md lint DESIGN.md on any change to it") keeps design rules out of your main CLAUDE.md while still enforcing them for UI tasks.
• A design-review subagent. Have a subagent whose only job is review: it reads DESIGN.md, then checks a diff or screenshot against the tokens and the Do's and Don'ts, and reports deviations. Because it runs with fresh context, it isn't biased by the session that produced the UI.
• Inject the spec itself. For agents that generate or edit DESIGN.md files, npx @google/design.md spec --rules outputs the format specification plus lint rules, useful context so the agent writes spec-valid YAML (well-formed token maps, valid component properties) instead of guessing the schema.

Same file, other tools: the point of the format is portability. The identical DESIGN.md works in Cursor via a rules file (see how to use DESIGN.md with Cursor) and in any tool that reads AGENTS.md.

Next step: paste your DESIGN.md into the free DESIGN.md viewer and check that what Claude Code will read matches what you think you shipped: broken references and contrast problems are cheaper to fix before the agent inherits them.