The Problem of Inconsistent AI-Generated UI
Developers who use Claude Code or other coding agents to build user interfaces often encounter a frustrating pattern. One request produces a settings screen that looks fine. An hour later, a pricing page request yields buttons in a different shade of indigo, altered border radius, and shadows that appear to come from a completely different application.
This issue is not specific to Claude Code. It stems from a context problem. Each fresh conversation starts with no memory of what the product should look like. The agent falls back on defaults. For most large language models today, those defaults mean rounded corners, a soft purple-to-blue gradient, and the generic SaaS aesthetic seen on countless landing pages.
DESIGN.md offers a small fix for this genuinely annoying problem. The file provides a way to maintain visual consistency across AI-generated UI components.
What DESIGN.md Actually Is
DESIGN.md is a plain markdown file placed in the project root. It describes the design system in words that an AI agent can read. The file covers colors and their purposes, type scale, spacing rules, how buttons and cards behave, what hover and disabled states look like, and an explicit list of things not to do.
The concept was popularized by Google's Stitch team but is not tied to that tool. It is simply a convention, similar to README.md or CLAUDE.md. Any coding agent that can read a text file, including Claude Code and Cursor, can consume it.
The division of responsibilities works like this. CLAUDE.md defines how to build the project, including commands, architecture, and conventions. DESIGN.md defines how the project should look and feel. CLAUDE.md is the operating manual. DESIGN.md is the design source of truth. They solve different problems. Most projects that struggle with visual consistency have a strong CLAUDE.md and no DESIGN.md at all. Claude knows how to structure React components but has no idea what the brand looks like.
Why Tokens Alone Do Not Fix the Problem
A DESIGN.md filled with hex codes and font names is a good start but not sufficient on its own. One developer who tried this approach for 30 days described dropping in a token-only file with colors, type scale, and spacing pulled directly from Figma. When asked to build a settings screen, Claude Code got the primary color right and the font right. But the agent still used the brand color as a background tint on an info banner, applied it to 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 is the real lesson. Tokens tell Claude what the colors are. They do not 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. Examples include statements 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," and "we don't use gradients anywhere in the product."
Without rules like that, Claude reads the file and decides on its own how closely to follow it. With them, the file stops being a reference and becomes an actual constraint.
Setting It Up in a Claude Code Project
The setup process is straightforward. First, place the file at the project root. The file structure should look like this:
Stay ahead of the AI curve
The most important updates, news, and content — delivered weekly.
No spam. Unsubscribe anytime.
my-project/ ├── DESIGN.md ├── CLAUDE.md ├── src/ └── ...
Root level placement matters because it means Claude Code can find the file no matter which subdirectory it is currently working in.
Second, reference DESIGN.md from CLAUDE.md using the @ prefix. Claude Code reads CLAUDE.md automatically at the start of every session, so that is where the pointer to the design file should go. The CLAUDE.md file should include sections like "Visual rules" with instructions to follow the rules defined in @DESIGN.md strictly for all UI generation, not to invent colors, fonts, or spacing outside the design system, and to read @DESIGN.md in full before generating any visual component.
The @ symbol is not decorative. It 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. They drop DESIGN.md into the repo, forget the @, and wonder why Claude still ignores it.
Third, a good DESIGN.md generally covers several areas. These include visual theme and atmosphere, including mood, density, and overall philosophy. Color palette and roles should include not just hex values but what each color is for. Typography rules should cover families and a full hierarchy from H1 down to caption text. Component styling should address buttons, cards, inputs, and navigation, including hover, disabled, and focus states. Layout principles should cover spacing scale, grid, and how whitespace is used. Depth and elevation should describe the shadow system and what sits above what. Do's and don'ts should provide guardrails in plain language. Responsive behavior should cover breakpoints, touch targets, and what collapses on mobile.
Fourth, test it with something small. Do not ask for a whole dashboard first. Ask for one button and one card. Check if the output actually matches. That is a much faster way to catch a vague or missing section than debugging four generated screens later.
A few things tend to go wrong once the setup is running. The agent may forget the rules mid-session on a long conversation. Simply repeating "follow the DESIGN.md" helps more than expected. Colors may come out partially right because the palette section is missing semantic names. Components may stay inconsistent because there is no explicit state list for hover, disabled, and focus. Almost all of these issues trace back to the file being too vague, not to Claude ignoring it.
Ready-Made DESIGN.md Files Available
Developers do not need to reverse-engineer their own design system into markdown by hand. They also do not need to be building a new design system to benefit from this approach. A community project called awesome-design-md exists as a library of pre-written DESIGN.md files extracted from real, well-known products. The collection includes files from Linear, Stripe, Vercel, Notion, Airbnb, Spotify, and dozens more. The files are organized by category, including AI platforms, dev tools, fintech, e-commerce, and even a retro web series with 90s-era sites for fun.
The pitch is straightforward. Copy a site's DESIGN.md into the project root. Tell the agent to follow it. The result is UI that is visually consistent with that product's language, without spending an afternoon hand-copying colors out of dev tools. Each entry follows the same structure described above, covering theme, palette, typography, components, layout, elevation, do's and don'ts, and responsive rules. Each entry also includes an HTML preview file so developers can eyeball the palette and type scale before committing to it.
This approach works well even for products with their own distinct brand. Pulling one of these files down and skimming it is a fast way to see what a well-structured DESIGN.md actually looks like, section by section, before writing a custom one.
The Short Version
DESIGN.md will not make Claude Code a designer. What it does is stop the agent from quietly reinventing the product's visual language every time a new chat opens. Put the file at the project root. Link it from CLAUDE.md with the @ prefix. Make sure it has explicit rules and not just tokens. Test it on something small before trusting it with something big.
Related on Neura Market
- AI Tools Directory - Browse a curated collection of AI development tools and platforms.
- Automation Marketplace - Find workflows and automation solutions for developer productivity.
- Developer Resources - Explore guides, templates, and community projects for AI-assisted development.