DESIGN.md: The File That Turns AI Agents Into Designers

You ask Claude Code or Cursor to build a landing page. The result works, but looks like a generic Bootstrap template. Random colors, inconsistent typography, approximate spacing. The problem isn't the model — it's missing design context.

DESIGN.md solves exactly this. Introduced by Google Stitch and popularized by the open source project awesome-design-md (over 10,000 GitHub stars in days), this simple Markdown file encodes your entire design system in a format LLMs understand natively.

The Problem: Agents That Code Well But Design Poorly

AI coding agents have made spectacular progress. They generate functional code, manage dependencies, write tests. But visually, they improvise.

Without explicit design context, an agent will:

Pick arbitrary colors or default to blue/gray
Use font sizes without consistent hierarchy
Apply inconsistent spacing between components
Produce interfaces that work but don't look professional

Figma exports, JSON design token files, or systems like Style Dictionary already exist. But they're built for tooling pipelines, not for LLMs. A 2,000-line JSON token file doesn't give an agent the context to make good design decisions.

DESIGN.md: The README for Your Design System

The concept is simple: a Markdown file placed at your project root that any AI agent can read and interpret. Just as CLAUDE.md defines behavior rules for Claude Code, DESIGN.md defines visual rules.

A typical DESIGN.md contains nine standardized sections:

Visual Theme and Atmosphere — the overall art direction
Color Palette and Roles — primary, secondary, accent, semantic
Typography Rules — families, scale, weights, line heights
Component Styles — buttons, cards, forms, navigation
Layout Principles — grid, containers, breakpoints
Depth and Elevation — shadows, layering, z-index
Do's and Don'ts — design guardrails
Responsive Behavior — mobile, tablet, desktop adaptations
Agent Prompt Guide — specific instructions for AI tools

Minimal Example

Here's what a simplified DESIGN.md looks like:

## Colors
- Primary: #1A73E8
- Primary Dark: #1557B0
- Surface: #FFFFFF
- Text Primary: #1F2937
- Text Secondary: #6B7280
- Success: #10B981
- Error: #EF4444
 
## Typography
- Font Family: Inter, sans-serif
- H1: 32px, weight 700
- H2: 24px, weight 600
- Body: 16px, weight 400
- Caption: 14px, weight 400
 
## Spacing
- Base unit: 8px
- Values: 4, 8, 16, 24, 32, 48px
 
## Components
- Button border-radius: 8px
- Card shadow: 0 1px 3px rgba(0,0,0,0.12)
- Container padding: 24px

When an agent reads this file, it stops guessing. It applies your exact values.

The awesome-design-md Project

The VoltAgent/awesome-design-md repository catalyzed this trend. It offers 55 DESIGN.md files extracted from real websites, covering a wide range of styles:

AI and Machine Learning: Claude, Cohere, ElevenLabs, Mistral AI, Ollama, Replicate, xAI

Developer Tools: Cursor, Linear, Vercel, Supabase, Sentry, PostHog, Raycast

Design and Productivity: Figma, Notion, Framer, Miro, Airtable, Webflow

Fintech: Stripe, Coinbase, Revolut, Wise

Enterprise and Consumer: Apple, Airbnb, Spotify, Uber, BMW, NVIDIA, SpaceX

Each folder contains the DESIGN.md plus preview.html and preview-dark.html files to visualize the result.

Practical Usage

# Clone the repository
git clone https://github.com/VoltAgent/awesome-design-md.git
 
# Copy a design system into your project
cp awesome-design-md/designs/stripe/DESIGN.md ./DESIGN.md
 
# Your AI agent detects it automatically

Then simply ask your agent:

"Build a pricing page following the project's DESIGN.md."

The result will respect Stripe's colors, typography, spacing, and components — no Figma export or extra configuration needed.

Why Markdown Instead of JSON or YAML

The choice of Markdown is deliberate. LLMs treat Markdown as a native format — they constantly generate it and understand it intuitively. A JSON token file is technically precise but lacks semantic context.

Compare:

JSON (technical, no context):

"button.borderRadius": "8px",
"button.primary.bg": "#1A73E8"

Markdown (semantic, contextual):

## Buttons
- Border-radius: 8px for a modern but accessible look
- Primary background: #1A73E8 — used for main actions
- Never use square corners (radius 0)

Markdown lets you mix values with intentions and constraints. The "Do's and Don'ts" section is particularly powerful: it acts as guardrails that AI agents respect.

Tool Compatibility

DESIGN.md works with any agent that reads project files:

Claude Code — automatically reads Markdown files at the project root
Cursor — integrates project file context into prompts
GitHub Copilot Workspace — uses repository context
Google Stitch — built natively for DESIGN.md
Gemini CLI — reads working directory files
Custom agents (LangChain, CrewAI) — add the file as context

Creating Your Own DESIGN.md

You can start from scratch or adapt an existing file. Here are the recommended steps:

1. Extract Existing Tokens

If you have a design system in Figma, Tailwind, or another tool, document the key values: colors, fonts, spacing, border radii, shadows.

2. Add Semantic Context

Don't just list hex values. Explain the roles:

## Colors
- Primary (#2563EB): main actions, links, focus states
- Destructive (#DC2626): deletion, critical errors
- Surface (#F9FAFB): card and modal backgrounds

3. Include Constraints

The most underrated section. AI agents respect explicit prohibitions:

## Strict Rules
- Never use more than 3 colors on a single screen
- Always maintain minimum WCAG AA contrast ratio
- Primary buttons always have minimum 24px horizontal padding
- Never center long text paragraphs

4. Version With Your Code

Place DESIGN.md at the project root, in the same repository as your code. Design changes go through pull requests, with review and history.

A Converging Pattern

DESIGN.md is part of the broader "knowledge files for agents" trend. The emerging stack looks like:

CLAUDE.md / .cursorrules — behavior rules and coding conventions
DESIGN.md — design system and visual rules
SPEC.md — product specifications and functional requirements
AGENTS.md — multi-agent workflow configuration

Each file encodes institutional knowledge in a format AI agents can navigate. Software development is restructuring around structured Markdown documents that serve as contracts between humans and agents.

Current Limitations

DESIGN.md is powerful but not perfect:

No complex state management — variants, animations, and micro-interactions remain hard to encode in Markdown
Drift risk — if the file diverges from the actual design system in Figma, agents will produce incorrect results
No automatic validation — nothing verifies that generated code actually follows the DESIGN.md
Size constraints — a complete enterprise design system may exceed the useful context window

For complex systems with hundreds of components, DESIGN.md complements Figma rather than replacing it. It excels at giving agents consistent direction, not encoding every pixel.

Get Started Now

The barrier to entry is almost zero:

Copy a DESIGN.md from awesome-design-md that matches your visual identity
Adapt the values to your brand guidelines (colors, fonts, spacing)
Test with a prompt: ask your agent to build a component and compare the result
Iterate: add constraints when you notice inconsistencies

In five minutes, your AI agents go from "junior frontend developer improvising" to "developer following a precise mockup." All with a simple text file.