How to Create a DESIGN.md from Scratch

design-md tutorial ai-agents

A DESIGN.md file is a single Markdown document that holds your entire design system — colors, typography, spacing, components — in a format that both humans and AI agents can read. When an agent like Claude Code or Cursor opens your project, it reads DESIGN.md before generating any UI code. Every component it creates follows the same visual rules.

Without this file, each prompt starts from zero. The agent picks arbitrary colors, invents spacing values, and produces inconsistent interfaces. DESIGN.md fixes that by placing hard constraints inside the context window. One file, one source of truth.

The format combines two layers: YAML front matter for machine-readable design tokens and Markdown prose for human-readable rationale. This guide walks you through building one from scratch.

Prerequisites

That’s it. No dependencies, no build tools. DESIGN.md is just a file.

Step 1: Create the File

Create a file named DESIGN.md at the root of your project:

my-project/
├── DESIGN.md    ← here
├── src/
├── package.json
└── ...

The root placement matters. AI agents like Claude Code and Cursor scan the project root for context files. If DESIGN.md lives in a subfolder, the agent may not find it automatically.

Step 2: Add YAML Front Matter

Open the file and add the YAML header between --- delimiters. This is where you define your design tokens — the raw values agents consume directly:

---
name: My App
description: A clean productivity tool with a calm, focused aesthetic
version: 1.0.0
tags: [saas, productivity, minimal]
---

The name and description fields give the agent context about the project’s identity. Keep the description short but specific — it influences the visual tone of generated components.

Step 3: Define Design Philosophy

Below the front matter, start the Markdown body with a philosophy section. This is prose, not tokens. It tells the agent why the design looks the way it does:

## Design Philosophy

This design system prioritizes clarity and calm. Interfaces should feel
spacious, not cramped. Use whitespace generously. Avoid visual noise —
no gradients, no drop shadows heavier than `sm`, no more than two font
weights on a single screen.

The aesthetic is inspired by Scandinavian minimalism: neutral tones,
clean lines, functional beauty.

This section is surprisingly powerful. AI agents use it to make judgment calls when the tokens don’t cover a specific case.

Step 4: Set Color Palette

Define your colors using CSS custom properties. This format works across frameworks and gives agents exact values to use:

## Colors

### Primary Palette
- `--color-primary`: `#2563eb` — Main actions, links, focus rings
- `--color-primary-hover`: `#1d4ed8` — Hover state for primary elements
- `--color-primary-light`: `#dbeafe` — Backgrounds, badges, highlights

### Neutral Palette
- `--color-bg`: `#ffffff` — Page background
- `--color-surface`: `#f8fafc` — Card and section backgrounds
- `--color-border`: `#e2e8f0` — Dividers and input borders
- `--color-text`: `#0f172a` — Body text
- `--color-text-muted`: `#64748b` — Secondary text, captions

### Semantic Colors
- `--color-success`: `#16a34a`
- `--color-warning`: `#d97706`
- `--color-error`: `#dc2626`

Each variable includes a usage note after the — dash. Agents read these notes to decide which color to apply where.

Step 5: Configure Typography

Specify font families, sizes, and weights. Be explicit — vague instructions like “use a nice font” produce inconsistent results:

## Typography

- **Font family (body):** `Inter, system-ui, sans-serif`
- **Font family (headings):** `Inter, system-ui, sans-serif`
- **Font family (code):** `JetBrains Mono, monospace`

### Scale
| Token   | Size     | Weight | Use case              |
|---------|----------|--------|-----------------------|
| `h1`    | `2.25rem`| `700`  | Page titles           |
| `h2`    | `1.5rem` | `600`  | Section headings      |
| `h3`    | `1.25rem`| `600`  | Subsection headings   |
| `body`  | `1rem`   | `400`  | Paragraphs, UI text   |
| `small` | `0.875rem`| `400` | Captions, helper text |

Line height: `1.6` for body text, `1.2` for headings.

The table format works well here. Agents parse tables reliably and can map tokens to CSS without ambiguity.

Step 6: Define Spacing Scale

A consistent spacing scale prevents the “everything looks slightly off” problem. Use a base-4 or base-8 system:

## Spacing

Base unit: `4px`

| Token  | Value  | Use case                        |
|--------|--------|---------------------------------|
| `xs`   | `4px`  | Tight gaps, icon padding        |
| `sm`   | `8px`  | Inline spacing, small gaps      |
| `md`   | `16px` | Default padding, stack spacing  |
| `lg`   | `24px` | Section padding, card padding   |
| `xl`   | `32px` | Page margins, large gaps        |
| `2xl`  | `48px` | Section separators              |
| `3xl`  | `64px` | Hero sections, major breaks     |

Border radius: `6px` for cards and inputs, `9999px` for pills and avatars.

Step 7: Document Components

Describe your core components with enough detail for an agent to reproduce them. You don’t need every variant — focus on the patterns that repeat most:

## Components

### Buttons
- **Primary:** `bg: --color-primary`, white text, `padding: sm md`,
  `border-radius: 6px`, `font-weight: 500`. Hover darkens to `--color-primary-hover`.
- **Secondary:** Transparent bg, `border: 1px solid --color-border`,
  `color: --color-text`. Hover adds `bg: --color-surface`.
- **Ghost:** No border, no background. Text uses `--color-primary`.
  Hover adds subtle background.

### Cards
- `bg: --color-surface`, `border: 1px solid --color-border`,
  `border-radius: 6px`, `padding: lg`.
- No drop shadow by default. Use `box-shadow: 0 1px 3px rgba(0,0,0,0.08)`
  only for elevated cards (modals, dropdowns).

### Inputs
- `height: 40px`, `padding: sm md`, `border: 1px solid --color-border`,
  `border-radius: 6px`. Focus ring: `2px solid --color-primary` with `2px` offset.

Complete Example

Here’s a minimal but functional DESIGN.md you can copy and adapt:

---
name: Starter App
description: Clean SaaS starter with a professional, focused aesthetic
version: 1.0.0
tags: [saas, starter, minimal]
---

## Design Philosophy

Calm, professional, and spacious. Prioritize readability and clear
hierarchy. Avoid decorative elements that don't serve a function.

## Colors

- `--color-primary`: `#2563eb`
- `--color-primary-hover`: `#1d4ed8`
- `--color-bg`: `#ffffff`
- `--color-surface`: `#f8fafc`
- `--color-border`: `#e2e8f0`
- `--color-text`: `#0f172a`
- `--color-text-muted`: `#64748b`

## Typography

- **Body:** `Inter, system-ui, sans-serif` at `1rem/1.6`
- **Headings:** `Inter` — h1 `2.25rem/700`, h2 `1.5rem/600`
- **Code:** `JetBrains Mono, monospace`

## Spacing

Base: `4px`. Scale: `xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48)`

## Components

- **Button primary:** `bg: --color-primary`, white text, `rounded-md`, `px-4 py-2`
- **Card:** `bg: --color-surface`, `border: --color-border`, `rounded-md`, `p-6`
- **Input:** `h-10`, `border: --color-border`, `rounded-md`, focus ring `--color-primary`

Next Steps