AI Agents

DESIGN.md for Cursor

How to use DESIGN.md with Cursor to keep AI-generated and AI-edited UI consistent with your product design system.

April 15, 20267 min read

Why Cursor needs design context before generating UI

Without a design reference, Cursor resolves every visual decision with the statistical center of its training data — the most common card margin, the most common button color, the most common heading weight — and the result is a codebase that works correctly but looks interchangeable with any other project. When Cursor edits React or Tailwind components without a DESIGN.md file, it makes visual decisions based on common patterns: standard card margins, default button color, typical heading sizes. Those defaults look familiar but not intentional. The product ends up with correct code that looks like a starter kit rather than a real product. DESIGN.md solves this by giving Cursor a written visual contract before it touches a component. The file can describe why your product uses compact card density instead of the default, which exact spacing values map to your design system, how buttons should be styled for primary, secondary, and destructive variants, what empty states should look like rather than leaving them blank, and which visual patterns are explicitly not allowed. When Cursor reads this before starting a task, it aligns new components with existing ones instead of creating a parallel visual system. A file that defines twelve rules does more for UI consistency than twelve follow-up prompts each correcting one off-brand decision.

Setting up DESIGN.md in your Cursor project

The simplest setup is to put DESIGN.md in the repository root alongside CLAUDE.md, AGENTS.md, or any other agent instruction file. Cursor indexes files in the repo, so placing it at root gives the agent easy access. You can also put it in a docs/ folder and reference it by path in your prompts. If your project uses .cursorrules, add a short pointer there: "For all UI work, read DESIGN.md before editing or creating components." That makes the reference automatic for tasks that do not include an explicit reminder. Once the file is in place, test it with a small prompt: ask Cursor to add a new card component and observe whether it follows your spacing, radius, and color rules. If it drifts, the issue is usually that the rule is stated too abstractly. Replace adjectives like "clean" or "minimal" with concrete values: "card padding is 20px, radius is 8px, border is 1px solid the neutral-200 token." Concrete rules produce consistent output; abstract rules produce subjective interpretations.

Best prompt pattern for Cursor UI work

A reliable Cursor prompt for UI work follows three steps: declare the source files, state the task, and set the constraint. A strong example: "Read DESIGN.md for visual rules. Read the existing DashboardCard component as a reference. Add a MetricsCard component that matches the same density, typography, and color treatment." This is more effective than describing the visual style in the prompt itself, because a one-time description is forgotten after the session ends while the file persists across every future session. For larger tasks — adding a new page, redesigning a settings section, or building a new feature surface — include a check step: "After implementing, list any DESIGN.md rules you were uncertain about or had to interpret." This surfaces spec gaps before they become consistent wrong patterns across the codebase. The prompt pattern also works well for review: "Compare this component against DESIGN.md and flag any violations."

What to include in a Cursor-ready DESIGN.md

A practical Cursor-ready file covers eight areas: brand mood, color tokens, typography, spacing, component rules, page layout patterns, anti-patterns, and examples. Brand mood is one short paragraph: "This is a developer tools product. It should feel technical, focused, and trustworthy — not startup-playful or marketing-soft." Color tokens should map to actual CSS variables or Tailwind classes: "--color-primary: 255 87 34" or "bg-orange-500." Typography rules should specify font family, heading sizes, body size, line height, and weight for different contexts. Spacing rhythm can be simple: "use 4px, 8px, 16px, 24px, 32px steps — do not invent intermediate values." Component rules should describe the most common UI elements with explicit behavior: button variants, card structure, form layout, table density, badge usage, modal tone. Page layout patterns should describe what a typical screen looks like — max-width, side nav width, section spacing, header behavior. Anti-patterns are the most underused section and often the most useful: "do not add decorative gradients," "do not use marketing-hero layouts inside operational tools," "do not use large padding in data tables."

Review loop: comparing Cursor output against the spec

The review loop is where DESIGN.md becomes a durable system rather than a one-time prompt. After Cursor generates or edits a component, compare the output against each rule. The checks that matter most are: density (padding and spacing match the spec), color (only tokens from the file appear, no hardcoded hex values), typography (hierarchy matches the type scale), component reuse (Cursor used an existing component where one fits), and anti-patterns (none of the forbidden patterns are present). When the output is correct, note that the relevant rules worked without correction — those rules are doing their job. When the output violates a rule, ask whether the rule was unclear, too abstract, or missing a constraint. Then update DESIGN.md with a more concrete version of the rule. A corrected rule is worth more than a corrected component, because it prevents the same mistake in every future session. Over time, the file becomes increasingly specific and the gap between Cursor output and your product design narrows.

Common mistakes and how to fix them

The most common mistake is writing DESIGN.md as a mood board instead of a specification. Phrases like "modern and minimal" or "clean and professional" do not help Cursor make decisions. Replace them with constraints: "maximum one decorative background per page," "card content aligned to a 16px grid," "secondary headings use weight 600 not 700." The second mistake is not committing the file to version control. DESIGN.md should live alongside the code it governs. When a design decision changes — a new primary color, a revised card style, a change in navigation density — update the file in the same commit. The third mistake is writing rules only for components that already exist and forgetting empty states, error states, loading states, and responsive behavior. These are the surfaces where AI agents drift most, because there is no existing component to copy. A rule like "empty states use a centered icon, one-line message, and a single CTA — no background fills, no large typography" eliminates an entire category of generic output before it appears in the codebase.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

AI Agents5 min read