What is DESIGN.md and how to set it up

What is a DESIGN.md file?

It’s a brand constitution that lives at the root of your project: palette hex codes, font families and weights, the spacing scale, tone, and the things you never do. Instead of holding your design language in your head, you write it down once where the agent can read it on every task. Think of it as the source of truth a new designer would be handed on day one.

Mechanically it is just a Markdown file, plain text, sitting in your repository where a coding agent like Claude Code reads it alongside the source. That is the whole trick: a model treats project files as context, so a design language written into a file the agent already reads becomes part of how it works rather than something you re-explain. It is the visual sibling of the README or CLAUDE.md file teams use to hand an agent the rules of a codebase, except this one carries the look instead of the build commands.

Why give an AI explicit design rules?

Without rules, the model guesses your look fresh on every generation, so the output drifts: slightly different blues, random spacing, an off button radius each time. Explicit rules make the design language a constant instead of a request you have to repeat. Decisions stop being remade and start being followed.

The drift is the real cost, and it compounds. A model is non-deterministic by nature, so two prompts that say “on brand” produce two subtly different brands, and across a dozen screens those differences read as a stitched-together product. Pinning the rules down converts a request you keep making into a decision the agent inherits, which is how a one-person team gets the consistency that normally needs a design lead policing every screen. You are not making the model smarter; you are removing its room to guess.

What belongs in a DESIGN.md?

The concrete, repeatable stuff: exact colors, typography rules, the spacing scale, component patterns like button and card styles, and an anti-pattern list of what to avoid. Be specific; “#141413 for text, never pure black” beats “use dark text.” The more decisions you lock down, the less the model improvises.

Specificity is the difference between a file that works and one that decorates the repo. Give the exact hex values with their roles, the font families with weights and the type scale, the spacing steps as real numbers, and named component patterns the agent can reuse instead of reinventing. The anti-pattern list earns its place by closing the gaps you cannot enumerate positively, “no pure black, no drop shadows, no more than two fonts”, because telling the model what to avoid is often clearer than describing everything it may do. Keep it short enough to stay true; a DESIGN.md that lies because nobody updated it is worse than none.

How does it keep output on-brand?

The model reads the file at the start of every design task, so the rules are bound to the project rather than to whatever you happened to type in the prompt. One person updates the palette in the file and every future generation inherits it automatically. The brand stays consistent because it lives in the codebase, not in anyone’s memory.

This is the same principle that makes a design token system work, with the rules as the single source of truth, except expressed in language the agent reads. Because the file lives next to the code, it travels with the project: a teammate, a future you, or a fresh agent session all start from the same constitution instead of re-deriving the brand from a half-remembered prompt. Update the file when the brand changes and the change propagates everywhere on its own.

A DESIGN.md is most useful once you know what to put in it, which means the upstream work of choosing a defensible AI colour palette and the discipline of AI design for non-designers. The rules it encodes are the same ones that keep output from collapsing into generic AI slop. All of it ships as the Design Intelligence kit, inside the broader Claude Design system guide.