Agent-Ready DESIGN.md Specs: What to Include

An agent-ready DESIGN.md is a short, strict spec your coding agent reads before touching UI: brand intent, design tokens, component rules, section patterns, and explicit anti-patterns. Give agents constraints instead of adjectives like "modern" or "clean," and you get consistent output across Cursor, Claude Code, Codex, and v0.

Why agents need a DESIGN.md

LLMs default to the median UI on the internet. Without a spec, every prompt renegotiates font sizes, spacing, and hero layout from scratch. A DESIGN.md is the handoff document a human designer would write — except it must be machine-actionable: concrete values, file paths, and pass/fail rules.

Think of it as config for taste.

Where to put it

• Repo root: DESIGN.md — visible to every agent session
• Per-template: designs/<slug>/DESIGN.md when you ship multiple products from one monorepo
• Reference in prompts: "Read DESIGN.md first. Do not deviate without asking."

Keep it under ~200 lines. Agents skim; novels get ignored.

Recommended structure

Copy this skeleton and fill in values for your project.

# Design spec — [Product name]

## Design read
One line: page kind, audience, vibe, stack.

## Anti-patterns (do not use)
- ...

## Tokens
### Color
### Typography
### Spacing
### Radius & shadow

## Layout
### Grid & breakpoints
### Section rhythm

## Components
### Buttons
### Cards
### Forms

## Page map
### /
### /pricing

## Motion
## Content voice
## File conventions

Below is what each section should contain.

1. Design read (one line)

Force the agent to lock context before coding.

Example:

B2B SaaS landing for engineering leads, Linear-minimal language, Next.js + Tailwind + HeroUI, light mode only.

This mirrors how senior designers brief the room. Ambiguous briefs produce slop.

2. Anti-patterns (non-negotiables)

List what to avoid first. Agents respond better to forbidden patterns than vague "be unique."

Examples:

• No purple/pink gradients on dark mesh backgrounds
• No three equal feature cards in a row without layout variation
• No Inter unless explicitly specified
• No "Unlock the power of AI" headline templates
• No lorem ipsum company names in logo bars
• No infinite CSS animations on decorative elements

Be specific to your brand. If you are building a playful consumer app, ban "corporate blue gradient" instead.

3. Design tokens

Agents need exact values, not "slightly rounded corners."

Color

- background: #FAFAF8
- foreground: #111110
- muted: #6B6B67
- accent: #E85D2C (CTAs and links only)
- border: #E8E8E4
- surface (cards): #FFFFFF

Include contrast notes: "Body text on background must pass WCAG AA."

Typography

- font-sans: "Geist Sans", system-ui
- font-mono: "Geist Mono"
- scale: 14 / 16 / 20 / 28 / 40 / 56 (px)
- body: 16px, line-height 1.6, max-width 65ch
- headings: font-semibold, tracking-tight

Spacing

Use a named scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. Tell agents which to use for section padding vs. card padding.

Radius and shadow

- radius-sm: 6px (inputs)
- radius-md: 10px (cards)
- shadow: 0 1px 2px rgba(0,0,0,0.06) only — no layered glow

4. Layout rules

Grid and breakpoints

- max content width: 1120px
- page padding: px-4 md:px-6
- section vertical padding: py-16 md:py-24
- marketing columns: 12-col grid, gap-6 md:gap-8

Section rhythm

Define the default page story so agents do not invent random order:

1. Hero (headline, subhead, primary CTA, product visual)
2. Logo bar OR single proof point
3. Features (bento OR two alternating rows — not three identical cards)
4. Deep dive (screenshot + bullets)
5. Pricing or final CTA
6. Footer

5. Component rules

Point to implementation paths.

### Buttons
- Primary: HeroUI Button, variant solid, accent background
- Secondary: variant bordered
- One primary CTA per viewport

### Cards
- Padding p-6, border border-default, no gradient fills

### Forms
- Label above input, error text text-danger text-sm

Variant budget: "Use at most 2 button variants on marketing pages." Agents otherwise render a component showcase.

6. Page map

Per-route notes prevent agents from duplicating heroes or breaking nav.

### /
- Hero: split layout, H1 max 8 words
- CTA: "Browse templates" → /

### /pricing
- Three tiers, middle highlighted
- FAQ below fold

7. Motion

- Entrance: fade + translateY 8px, 200ms, ease-out
- Hover: translateY -1px on cards only
- Respect prefers-reduced-motion: disable transforms
- No parallax, no looping background animation

8. Content voice

Short rules for copy agents generate:

• Direct, second person ("you")
• No "leverage," "streamline," "revolutionize"
• Headlines state outcome, not category ("Ship landing pages" not "The future of web design")
• CTA verbs with objects

9. File conventions

Help agents navigate:

- Sections: components/sections/<name>.tsx
- UI primitives: components/ui/
- Do not edit generated lockfiles
- Images in public/images/, WebP preferred

Example: minimal DESIGN.md excerpt

# Acme Analytics — design spec

## Design read
B2B SaaS for data teams, calm technical, light mode, Next.js + Tailwind + shadcn.

## Anti-patterns
- No dark purple gradients
- No more than one primary button per section

## Tokens
- accent: hsl(220 90% 56%)
- font-sans: Geist Sans
- section padding: py-20

## Components
- Use shadcn Button, Card, Input from @/components/ui
- Cards: border only, no shadow-lg

## Motion
- 200ms transitions max on marketing pages

How agents should use it (prompt snippet)

Paste with your task:

Read DESIGN.md before making UI changes.
Follow tokens and anti-patterns exactly.
If the request conflicts with DESIGN.md, ask before overriding.
When done, verify: typography scale, accent usage, and anti-pattern list.

DESIGN.md + templates beats either alone

A spec without structure makes agents paint slop on blank canvases. A template without a spec drifts back to defaults on the second prompt.

Agent's Design gallery ships templates with DESIGN.md files and matching prompts — the spec and the composition bundled so you edit intent instead of inventing layout from noise.

Write your DESIGN.md once, reuse it across features, and update anti-patterns when you catch new agent habits. That is how vibe coding scales without looking like every other AI SaaS.

Versioning and team handoff

Treat DESIGN.md like code:

• Commit it — track changes in git, review in PRs like any config
• Date breaking changes — "2026-07-02: switched accent from blue to terracotta"
• Link from README — "Agents: read DESIGN.md before UI work"
• Split when it grows — DESIGN.md for global tokens, docs/pages/pricing.md for route-specific notes

Designers who do not code can still edit the token and anti-pattern sections. Engineers keep file conventions and component paths accurate.

Common DESIGN.md mistakes

Mistake	Why it fails	Fix
Vague adjectives ("modern, clean")	Agents interpret randomly	Replace with tokens and examples
No anti-patterns	Defaults creep back in	List 5–10 forbidden patterns
Too long (500+ lines)	Agents skip or hallucinate	Split by route or concern
Stale component paths	Agent edits wrong files	Update paths when you refactor
Missing motion rules	Everything animates	Cap durations and list banned effects

Validate the spec works

After writing DESIGN.md, run a spec smoke test:

1. Ask the agent to build a new section (e.g. testimonial strip) using only the spec
2. Check output against anti-patterns — if violations appear, tighten the doc
3. Ask the agent to quote which sections it used — if it cannot, the spec is not visible enough

One iteration on the spec saves ten iteration loops on purple heroes.

Related reading

Pair your spec with an anti-slop design checklist before ship, and pick a starting layout from SaaS landing templates for AI builders or the Agent's Design gallery so composition and constraints stay aligned from prompt one.