· 6 min read

Writing DESIGN.md Files That AI Agents Actually Follow

DESIGN.md is becoming the standard convention for giving AI coding agents visual design context. But not all DESIGN.md files are equally effective. The difference between a file that works and one that gets ignored comes down to structure, specificity, and formatting.

Why some DESIGN.md files fail

The most common mistake is writing DESIGN.md like a design brief for humans. AI agents process information differently. They are literal, they need explicit instructions, and they perform best with structured, categorical information.

Vague language like "use a modern, clean aesthetic" gives the agent no actionable rules. What is modern? What is clean? The agent averages across its training data and produces something generic — exactly what you are trying to avoid.

The six-section structure

An effective DESIGN.md follows a consistent six-section format. Each section serves a specific purpose and is clearly labeled with a heading that the agent can find and parse.

1. Design philosophy (2-3 sentences)

A brief statement of visual intent. This helps the agent understand the overall direction before diving into specifics. 

This design system is minimal and dark-themed with purple accent colors.
The visual language emphasizes clarity, ample whitespace, and subtle
elevation cues. Avoid decorative elements — every visual choice should
serve readability and interaction clarity.

2. Color system (by role, not name)

List colors by their functional role, not their color name. The agent needs to know when to use each color, not what it is called. 

Colors:
- Primary (interactive elements, links, buttons): #6c5ce7
- Surface (main background): #0c0e14
- Surface raised (cards, elevated areas): #1a1d27
- Text primary: #e6e8ee
- Text secondary: #8b8fa3
- Border: #2a2d3a
- Success: #22c55e
- Warning: #f59e0b
- Error: #ef4444

3. Typography hierarchy (size, weight, line height)

Define each typography level explicitly. Include font family, size, weight, line height, and letter spacing. 

Typography:
- Font family (body): "Plus Jakarta Sans", system-ui, sans-serif
- Font family (mono): "JetBrains Mono", monospace
- H1: 40px / 800 / 1.2 / -0.02em letter-spacing
- H2: 28px / 700 / 1.3
- H3: 22px / 700 / 1.4
- Body: 16px / 400 / 1.6
- Small: 14px / 400 / 1.5

4. Spacing and layout (exact values)

Give the agent a spacing scale with exact pixel values. Include section-level and component-level spacing. 

Spacing:
- Base unit: 8px
- XS: 4px (minimal spacing between tight elements)
- SM: 8px (between related elements)
- MD: 16px (between elements in a section)
- LG: 24px (section padding, card padding)
- XL: 48px (between sections)
- 2XL: 80px (between major page sections)
- Max content width: 1200px

5. Component rules (when and how)

Define patterns for common components. Include visual rules and behavior descriptions. 

Components:
- Buttons: 8px radius, 1.5px border, padding 10px 20px
- Cards: 12px radius, surface raised background, subtle shadow, padding 24px
- Inputs: 8px radius, 1px border, 12px padding
- Modals: 16px radius, surface background, 24px padding, centered

6. Negative constraints (what NOT to do)

Explicitly tell the agent what to avoid. This is surprisingly effective because AI models are trained to follow instructions, including prohibitions. 

Constraints:
- Do NOT use decorative fonts
- Do NOT use gradients
- Do NOT use bright saturated colors for backgrounds
- Do NOT add shadows to buttons (flat style)
- Do NOT use border-radius larger than 16px
- Keep density low — generous whitespace is required

Formatting tips for AI readability

How DesignSaver generates DESIGN.md

DesignSaver generates DESIGN.md automatically from any website URL. The output follows this six-section structure, with extracted values populated from the reference site's actual CSS. You get a complete, AI-optimized DESIGN.md in seconds — ready to use in any AI coding workflow.

Join the DesignSaver beta

Related articles