DESIGN.md for Design in Claude Code - AI For Developers

AI For Developers

SubscribeSign in

DESIGN.md for Design in Claude Code<br>A plain-text file that stops your AI-generated UI from looking different every time you ask for it.

AI For Developers<br>Jul 26, 2026

13

Share

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.<br>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.<br>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.<br>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.<br>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.<br>It helps to think about the split like this:<br>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<br>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.<br>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.<br>The tokens were correct. The decisions were wrong.<br>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:<br>“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.<br>Setting it up in a Claude Code project

The setup itself is genuinely simple:<br>1. Put the file at your project root.<br>my-project/<br>├── DESIGN.md<br>├── CLAUDE.md<br>├── src/<br>└── ...<br>Root level matters — it means Claude Code can find it no matter which subdirectory it’s currently working in.<br>2. Reference it from CLAUDE.md, using the @ prefix.<br>Claude Code reads CLAUDE.md automatically at the start of every session, so that’s where you point it toward the design file:<br># CLAUDE.md

## Visual rules<br>Follow the rules defined in @DESIGN.md strictly for all UI generation.<br>Don't invent colors, fonts, or spacing outside the design system.<br>Read @DESIGN.md in full before generating any visual component.<br>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.<br>3. A good DESIGN.md generally covers:<br>Visual theme & atmosphere — the mood, density, overall philosophy

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

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

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

Layout principles — spacing scale, grid, how...