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

> Source: <https://dev.to/promptmaster/how-to-write-designmd-prose-that-ai-agents-actually-follow-3bn7>
> Published: 2026-06-28 07:55:48+00:00

**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.

```
## 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.

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.

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

``` php
## 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
- 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.

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.

**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.

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](https://promptmasterstore.gumroad.com/l/design-md-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](https://promptmasterstore.gumroad.com/l/design-md-guide)

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.