You've created the file.

You've named it DESIGN.md.

You've dropped it into the repository.

And the AI coding agent still generated a button with the wrong border radius.

So what went wrong?

Nothing is wrong with the file.

The problem is how you wrote it.

Because writing for an AI agent is not the same as writing for a developer.

And most designers don't know the difference.

Want more like this? Subscribe to get my free UX prompt guide for designing with AI and join the exploration.

When a developer reads your DESIGN.md, they bring context.

They've been in your Slack channels. They've sat in the design review. They know what you mean when you say "use the primary button for CTAs."

They fill the gaps with judgment.

An AI coding agent doesn't have gaps.

It has instructions. And it follows them literally.

If your DESIGN.md says "use brand colors consistently" the agent doesn't know what brand colors are. It doesn't know what consistently means. It will make a decision. And it won't be yours.

This is the core problem.

Vague language that works for humans fails for machines.

When an AI coding agent reads your DESIGN.md it's doing one thing.

Pattern matching.

It scans for structure, labels, and explicit values it can map to decisions.

It's looking for answers to these questions:

What should I use?

What should I never use?

What are the exact values?

What are the rules for when to use what?

If your file answers those four questions, clearly, specifically, with real values the agent follows it.

If it doesn't, the agent guesses.

And agents are confident guessers.

1. Token values not references

❌ Don't write: "Use the primary color for buttons."

✅ Write: "Primary button background: color-primary - #2563EB. Do not substitute."

The agent needs the actual value alongside the token name. Token names alone are meaningless without a resolved value unless you've also provided a token file the agent can read.

2. Explicit do and don't rules

❌ Don't write: "Buttons should feel consistent."

✅ Write: "Use the primary button for one CTA per page only. Use the secondary button for all supporting actions. Never use more than two button variants in a single view."

Rules without exceptions are rules the agent can follow.

3. Component anatomy not just appearance

❌ Don't write: "Cards have a shadow and rounded corners."

✅ Write: "Card component: - Background: color-surface — #FFFFFF — Border radius: radius-md — 8px — Shadow: elevation-1 — 0px 1px 3px rgba(0,0,0,0.1) — Padding: spacing-lg — 24px — Never use elevation-2 or above inside a card"

Anatomy gives the agent a complete picture. Appearance gives it half a guess.

4. Hierarchy and priority - what overrides what

❌ Don't write: "Follow the design system."

✅ Write: "Token values in this file take priority over any hardcoded values in the codebase. If a conflict exists, always defer to the token."

Agents need to know what wins when rules collide.

Here's what a real section looks like. And why it works.

Why this works:

The token name and resolved hex value appear together. The agent doesn't have to guess what color-primary resolves to.

The rules are specific and binary: one primary button per view. Not "use sparingly." Not "be consistent." One.

The "never do this" section is the most important part most designers leave out. Agents don't instinctively avoid things. You have to tell them what's off limits.

"Use your best judgment."

Never write this in a DESIGN.md.

An AI agent will use its judgment. And its judgment is trained on the entire internet, not your design system.

Anywhere you're tempted to write "use your best judgment" stop. That's a gap in your documentation. Fill it with a specific rule.

If you don't know the rule yet write a placeholder:

"Rule pending - default to spacing-md until updated."

A pending rule is better than no rule. The agent has something to follow.

You don't need a perfect DESIGN.md on day one.

Start with buttons.

Write the full token anatomy. Write the rules. Write what not to do.

Get one component documented properly and test it with your agent. See how it performs.

Then add typography. Then color. Then layout.

The goal isn't a complete document.

The goal is a document that gives your agent fewer reasons to guess.

Every section you write is one less decision the AI makes without you.

Stop writing DESIGN.md from scratch. I built the full template so you don't have to. Every section from this article: tokens, components, agent instructions pre-written and ready to drop into your repo.

👉 Download it free on Gumroad

Next in this series: Part 4: Scaling DESIGN.md When Your System Gets Complex.

Subscribe to Design x Machine for more on UX, intelligent systems, and the future of design practice.

👉 designxmachine.beehiiv.com