How to Write DESIGN.md Prose That AI Agents Actually Follow

#webdev #ai #tutorial #design

To write DESIGN.md prose agents follow, describe intent and rules, not just values. A token says a color is a hex; good prose says it is for the primary action only. Reasoning is what lets an agent generalise to cases you did not explicitly cover.

Weak vs strong prose

## Colors

# WEAK - restates the tokens:
Primary is #1A1C1E. Secondary is #6C7278.

# STRONG - explains intent:
High-contrast neutrals with one warm accent. Use the accent
only for the single most important action. Never decoratively.

The strong version gives the agent a rule it can apply to situations you never listed.

Why prose works on agents

LLMs read markdown with very high fidelity - most of their training is structured this way. That makes prose an ideal channel for design intent. The value tells the model what a color is; only prose tells it the rules.

Cover the canonical sections

Each section answers a question the agent would otherwise guess at:

## Overview        -> the personality
## Colors          -> roles and rules
## Typography      -> the job of each style
## Layout          -> grid and spacing
## Do's and Don'ts -> hard guardrails

Do's and Don'ts is where the value is

## Do's and Don'ts
- Do use the accent for one primary action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast (4.5:1 for normal text)
- Don't use more than two font weights on a screen

Each line removes a whole category of off-brand output.

How much is enough?

A good test: would the prose let a designer who had never seen your product apply your system correctly? Write what prevents a mistake, and stop there.

FAQ

Descriptive color names? Yes - tie them to the token name so the agent can map rationale onto values.
Most important section? Do's and Don'ts - it directly prevents agent mistakes.

Bottom line

Tokens are easy; the rationale is the work. Spend your time on the prose that turns values into your identity.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents

What is the one design rule you wish your agent would stop breaking? Drop it below - it probably belongs in your Do's and Don'ts.