DESIGN.md: How to Give Cursor and Claude Code a Real Design System

Published August 11, 2026 · Updated August 11, 2026 · 9 min read · by the CSS DNA team

Quick answer: A DESIGN.md is a Markdown file describing your visual design system in a form a coding agent can read — design tokens in YAML front matter, then prose rules for using them. Put it in the project root and reference it from the file your agent already loads (CLAUDE.md, .cursor/rules, .github/copilot-instructions.md). The agent then builds with your colors and spacing instead of inventing its own.

The problem: agents don't have taste, they have defaults

Ask any coding agent for “a pricing card” and you get a recognizable artifact: #3b82f6 for the primary button, rounded-lg, shadow-md, gap-4, Inter at 16px. It is competent and it is not yours.

This is not the agent ignoring your design system. It never received one. In the absence of explicit tokens, a model falls back on whatever is most common in its training data — which, for web UI in 2026, is Tailwind's stock palette and spacing scale. The fix is not a better prompt. It is putting the tokens in context.

What a DESIGN.md actually is

A DESIGN.md is a Markdown file that describes a product's visual design system in a form an AI coding agent can read and follow. It has two halves that do different jobs:

• YAML front matter — the machine-parseable token block. Colors, fonts, type scale, spacing, radii, breakpoints. Values the agent copies verbatim.
• Markdown prose — the judgment. Which color is primary, what counts as elevation, what the agent must never do. Rules a JSON token file cannot express.

That second half is why DESIGN.md exists as a separate artifact from a W3C design tokens JSON file. Tokens tell the agent what values exist. DESIGN.md tells it which ones to reach for and when.

The five parts every good DESIGN.md has

1. Token front matter. Flat, named, quoted. No nesting deeper than two levels — agents copy flat structures more reliably.
2. A hard constraint sentence. One line, near the top, in the imperative: use only these tokens, invent nothing.
3. Usage frequency. Annotate colors with how often they appear. “Used 128×” tells the agent this is the primary; “used 3×” tells it this is an accent. Raw hex lists carry no hierarchy.
4. Negative constraints. What not to do is more actionable than what to do. “Never hard-code off-scale padding” beats “use consistent spacing.”
5. A target stack line. Tailwind v4, CSS Modules, styled-components, SwiftUI. Without it the agent picks, and it picks differently each session.

A complete DESIGN.md

This is the real shape — token block, constraint, annotated colors, rules, and a config the agent can paste:

---
source: https://linear.app
stack: "Next.js 15 + Tailwind v4"
design_tokens:
  colors:
    charcoal: "#08090a"
    porcelain: "#f7f8f8"
    iris: "#5e6ad2"
    slate: "#8a8f98"
    hairline: "#23252a"
  fonts:
    inter: "'Inter Variable', Inter, system-ui, sans-serif"
  font_sizes: ["13px", "15px", "17px", "21px", "32px", "56px"]
  spacing: ["4px", "8px", "12px", "16px", "24px", "32px", "64px"]
  radii: ["4px", "8px", "12px", "30px"]
  breakpoints: ["640px", "768px", "1024px", "1280px"]
---

# Design system — Linear

You are building UI that must match this design system. Use ONLY the
tokens below — do not invent new colors, font sizes, or spacing values.

**Target stack: Next.js 15 + Tailwind v4.** Generate idiomatic
components using these tokens.

## Colors
- `charcoal` — #08090a (near-black), used 214×
- `porcelain` — #f7f8f8 (off-white), used 186×
- `iris` — #5e6ad2 (indigo), used 41×
- `slate` — #8a8f98 (muted gray), used 97×
- `hairline` — #23252a (border gray), used 63×

## Typography
- **Inter Variable** (body + headings) — `'Inter Variable', Inter, system-ui, sans-serif`
- Type scale: 13px, 15px, 17px, 21px, 32px, 56px

## Spacing
4px · 8px · 12px · 16px · 24px · 32px · 64px

## Elevation (shadows)
- shadow-1: `0 1px 2px rgba(0,0,0,.28)`
- shadow-2: `0 7px 32px rgba(0,0,0,.35)`

## Motion
Durations: 120ms, 250ms · Easings: cubic-bezier(.25,.46,.45,.94)

## Rules
- Use the most-frequent color as the primary; reserve the rest for accents and states.
- Stick to the spacing scale — never hard-code off-scale margins or padding.
- Match the type scale; don't introduce new font sizes.
- Reuse the shadow and radius values so elevation stays consistent.
- Body text is 15px, not 16px. Do not round it up.

## Known issues to avoid
The source page's CSS health scored 78/100. Do NOT copy these problems:
- Duplicate selectors: 14 rules re-declare `.button` across 3 files.
- Orphaned variables: 6 custom properties are defined but never referenced.

Two details do most of the work here. The usage counts give the agent a hierarchy it can reason about. The “Known issues to avoid” section stops it from faithfully reproducing the source's mistakes — which is exactly what happens when you extract from a real site and hand the result over uncritically.

Where each agent looks for it

Agents do not scan for a file called DESIGN.md. Each has its own entry point, and the reliable pattern is: keep DESIGN.md as the single source of truth in the project root, then point the agent's own config file at it.

Keeping one file and four pointers means you update tokens in one place. Duplicating the token block into four config files means three of them go stale.

Generating one in about thirty seconds

Writing a DESIGN.md by hand means auditing your own app for every color and size actually in use — which is the part nobody does. Reading it off the rendered page is faster and more honest:

1. Install CSS DNA and open the site — your own app, staging, or a reference you're designing toward.
2. Click Extract. It scans live computed styles for colors, fonts, type scale, spacing, radii, shadows, gradients and motion.
3. Choose the AI / DESIGN.md export, optionally naming your target stack.
4. Paste the result into DESIGN.md and commit it.

Because it reads computed styles rather than the stylesheet, the tokens are what the browser actually rendered — not what someone wrote in a CSS file two refactors ago. That distinction matters most on the sites where it is hardest to check by hand: minified CSS, atomic utilities, or class names like .css-1x9f2kq.

What to leave out

The most common failure is a DESIGN.md so long the agent skims it. It gets loaded on every UI task, so every line is a recurring cost. Cut:

• Component APIs. The agent can read your component files. It cannot read your intent.
• Every shade of every ramp. Five to eight named colors with usage counts beat a 60-swatch dump. Give it the generation rule for the ramp instead.
• Brand narrative. “Confident yet approachable” produces nothing an agent can act on.
• Anything hedged. “Generally prefer” reads as optional. Say “never” and “always”.

Target one screen of tokens plus one screen of rules — roughly 100 to 200 lines.

Keeping it from going stale

A DESIGN.md that no longer matches the app is worse than none — the agent confidently generates the old palette. Two habits keep it honest:

• Re-extract after any theme change. It takes a click; regenerate rather than hand-editing.
• Put the source URL and date in the front matter. The example above carries source: for exactly this reason — anyone reading the file can check it against the live site.

Frequently asked questions