How to Use DESIGN.md with Claude Code

To use DESIGN.md with Claude Code, commit the spec to your repo root, open Claude Code in that directory, and reference the file path in every UI prompt before asking for multi-file edits. Claude Code reads the filesystem directly — a stable DESIGN.md beats pasting specs inline, and section-scoped requests prevent full-repo slop.

Claude Code excels at long-context refactors. DESIGN.md is how you aim that context at taste, not defaults.

Why DESIGN.md matters for Claude Code

Claude Code operates terminal-first across your whole project. Without a spec:

• It picks fonts and colors from training-data medians
• Wide edits touch unrelated files
• Each new session renegotiates spacing and hero layout

A committed DESIGN.md is the single source of truth Claude can read at session start.

See the full spec format in agent-ready DESIGN.md guide.

Where to put DESIGN.md

Location	When to use
./DESIGN.md	Default — one product per repo
./docs/DESIGN.md	Larger monorepos; reference path in prompts
./designs/<slug>/DESIGN.md	Multiple white-label sites in one repo

Keep under ~200 lines. Lead with anti-patterns so Claude sees constraints first.

Session start workflow

1. cd into project root
2. Start Claude Code (claude in terminal)
3. First message:

Read DESIGN.md at repo root. Confirm tokens, layout rules, and anti-patterns before any UI work.
Stack: Next.js App Router, Tailwind, shadcn/ui.
Do not edit files until I assign a section.

4. Wait for acknowledgment — catches spec parse errors early

Referencing DESIGN.md in prompts

Always include the path:

Implement components/landing/hero.tsx per DESIGN.md.
Headline: [yours]. Split layout 55/45. Use components/ui/button.tsx only.
Do not deviate from DESIGN.md colors. No new font imports.
Stop after hero.tsx — show diff summary.

For reads across files:

Read DESIGN.md and app/page.tsx. Add Features section as new file components/landing/features.tsx.
Bento grid per DESIGN.md layout section. Do not modify hero.tsx.

Claude Code uses file tools — explicit paths reduce drift.

Section-scoped generation (critical)

Claude Code can edit many files in one turn. Constrain scope for landing pages and dashboards:

Section	Prompt scope
Hero	hero.tsx + page.tsx import only
Features	features.tsx only
Pricing	pricing.tsx only
Settings	app/settings/** only

Full-page requests produce inconsistent spacing between sections.

Pairing gallery templates with Claude Code

1. Export DESIGN.md + prompt from Agent's Design
2. Save as ./DESIGN.md and ./PROMPT.md (optional)
3. Session start: Read DESIGN.md and PROMPT.md
4. Implement section 1 (hero) only per PROMPT.md

Gallery specs are pre-decomposed — faster than writing from scratch.

Claude Code vs Cursor for DESIGN.md

Aspect	Claude Code	Cursor
Spec access	Reads files via terminal	@DESIGN.md in chat
Best for	Large refactors, many files	IDE-integrated review
Context	Long session in repo	Per-composer turn
Visual review	You run dev server separately	Browser + screenshot in chat

Same DESIGN.md works in both. Standardize on one spec per project.

Multi-file patterns that work

Token migration:

Update globals.css and tailwind.config per DESIGN.md token section.
Then update components/ui/button.tsx and card.tsx to use CSS variables.
Do not change page content yet.

New route from spec:

Create app/pricing/page.tsx per DESIGN.md page map /pricing section.
Reuse components/ui/*. No new primitives.

Slop recovery:

Hero violates DESIGN.md anti-patterns (gradient, three equal cards).
Rewrite hero.tsx only to match spec. Keep copy unchanged.

Common mistakes

Mistake	Fix
Pasting full spec every message	Commit DESIGN.md; reference path
No anti-patterns section	Add forbidden patterns at top of spec
"Make it look better"	Point to specific DESIGN.md sections
Allowing repo-wide style edits	Scope to one directory per prompt
Skipping dev server review	Run bun dev; verify between sections

DESIGN.md maintenance

Update the spec when you intentionally change brand direction — not after every tweak. Version in git. If Claude drifts, restate:

DESIGN.md overrides all prior styling decisions in this thread.

For Claude-specific UI workflows, see design better UI with Claude Code.

Checklist: DESIGN.md + Claude Code ready

• DESIGN.md at repo root with tokens and anti-patterns
• Component library installed (components/ui/)
• Section files created before content generation
• Session starts with read DESIGN.md instruction
• Each prompt names allowed files
• Dev server running for visual review
• Anti-slop checklist run before merge

Start with a real spec

Claude Code without DESIGN.md is fast generic UI. Claude Code with DESIGN.md is a craft workflow.

Copy a spec from Agent's Design or use the skeleton in our DESIGN.md guide, commit it, and build one section at a time. The terminal agent already has repo access — give it constraints.