DESIGN.md: The File That Gives Claude a Design Brain

A single Markdown file called DESIGN.md can stop Claude Code from making up its own visual decisions every time you prompt it. If you have been vibe-coding your way through a product and wondering why the AI keeps drifting off-brand, this is the fix worth knowing about.

The thesis here is simple: once you understand that Claude Code reads plain text files as context, you hold real power. You can encode your design system, your visual principles, your component rules, directly into the project, and Claude will use them as a source of truth. No engineering knowledge required.

The Two Files That Run Claude Code

Writer and designer Nick Babich, writing on UX Planet, frames it cleanly: CLAUDE.md tells Claude how to work on your product, and DESIGN.md tells Claude how your product should look and feel. Think of CLAUDE.md as the project brief and DESIGN.md as the brand and design system guide sitting next to it.

Both are just plain Markdown files, which means plain text that Claude can read. You write them once, keep them in your project folder, and Claude picks them up automatically every session. No copy-pasting your design rules into every single prompt.

The Five Ways to Use DESIGN.md

Babich lays out five distinct approaches, and the interesting part is that they are not interchangeable. The right one depends on what stage of building you are in.

1. Persistent reference via CLAUDE.md. You add a line in CLAUDE.md that tells Claude to treat DESIGN.md as the source of truth for all UI work. This is the right move when you already have a design system locked in and you want every single UI task to follow it consistently. Babich includes a real snippet: instruct Claude to follow existing tokens and component patterns, preserve the visual principles described in DESIGN.md, reuse patterns before introducing new ones, and flag any intentional deviations. That last instruction, flagging deviations, is smart. It keeps Claude honest rather than silently improvising.

2. Task-specific inline reference. Instead of making DESIGN.md global, you pull it in only for specific prompts. Useful when you are early in a project and your design rules are still evolving. You do not want Claude locked to a system that is half-finished.

3. Design system bootstrapping. You use DESIGN.md to describe a design system you want Claude to build for you, not one that already exists. You describe the visual direction, the tone, the principles, and Claude helps generate the system from there. This is the approach for designers at the very start of a project who want a structured foundation without hand-coding every token.

4. Audit and review mode. You point Claude at your existing UI and ask it to compare what it sees against what is in DESIGN.md. This turns Claude into a light-touch design reviewer, surfacing inconsistencies between your stated principles and what actually shipped. A useful sanity check before a handoff or a launch.

5. Incremental updates. You treat DESIGN.md as a living document and update it as the design system evolves. When you add a new component pattern or change a spacing token, you update the file and Claude picks up the new rules on the next session. This keeps the AI in sync with your design thinking over time rather than drifting further away from it.

How to Actually Start

If you have never used either file before, the lowest-friction entry point is this: create a DESIGN.md file in the root of your project folder. Write it the way you would write a design spec for a teammate. Describe your colour palette, your type scale, your spacing principles, your component naming, whatever you have decided. Then create a CLAUDE.md file and add a line telling Claude to use DESIGN.md as the source of truth for visual work.

You do not need to be exhaustive on day one. Even a short file with your core decisions, primary colours, font choices, spacing rhythm, is enough to meaningfully reduce Claude's tendency to freestyle. You can expand it as your system matures.

The persistent reference approach Babich describes is the most powerful once your system is stable, because it means you never have to re-explain your design language. Claude just knows.

What to Watch For

This approach has real limits. Claude reads what you write, so the quality of DESIGN.md is entirely dependent on how clearly you articulate your design decisions. Vague instructions produce vague results. If your file says "use a clean, modern aesthetic" Claude will interpret that however it wants. Specifics work better: name your tokens, describe your component patterns concretely, give examples.

There is also a maintenance cost. If your design evolves and DESIGN.md does not, Claude will faithfully follow outdated rules. The incremental update approach Babich describes is the answer to this, but it does require discipline.

None of this replaces a real design system or a real design review process. What it does is bring your design thinking into the AI's working context, so the gap between what you intended and what Claude builds gets meaningfully smaller. For a designer who is just starting to build, that gap is often the most frustrating part. This is a practical way to close it.