How to Use DESIGN.md with Cursor — Complete Setup Guide

cursor design-md setup ai-agents

Every time you ask Cursor to generate a component, it starts from zero. It picks colors, spacing, and typography based on whatever patterns it finds in your codebase — or invents new ones. The result: buttons that don’t match your cards, inconsistent font sizes, and hours spent fixing AI output.

DESIGN.md fixes this. It’s a single Markdown file that contains your entire design system — colors, typography, spacing, components — in a format AI agents can read before generating any code. When Cursor reads your DESIGN.md, every component it generates follows the same visual rules.

This guide walks you through the complete setup: from getting a DESIGN.md to configuring Cursor so it reads the file automatically on every prompt.

What You Need

Step 1: Get a DESIGN.md

You have two options:

Option A: Pick one from the library. Browse the DESIGN.md library and download a pre-built design system that matches your project’s style. Each file includes tokens (colors, fonts, spacing) and prose explaining how to apply them.

Option B: Create your own. Follow the How to Create a DESIGN.md guide to build one from scratch. A minimal DESIGN.md looks like this:

---
name: My App
colors:
  primary: "#2665fd"
  surface: "#ffffff"
  on-surface: "#111827"
typography:
  heading:
    fontFamily: Inter
    fontSize: 1.5rem
    fontWeight: 600
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
spacing:
  sm: 8px
  md: 16px
  lg: 32px
---

## Colors
- **Primary** (#2665fd): CTAs, active states, links
- **Surface** (#ffffff): Page and card backgrounds
- **On-surface** (#111827): Body text, headings

## Typography
- Headings: Inter, semi-bold, 1.5rem
- Body: Inter, regular, 1rem

## Components
- Buttons: primary background, white text, 8px rounded, 12px 24px padding
- Cards: surface background, 1px border #e5e7eb, 12px rounded, 24px padding

## Do's and Don'ts
- Do use primary only for main actions
- Don't mix rounded and sharp corners
- Do maintain 4.5:1 minimum contrast (WCAG AA)

Step 2: Place It in Your Project Root

Drop the file at the root of your repository:

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

The root is the standard location. Cursor and other AI agents look here first, and it stays visible in your file tree as a reminder that the design system exists.

Step 3: Configure Cursor to Read It

This is where the magic happens. You need to tell Cursor: “Read DESIGN.md before generating any UI code.”

Create .cursor/rules/design.mdc:

---
description: Design system rules — read DESIGN.md before generating UI
globs: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.css"]
---

Before generating any visual component, read the DESIGN.md file at the project root.

Rules:
- Use ONLY the colors defined in DESIGN.md
- Follow the typographic scale exactly
- Apply spacing values from the Spacing section
- Follow component patterns from the Components section
- Never violate the Do's and Don'ts section
- When in doubt, reference DESIGN.md — do not invent new values

The globs field ensures this rule only activates for UI files. Backend code won’t trigger it.

Option B: Global .cursorrules

If you prefer a single file, add to .cursorrules in your project root:

# Design System
Always read DESIGN.md before generating UI components.
Apply colors, typography, spacing, and component patterns exactly as defined.
Never introduce visual values not present in DESIGN.md.

Option A is better for larger projects because you can have separate rules for different concerns. Option B is simpler for solo projects.

Step 4: Test It

Open Cursor in your project and try this prompt:

Create a pricing card component with three tiers: Free, Pro, and Enterprise.
Use the project's design system.

Cursor should read your DESIGN.md (you’ll see it referenced in the context) and generate a component using your exact colors, fonts, and spacing — not random defaults.

Try a second prompt to verify consistency:

Create a navigation bar with logo, links, and a CTA button.

Both components should share the same visual language: same primary color on CTAs, same font family, same spacing scale.

Before and After

Without DESIGN.md, each Cursor generation is a coin flip:

With DESIGN.md, Cursor follows your system:

The difference compounds. Over a full page, you save hours. Over a full project, you save days.

Tips for Getting the Most Out of It

Keep DESIGN.md updated. When you change a color or add a component pattern, update the file. Stale tokens lead to stale output.

Use Cursor Composer for multi-file generation. When generating entire pages or features with Composer, DESIGN.md ensures all files share the same visual rules — even across multiple components generated in one session.

Be specific in the Do’s and Don’ts. Vague rules like “keep it clean” don’t help an AI agent. Specific rules like “Never use more than 3 font sizes per page” do.

Validate with the official CLI. Run the linter to catch issues before they reach your AI agent:

npx @google/design.md lint DESIGN.md

Combine with framework-specific rules. Add a second .mdc rule for your framework:

---
description: Tailwind + DESIGN.md integration
globs: ["**/*.tsx"]
---

Map DESIGN.md tokens to Tailwind classes. Use the project's tailwind.config
for custom colors and spacing. Do not use arbitrary values.

Next Steps