DESIGN.md for Design in Claude Code

A plain-text file that stops your AI-generated UI from looking different every time you ask for it.

If you’ve used Claude Code (or any coding agent) to build UI, you’ve probably seen this pattern: you ask for a settings screen, it looks fine. You ask for a pricing page an hour later, and suddenly the buttons are a different shade of indigo, the border radius changed, and the shadows look like they came from a different app entirely.

This isn’t really a Claude Code problem. It’s a context problem. Every time you start a fresh conversation, the agent has no memory of what your product is supposed to look like. So it falls back on defaults — which, for most LLMs right now, means rounded corners, a soft purple-to-blue gradient, and that same generic SaaS aesthetic you’ve seen on a thousand landing pages.

DESIGN.md is a small fix for a genuinely annoying problem. Here’s what it is, how to actually set it up, and where to grab ready-made ones instead of writing your own from scratch.

What DESIGN.md actually is

DESIGN.md is just a plain markdown file that lives in your project root and describes your design system in words an AI agent can read: colors and what each one is for, type scale, spacing rules, how buttons and cards behave, what states like hover and disabled look like, and — often the most useful part — an explicit list of things not to do.

The idea was popularized by Google’s Stitch team, but it’s not tied to Stitch. It’s just a convention, the same way README.md or CLAUDE.md are conventions. Any coding agent that can read a text file — Claude Code, Cursor, whatever you use — can consume it.

It helps to think about the split like this:

File Who reads it What it defines CLAUDE.md Claude Code How to build the project (commands, architecture, conventions) DESIGN.md Claude Code / design agents How the project should look and feel

CLAUDE.md is your operating manual. DESIGN.md is your design source of truth. They solve different problems, and honestly, most projects that struggle with visual consistency have a great CLAUDE.md and no DESIGN.md at all. Claude knows exactly how to structure your React components — it just has no idea what your brand looks like.

Why tokens alone don’t fix it

Here’s the part that trips people up. A DESIGN.md full of hex codes and font names is a good start, but it’s not enough on its own. One developer who tried this for 30 days described dropping in a token-only file — colors, type scale, spacing, all pulled straight from Figma — and asking Claude Code to build a settings screen. The primary color was right. The font was right. And the agent still used the brand color as a background tint on an info banner, slapped it on a decorative divider, and gave every card the same soft box-shadow the product had never actually used.

The tokens were correct. The decisions were wrong.

That’s the real lesson: tokens tell Claude what your colors are. They don’t tell it when to use them, or when not to. A genuinely useful DESIGN.md needs a “do’s and don’ts” section, not just a palette. Something like:

• “brand-primary is for CTAs and links only — never backgrounds, never dividers”

• “cards use a 1px border, not a shadow, unless the card is interactive”

• “we don’t use gradients anywhere in the product”

Without rules like that, Claude reads the file and then decides, on its own, how closely to follow it. With them, the file stops being a reference and starts being an actual constraint.

Setting it up in a Claude Code project

The setup itself is genuinely simple:

1. Put the file at your project root.

my-project/
├── DESIGN.md
├── CLAUDE.md
├── src/
└── ...

Root level matters — it means Claude Code can find it no matter which subdirectory it’s currently working in.

2. Reference it from CLAUDE.md, using the @ prefix.

Claude Code reads CLAUDE.md automatically at the start of every session, so that’s where you point it toward the design file:

# CLAUDE.md

## Visual rules
Follow the rules defined in @DESIGN.md strictly for all UI generation.
Don't invent colors, fonts, or spacing outside the design system.
Read @DESIGN.md in full before generating any visual component.

The @ isn’t decorative — it’s what tells Claude Code to actually pull in the referenced file’s contents, not just note that it exists. This is the single most common mistake people make: dropping DESIGN.md into the repo, forgetting the @, and wondering why Claude still ignores it.

3. A good DESIGN.md generally covers:

1. Visual theme & atmosphere — the mood, density, overall philosophy

2. Color palette & roles — not just hex values, but what each color is for

3. Typography rules — families, and a full hierarchy from H1 down to caption text

4. Component styling — buttons, cards, inputs, nav, including hover/disabled/focus states

5. Layout principles — spacing scale, grid, how whitespace is used

6. Depth & elevation — shadow system, what sits above what

7. Do’s and don’ts — the guardrails, in plain language

8. Responsive behavior — breakpoints, touch targets, what collapses on mobile

4. Test it with something small. Don’t ask for a whole dashboard first. Ask for one button and one card, and see if the output actually matches. That’s a much faster way to catch a vague or missing section than debugging four generated screens later.

A few things that tend to go wrong once it’s running: the agent forgets the rules mid-session on a long conversation (just re-say “follow the DESIGN.md” — it helps more than you’d expect), colors come out “partially right” because the palette section is missing semantic names, or components stay inconsistent because there’s no explicit state list for hover/disabled/focus. Almost all of it traces back to the file being too vague, not to Claude ignoring it.

If you want a deeper walkthrough of doing this well inside Claude’s own design tooling specifically, we covered that in a separate issue.

You don’t have to write one from scratch

This is the part I actually find most useful: you don’t need to reverse-engineer your own design system into markdown by hand, and you don’t need to be building a new design system to benefit from this. There’s a community project, awesome-design-md, that’s essentially a library of pre-written DESIGN.md files extracted from real, well-known products — Linear, Stripe, Vercel, Notion, Airbnb, Spotify, and dozens more, organized by category (AI platforms, dev tools, fintech, e-commerce, even a “retro web” series with 90s-era sites for fun).

The pitch is straightforward: copy a site’s DESIGN.md into your project root, tell your agent to follow it, and you get UI that’s visually consistent with that product’s language — without hand-copying colors out of dev tools for an afternoon. Each entry follows the same structure described above (theme, palette, typography, components, layout, elevation, do’s/don’ts, responsive rules), plus an HTML preview file so you can eyeball the palette and type scale before committing to it.

It’s a good move even if your product has its own distinct brand — pulling one of these down and skimming it is a fast way to see what a well-structured DESIGN.md actually looks like, section by section, before you write your own.

The short version

DESIGN.md won’t make Claude Code a designer. What it does is stop it from quietly reinventing your product’s visual language every time you open a new chat. Put the file at your project root, link it from CLAUDE.md with the @ prefix, make sure it has explicit rules and not just tokens, and test it on something small before you trust it with something big.