The File That Makes Claude Code Generate UI Inside Your Design System (Not Generic Tailwind)

TL;DR: A DESIGN.md in your repo root tells Claude Code (and any code agent) your color palette, typography, spacing, and component constraints — with intent and boundaries, not just values — so generated UI stays inside your design system.

What you'll be able to do after this:

• Make Claude Code generate components that use your actual tokens, not Tailwind defaults
• Write token constraints that prevent the agent from misusing values (e.g., "primary blue is for CTAs only — never backgrounds, never decorative")
• Version-control your design system as a first-class repo artifact any compatible agent can load

The key insight: value + intent + boundary

The difference between a file Claude can read and a file Claude can follow is whether each token says what it's for and what it's not for.

Instead of:

primary: #3b82f6

Write:

primary: #3b82f6 — CTAs and active states only. Never used as a background, never decorative.

A minimal DESIGN.md that works

# Design System

## Product
[2–3 sentences: what the product does, who uses it, its core UI purpose.]

## Colors
- primary: #3b82f6 — CTAs and active link text. Never as a background.
- surface: rgba(255,255,255,0.06) — Card backgrounds only. Always paired with backdrop-blur.
- text-primary: #f1f5f9 — Body copy. Never on anything lighter than surface.

## Typography
- h1: 2rem, weight 700, leading-tight
- body: 1rem, weight 400, leading-relaxed
- caption: 0.75rem — metadata and labels only. Never body text.

## Spacing
Base unit: 4px. Use only multiples: 8, 16, 24, 32, 48px.

## Components
- Buttons: rounded-md bg-primary px-4 py-2. Primary action only, one per viewport section.
- Cards: rounded-xl bg-surface backdrop-blur-sm border-white/10 p-6.

## Don'ts
- Never use Tailwind's default blue — always #3b82f6.
- Never hardcode a hex that isn't in this file.
- Never add margin to a Card — let the layout own spacing.

Wiring it into Claude Code

Add one line to your CLAUDE.md:

When generating or editing UI components, read DESIGN.md and apply every token, constraint, and Don't rule from it.

Claude Code loads CLAUDE.md at session start. When it writes UI, it reads DESIGN.md and your tokens flow into every generated component without re-explaining them per prompt.

Limits to know

DESIGN.md requires maintenance — when your system evolves, update the file, or the agent will confidently apply stale tokens. More importantly: if you ask Claude to generate DESIGN.md from a Figma export without guidance, it extracts token values accurately but fabricates the intent and boundary constraints. Those require a designer's actual decisions. The model infers plausible-sounding rules; they are not your rules. Write the product brief and the don'ts yourself.

Sources: Writing a DESIGN.md file Claude can actually use — Process to Pixels · The DESIGN.md Workflow — Design Systems Collective · Google Stitch open-sources DESIGN.md spec (Apache 2.0) — Pasquale Pillitteri