How to give Claude Code a real design system, with a single markdown file

I use Claude Code daily and the first thing I noticed, the very first week, was that Claude has good taste in code and weak taste in UI. The functions it writes are clean, the architecture it suggests is reasonable, the test coverage it adds is sensible. The components it builds, on the other hand, all look the same. Inter at fourteen, soft gray cards, a button with rounded corners and a faint blue background. Every project.

This is not Claude's fault. Claude has no opinion about your brand because you never gave it one. The fix is small. You write a CLAUDE.md, you write a DESIGN.md, you commit them both, and you never have to think about it again. This post walks through that exact setup, in the way I wish someone had shown me when I started.

Why Claude Code needs a written design system

Claude Code reads your repository the way a new contractor would. It opens the README, scans the package.json, looks at a few existing components if there are any, and then writes the next file based on patterns it can see. If there is no design pattern in the repo, Claude defaults to whatever it thinks a modern web app should look like, which is exactly the thing you do not want.

A CLAUDE.md is the file Claude reads first on every session. It is the place where you tell Claude what is special about this codebase. The most important thing you can put in there is one line that points at your DESIGN.md, because that single line keeps every UI decision Claude makes anchored to a real source of truth, instead of drifting toward the average.

The two file setup

You only need two files. CLAUDE.md and DESIGN.md, both at the root of the project. CLAUDE.md is short, often under twenty lines, and it tells Claude how to work in this repo. DESIGN.md is the actual design system, with tokens for colors, fonts, radii, shadows, and buttons.

My CLAUDE.md is almost the same on every project. It says, work in TypeScript, use the existing component library, prefer composition over inheritance, and reference DESIGN.md for all styling decisions. That last line is the one that matters for UI.

The DESIGN.md is the longer file but it is still small. Three colors, two or three fonts, a radius scale, a button section, a one paragraph note about how the app should feel. You can see the exact format on any system page in the directory, since each system here is itself a working DESIGN.md you can copy into your project.

What changes after Claude reads it

The difference is hard to overstate until you see it. Without DESIGN.md, you ask Claude for a pricing card and you get a soft white card with rounded corners and a blue button. Without DESIGN.md, you ask for a settings page and you get the same card pattern, repeated four times. Without DESIGN.md, you ask for a hero and you get a generic gradient behind a 64 pixel headline in Inter.

With DESIGN.md, you ask for the same things and Claude reaches for your tokens. The pricing card uses your surface color, your hairline border, your accent for the call to action. The settings page uses your radius scale, not a default. The hero uses your display font, not Inter. None of this requires re prompting. It just happens, on the first try, because the file was in context.

Common mistakes when wiring Claude to a design system

The first mistake is putting the design tokens in CLAUDE.md instead of in their own file. CLAUDE.md is for general repo behavior, not for visual specifics. If you mix them, the file gets long, Claude skims, and the design tokens get less attention. Keep them separate.

The second mistake is writing the DESIGN.md as a wishlist instead of as a contract. Lines like, the app should feel modern and clean, are useless. Lines like, primary background is oklch 0.99 0.005 240, hairline borders are 1 pixel oklch 0.88 0.01 240, are usable. Be specific where it matters and prose where it does not.

The third mistake is not committing the files. If DESIGN.md only exists on your machine, your collaborators get drift, your CI runs get drift, and any new Claude session that does not have your local file context will start guessing again. Commit it the same way you commit your tsconfig.

Picking a system to start from

If you do not want to write a DESIGN.md from scratch, you do not have to. Pick one from the directory that is close to the feeling you want, copy the file into your project, change the brand color, and you are done. That is the fastest way to get Claude generating consistent UI in a new project, often within ten minutes of opening the editor.

For SaaS dashboards, I tend to start from a clean technical system and adjust the accent color to the brand. For marketing sites, an editorial system gives the prose room to breathe. For internal tools, a denser admin oriented system saves a lot of layout decisions.

What I would do differently if I was starting today

I would set up the two files before I wrote a single component. The cost of doing it on day one is twenty minutes. The cost of doing it later, after a hundred components have already been generated in the wrong style, is a refactor. Future you will be glad past you wrote the DESIGN.md before the first card.

I would also not over engineer the file. Three colors, two fonts, four button states, a radius scale, a one paragraph mood note. Anything more, on a new project, is premature. You can always extend the file as the product matures, but starting small keeps Claude from second guessing the constraints.