DESIGN.md with Cursor

The setup takes five minutes. What takes judgment is writing the rule so Cursor actually complies, and knowing what to check when it still invents an off-brand blue. Both are covered below.

Quick refresher on the format itself: 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. New to it? Start with what DESIGN.md is; the DESIGN.md guide has the full token schema.

Quick setup#

1. Put DESIGN.md in your repository root. Keep the YAML frontmatter spec-valid: well-formed token maps, quoted hex colors, {token.references} that resolve. Run npx @google/design.md lint DESIGN.md to confirm before wiring it into Cursor; a broken file gives the model license to improvise.

2. Create a rule file at .cursor/rules/design-md.mdc (full snippet below). As of July 2026, Cursor stores project rules as Markdown files under .cursor/rules/; older versions used a single .cursorrules file. If your Cursor version differs, the rule text is what matters. Put it wherever your version keeps always-on project instructions.

3. Test in a fresh session. Prompt: "Build a login screen with a primary button. Use only tokens from DESIGN.md." Then search the generated code for your actual primary hex. If Cursor shipped a generic palette instead, the rule isn't being applied. See troubleshooting.

Here is the copy-paste rule file:

---
description: Project design system, apply to all UI work
alwaysApply: true
---

Before writing or modifying any UI code (components, styles, layouts, themes):

1. Read DESIGN.md in the repository root. Its YAML frontmatter is the
   single source of truth for colors, typography, spacing, radii, and
   component styles.
2. Use token values exactly as written. Never approximate a color, font
   size, or spacing value, and never introduce values that are not in
   DESIGN.md.
3. If a value you need is not defined in DESIGN.md, do NOT guess or
   invent one. Ask which token to use or whether to add one.
4. Treat the "Do's and Don'ts" section of DESIGN.md as hard constraints.
5. After completing UI work, list which DESIGN.md tokens you used.

The metadata keys (description, alwaysApply) follow Cursor's rule format as of July 2026; check Cursor's docs if your version rejects them.

Should the reference go in .cursor/rules or AGENTS.md?#

Both routes work; they differ in scope and portability. The reason you want either at all: chat prompts don't persist. A style instruction you type today is gone in tomorrow's session, and every teammate starts from zero. A rule file or AGENTS.md entry is committed to the repo, so the "read DESIGN.md first" behavior survives new sessions, new branches, and new hires.

A pragmatic default: put the instruction in AGENTS.md so every agent gets it, and keep a thin .cursor/rules file that says the same thing for Cursor specifically. The DESIGN.md file itself stays identical either way. That's the format's portability argument. If part of your team uses Claude Code, the equivalent setup is described in DESIGN.md with Claude Code; same file, different pointer.

How do you verify Cursor's output?#

Make the check visual, not vibes-based:

• Render your tokens. Paste DESIGN.md into the DESIGN.md viewer to see the palette, type scale, and component styles as swatches. Compare the generated screen against that rendering: a wrong radius or near-miss color is obvious side by side.
• Grep for fabricated values. Search new code for hex values and check each against your colors: map. Any hex not in DESIGN.md is fabricated and worth a follow-up prompt: "Replace every color not defined in DESIGN.md with the nearest defined token, or ask me."
• Ask Cursor to self-audit. "List every color, font size, and radius you used, next to the DESIGN.md token it came from." Values without a token next to them are your drift report.

Troubleshooting#

Cursor-specific tips#

These are working heuristics from our own use, not documented guarantees (Cursor's internals change quickly):

• Long agent runs drift more than short chats. Multi-file agent sessions accumulate context that dilutes your rule. For big UI features, restate the constraint in the task prompt itself ("follow DESIGN.md tokens exactly") rather than relying on the rule alone.
• Stronger models comply better. In our experience, larger frontier models follow exact token constraints more reliably than fast/cheap tiers. If brand fidelity matters for a task, pick the stronger model for it.
• Keep the rule short and the file authoritative. Don't duplicate token values inside the rule. Values belong in DESIGN.md only. Two sources of truth will eventually disagree, and the model has no way to know which one wins.
• Commit .cursor/rules to version control. The rule only helps teammates if it ships with the repo. Review changes to it like code: a well-meaning edit that softens "never" to "prefer" measurably loosens compliance.

Next step: lint your file (npx @google/design.md lint DESIGN.md), then drop it into the DESIGN.md viewer to see exactly what Cursor will be told to follow, and if teammates use Claude Code, wire up the same file there with DESIGN.md + Claude Code.