GUIDE

How to use your DESIGN.md file

You generated the spec — now make your AI coding agents actually follow it. This guide covers the file's anatomy, wiring it into Cline, Cursor, Claude Code and other agents, and the prompts that get perfectly on-brand output.

Anatomy

What's inside a DESIGN.md

Every file has two layers: machine-readable YAML frontmatter (tokens an agent can parse programmatically) and richly detailed Markdown sections that explain how the design behaves.

# DESIGN.md (excerpt)
---
name: Aurora Landing
colors:
  primary: "#4F46E5"
  accent: "#06B6D4"
  surface: "#FFFFFF"
typography:
  heading: "Inter, 800, -0.03em"
  body: "Inter, 400, 16px/1.6"
radius: [8, 12, 16]
---

## Color System
Primary #4F46E5 is reserved for CTAs…

## Motion
All entrances use cubic-bezier(.16,1,.3,1)…

## Guardrails
Never place accent text on primary bg…

YAML frontmatterNamed design tokens — colors, type, spacing, radii — directly mappable to CSS variables or a Tailwind config.

Color systemFull palette with roles, usage rules and contrast guidance.

Typography & spacingFont stacks, scale, weights, line heights, spacing rhythm and breakpoints.

Components & elevationButtons, cards, nav, inputs — with exact shadows, borders and states.

MotionKeyframes, easings, durations and which elements animate.

GuardrailsExplicit do's & don'ts that stop an agent from drifting off-brand.

Workflow

Five steps to on-brand AI output

Generate & download

Paste your reference URL (or upload a screenshot) in the generator, review the live preview and full report, then download the .md file.

Drop it at your repo root

Save the file as DESIGN.md in the root of your project — next to your README. Agents that scan the workspace will find it naturally.

my-project/ ├── DESIGN.md ← the spec ├── README.md ├── src/ └── package.json

Wire it into your agent's rules

Make reading the file non-optional by adding one rule to your agent configuration:

# .clinerules / .cursorrules / CLAUDE.md Before writing or changing any UI code, read DESIGN.md at the repo root and strictly follow its color tokens, typography scale, spacing, shadows, motion and guardrails. Never invent new colors or fonts.

Prompt with the file in mind

Reference the spec explicitly in your prompts for best results:

"Build a pricing page following DESIGN.md — use the documented card component style, primary color only on CTAs, and the standard entrance animation for section reveals."

Keep it fresh

Whenever the live design changes, re-scan the site and replace the file. Because it's generated from real shipped CSS, your documentation can never silently drift from reality.

Compatibility

Works with every major AI coding agent

DESIGN.md is plain Markdown — any tool that reads project files can use it. Here's where to reference it for each agent:

Cline

.clinerules

Add a rule instructing Cline to read DESIGN.md before UI work. It will honor it in both Plan and Act modes.

Cursor

.cursorrules / .cursor/rules

Reference DESIGN.md in your project rules so every Composer and chat session applies the tokens.

Claude Code

CLAUDE.md

Point to DESIGN.md from CLAUDE.md ("always follow DESIGN.md for styling") — it's read at session start.

GitHub Copilot

.github/copilot-instructions.md

Add the instruction to the repository custom-instructions file so Copilot Chat follows the spec.

Windsurf

.windsurfrules

Same pattern: one rule that mandates reading DESIGN.md before generating any component.

Aider & others

/add DESIGN.md

Add the file to the chat context explicitly, or mention it in your prompt — Markdown needs no special support.

Best practices

Do's & don'ts

✓ Do keep one DESIGN.md per product surface

A marketing site and a dashboard usually deserve separate specs — different densities, different components.

✗ Don't paraphrase the spec in prompts

Let the agent read the file itself. Re-typing tokens from memory reintroduces exactly the inconsistency the file solves.

✓ Do map frontmatter tokens to code

Generate CSS custom properties or a Tailwind theme from the YAML block so the design system exists in code too, not just docs.

✗ Don't hand-edit values without re-verifying

If you tweak colors or spacing manually, run the preview (or the Verify & Fix pass) to be sure the system still holds together.

✓ Do use the guardrails section aggressively

Guardrails are the highest-leverage lines for AI agents — explicit "never do X" rules prevent the most common drift.

✗ Don't let the file go stale

An outdated spec is worse than none — agents will confidently build to the wrong design. Re-scan after visual releases.

Generate your DESIGN.md now

Any URL. Any screenshot. A complete, agent-ready design specification in minutes.

✨ Open the generator