Your design.md Is Missing These 10 Lines

Your AI agent already knows how to run your tests. It has no idea your product uses 4px spacing increments. That gap — between what the agent knows about your code and what it knows about your design — is quietly wrecking the consistency of everything you're building.

This is the core insight behind the idea of a design.md file: a plain-text context document that lives in your repo alongside CLAUDE.md (or whatever equivalent file you're using to brief your AI agent on the project), but speaks entirely in design language instead of engineering language.

What's a CLAUDE.md, and why does design need its own version?

If you're new to vibe-coding with tools like Claude, a CLAUDE.md is a simple text file you drop into your project folder. The AI reads it at the start of every session and uses it to understand your project's ground rules — which commands to run, which files not to touch, how the codebase is structured. Think of it as a briefing document for a very capable new contractor who forgets everything between sessions.

The problem: that briefing document is almost always written by developers, for developers. It tells the agent how things work, not how things look or feel or should behave from a user's perspective. So the agent will dutifully respect your folder structure while inventing a new shade of blue for your primary button, or centering a form that every other form in your product left-aligns.

A design.md fills that gap. It's the same format — just a plain text or Markdown file — but it's yours to write as a designer.

What actually goes in it

The article's central example is instructive: an AI agent asked to redesign a settings page did everything technically correct and nothing contextually right. The spacing was fine. The components existed. But it ignored the toggle pattern used throughout the rest of the product, and picked colors from outside the established system. Nothing was broken. Everything was slightly off — like a stranger rearranged your furniture.

That experience points to exactly the kinds of things a design.md should capture:

• Spacing rules. If your product is built on 4px increments, say so. If you never use odd numbers, say that too.
• Color intent. Not just hex codes — why things are the colors they are. Destructive actions are always red. Primary actions use this one specific blue, not a close cousin.
• Pattern decisions. We don't use modals for anything longer than two fields. Forms are left-aligned. Confirmation dialogs always follow this structure.
• Things we stopped doing. This is underrated. If you abandoned a pattern six months ago, the agent doesn't know that — and will happily resurrect it.
• Tone and copy style. If your UI copy is direct and verb-first ("Save changes," not "Would you like to save your changes?"), write that down.

None of this is technical. It's design knowledge your team already carries around in their heads — and almost never writes down anywhere an AI can read it.

How to actually build this file

Start small. Open a text file, name it design.md, and drop it in the root of your project next to CLAUDE.md. Then think about the last time an AI (or a new team member) got something visually or behaviourally wrong. What would you have had to say to prevent that mistake?

Write that down. That's your first entry.

Over time, the file grows naturally from the corrections you find yourself making repeatedly. If you've told the agent three times that destructive actions need a confirmation step, that's a rule that belongs in design.md. If you've re-explained your spacing system in every new session, write it down once and reference it forever.

The file doesn't need to be long or beautifully formatted. A bulleted list of design decisions, written the way you'd explain them to a smart intern on their first day, is exactly right. The agent isn't looking for design theory — it's looking for specific, actionable constraints.

The practical limit worth naming

A design.md isn't a design system. It won't replace Figma tokens, a component library, or the institutional knowledge that comes from years working on a product. And an AI agent working only from a text file will still make judgment calls — some of which will be wrong.

What the file does do is dramatically narrow the gap between what you meant and what the agent built. It turns "technically correct but slightly off" into "closer to what we'd actually ship." That's not a small thing when you're iterating fast.

If you're building with Claude or any other AI agent right now and you don't have a design.md, you're essentially briefing a contractor on the plumbing but not the interior design. The house will stand. It just won't feel like yours.

Start the file today. Ten lines is enough to begin.