How to Use Design MD with Claude Code

Claude Code will happily invent a visual language if you let it — a random blue, rounded-lg on everything, shadow-md cards. The fix is not longer prompts. It is a DESIGN.md checked into the repository, referenced once, and treated as a contract. This guide covers how to use design md with Claude Code end to end: file placement, wiring it into CLAUDE.md, prompt patterns that actually hold, and the review loop that catches drift before it merges.

Where the file lives

Put DESIGN.md in the repository root, next to CLAUDE.md. Claude Code reads CLAUDE.md automatically at the start of every session, so the cheapest reliable wiring is a single reference line:

# CLAUDE.md

- UI work MUST follow the rules in DESIGN.md. Read it before writing any component.

That import-style reference means you never paste design rules into a prompt again. Every session — including ones you start weeks later — begins with the same visual constraints. If your DESIGN.md is large, keep the top of the file skimmable: tokens and hard rules first, prose rationale later. Claude Code respects specific, checkable rules ("never use font-weight 700", "interactive color is #0072F5 and nothing else") far better than mood words ("clean", "modern").

What a usable DESIGN.md contains

Whether you wrote it by hand or generated it from a URL with our generator, the file earns its place when it names decisions the agent would otherwise guess:

• Color roles, not just hexes. "#171717 is ink: headings and primary buttons" beats a bare palette.
• A type scale with weights. Sizes, line-heights, letter-spacing, and which weights are allowed.
• Component states. Default, hover, focus, disabled — for buttons, inputs, and cards at minimum.
• Do's and don'ts. The section agents follow most literally. "Don't introduce new colors" prevents ninety percent of drift.

If you need a starting point, browse the DESIGN.md library and adapt a system whose constraints resemble yours.

Prompt patterns that hold

Once the file is wired in, the question of how to use design md with Claude Code becomes a prompting question. Three patterns work consistently:

Scope one surface per task. "Build the settings page following DESIGN.md" beats "make the app match the design system". Small scopes let the model hold every constraint in attention while it writes.

Name the section you care about. For fiddly work, point at the rule: "Use the button states exactly as defined in DESIGN.md section 5." This collapses ambiguity to zero and costs one sentence.

Ask for a compliance pass, not a rewrite. After a feature lands: "Review src/components/checkout/* against DESIGN.md and list violations before fixing anything." Claude Code is notably better at auditing against a written spec than at remembering one it was never shown.

The review loop

Treat design compliance like type checking — a gate, not a hope. A loop that works in practice:

1. Implement with the scoped prompt above.
2. Ask Claude Code to self-audit the diff against DESIGN.md and output a violation list.
3. Fix violations in the same session while context is warm.
4. Screenshot the result and compare against the source site or design reference yourself. Agents catch token violations; humans catch composition problems.

Teams that run this loop stop reviewing hex codes in PRs entirely. The file is the reviewer.

Common failure modes

The file exists but is never read. If you skipped the CLAUDE.md reference, the agent only sees DESIGN.md when a prompt mentions it. Wire the reference.

Tokens without roles. A palette dump forces the model to guess which color is primary. Every token needs a job title.

Stale rules. After a redesign, an outdated DESIGN.md is worse than none — the agent will faithfully implement the old brand. Update the file in the same PR that changes the design.

Fighting utility classes. If the file says #FAFAFA but your Tailwind config has no matching token, the agent improvises. Mirror DESIGN.md values into your Tailwind theme so the vocabulary matches the toolchain.

A worked example

Say you want a pricing page for a product styled like Vercel. With the Vercel design md in your repo root and referenced from CLAUDE.md, the entire prompt is:

Build /pricing with three tiers. Follow DESIGN.md strictly: grayscale hierarchy, blue only on interactive elements, shadow-as-border cards, no font weight above 600.

The output lands close enough that review is about copy and layout, not color correction. That is the payoff of learning how to use design md with Claude Code properly: the design conversation happens once, in a file, instead of in every prompt.

Checklist

• DESIGN.md in repo root, referenced from CLAUDE.md
• Tokens have roles; components have states; don'ts are explicit
• One surface per prompt; name sections for fiddly work
• Self-audit pass after every UI diff
• File updated in the same PR as any redesign

Set this up once and every future session starts on-brand. Generate a grounded file for your own product with the DESIGN.md generator — paste a URL, get the contract.