How to write a DESIGN.md file your AI coding agent actually follows

A step-by-step guide to writing a DESIGN.md: start from a feeling, turn it into exact tokens, write component recipes and a Do / Don't list, then test it with one screen.

Clinic Pearl design system preview, a calm healthcare DESIGN.md

Key takeaways

  • Start from one sentence about how the product should feel, then turn it into exact values.
  • Name colors by role (primary, muted-foreground), give every type role a size, and keep the radius scale small.
  • Finish with a Do / Don't list and test the file by generating one screen.

Writing a DESIGN.md is not like writing a brand book. The reader is an AI coding agent that will follow every line literally and fill every gap with defaults. So the job is simple to state: leave no gaps, and make every line specific. Here is how to write a DESIGN.md in seven steps, using the same structure as the DESIGN.md template.

Step 1: write the personality in one paragraph

Start with how the product should feel, in plain words: calm and clinical, loud and editorial, dark and technical. Then list three to six signature moves, the concrete things that make the look recognizable. Moves are better than adjectives because an agent can act on them.

DESIGN.md
## 1. Overview & personality

Calm, clinical and warm. White and pearl surfaces, one deep teal
for actions, generous type. Status colors inform, they never alarm.

**Signature moves**
- One teal action per view, everything else neutral
- 44px minimum touch targets, large body text
- Cards are solid with a hairline, never glass

Step 2: turn the feeling into color roles

Name colors by what they do, not what they look like. The roles that matter most:

  • background and foreground: the page and its text.
  • card, muted and muted-foreground: surfaces and secondary text.
  • primary and primary-foreground: the main action and the text on it.
  • accent, border, ring: highlights, dividers and focus.
  • destructive, success, warning: status, each with a foreground.

Give every role an exact value for light and dark mode, and check the contrast of each text pair. Agents that ask for "primary" stay on brand; agents that ask for "a nice blue" do not. If you want a wider gamut, the glossary has a page on OKLCH palettes.

Step 3: set every type role

Most generic AI UI is generic because of type: one font, one weight, default tracking. Pick a display font and a body font (and a mono if you show code or numbers), then give each role a size, mobile size, line height, weight and tracking: display, h1, h2, h3, body, small, label and mono. Exact numbers beat "large heading".

Step 4: spacing, radius, shadow and motion

Write these as short scales, not single values:

  • Spacing: a list like 4, 8, 12, 16, 24, 32, 48, 64, plus container width and section padding.
  • Radius: four or five named steps. A small named menu stops the agent from picking a new radius per card.
  • Shadow: two or three levels for light and dark.
  • Motion: durations (fast, base, slow) and easing curves, plus a rule for reduced motion.

Step 5: write component recipes

A recipe is the markup and CSS for one component, built from your tokens. Write recipes for the components agents build most often: button, input, card, badge, navigation, tabs, table, dialog and link. Include the states: hover, focus, disabled. Recipes work better than descriptions because the agent copies the structure instead of interpreting a sentence.

Step 6: describe imagery and icons

One or two lines each. What do photos look like? Which icon set and stroke width? This prevents the agent from mixing three icon styles in one screen.

Step 7: write the Do / Don't list

This is where your taste lives. Name the exact mistakes you have seen the agent make, and the rules a new designer on your team would get on day one.

DESIGN.md
## 9. Do / Don't

**Do**
- Use role names (primary, muted-foreground), never raw hex
- Keep one primary action per view

**Don't**
- Don't add a second accent color
- Don't use bold (700+) headings
- Don't put text on images without a scrim

Wire it in and test it

Save the file as DESIGN.md in your project root and point your tool at it: a line in CLAUDE.md for Claude Code, a rule in .cursor/rules/design.mdc for Cursor, Project Knowledge for Lovable. Then test it the simple way: ask for one screen you know well, like a pricing page, and compare it to the file. Every mismatch is a missing line. Add it and generate again.

Common mistakes when writing a DESIGN.md

  • Adjectives instead of values. "Modern and clean" means nothing to an agent. #1d1d1f on #ffffff does.
  • Hex values in prose that are not tokens. If the paragraph says one blue and the table says another, the agent picks one at random. The freedesignmd build fails when prose mentions a hex value or duration that is not a token, for exactly this reason.
  • Only light mode. Specify dark mode or the agent invents it.
  • Several accent colors. One accent, used for one prominent action per view, reads designed. Five read generated. More in why every AI landing page looks the same.

Frequently asked questions

Write the personality in one paragraph, then give exact values for color roles in light and dark mode, every type role, spacing, radius, shadow and motion. Add component recipes and a Do / Don't list, save it as DESIGN.md in your project root and test it by generating one screen.

Tokens (colors for light and dark, type roles, spacing, radius, shadow, motion), component recipes for common components, imagery and icon rules, a Do / Don't list and the tokens as CSS variables.

Usually not. Copy the closest of the 31 free systems on freedesignmd and rewrite the personality, the colors and the Do / Don't list. The structure is the hard part, and it is already done.

Ask your agent for one familiar screen, like a pricing page, and compare it to the file. Every value the agent got wrong points to a missing or vague line. Fix it and generate again.
Tammo Elsner, founder of freedesignmd

Written by Tammo Elsner

Founder of freedesignmd, a free DESIGN.md library for AI coding agents. About the project · LinkedIn

Keep reading. More on DESIGN.md.

Argent Machined design system preview, built from the DESIGN.md template

DESIGN.md

DESIGN.md template: the structure every design file for AI agents needs

The DESIGN.md template behind every file in the freedesignmd library: YAML tokens on top, then ten sections an AI coding agent can follow without guessing. Copy the outline or start from a finished system.

Nov 16, 2026 · 5 min read

Linear Orbit, one of the DESIGN.md examples: a dark hairline product workspace

DESIGN.md

31 DESIGN.md examples for AI coding agents, by style and industry

Every DESIGN.md example in the freedesignmd library, grouped by style and industry, with what each one is built for. Pick the closest one, copy it, change the brand color.

Nov 16, 2026 · 8 min read

free design.md library

DESIGN.md

What is a DESIGN.md file? The design spec AI coding agents read

A DESIGN.md file is one markdown document that tells AI coding agents how your product looks. What it is, why it works better than a Figma link, and how to wire it into Claude Code, Cursor and Lovable.

Nov 16, 2026 · 7 min read

Start with a free DESIGN.md. Or install a component.

Free design systems, React components and landing page templates for Claude Code, Cursor, Lovable and v0. No signup.