Why connect DESIGN.md to Cursor?
A task prompt explains what to build now. A repository design specification explains how the product should look across tasks, sessions, contributors, and models. The strongest setup separates concerns: production components are executable truth, DESIGN.md describes the visual system and its constraints, and .cursor/rules/design-system.mdc makes reading that context an explicit habit.
Persistent context
Project rules give Cursor durable, repository-level context.
Focused instructions
Scope design guidance to UI files so unrelated tasks receive less noise.
System before invention
Keep executable truth in components and tokens; use DESIGN.md for intent, composition, and guardrails.
Human review remains essential
Agent instructions reduce arbitrary choices; they do not replace design judgment, accessibility testing, or visual QA.
Four-step setup
Place DESIGN.md at the repository root
Keep exact semantic roles, component recipes, layout patterns, states, motion, responsive rules, accessibility expectations, and “do not” guidance in one reviewable file.
Create .cursor/rules/design-system.mdc
Use the concise rule below. It tells the agent when to consult the detailed specification without copying the whole document into another file.
Give the task measurable acceptance criteria
Name the existing component to reuse, the approved page to compare against, required states, responsive widths, and the visual decisions that must not change.
Review code and pixels
Search the diff for new hard-coded colors, fonts, shadows, radii, duplicate components, and one-off breakpoints. Then inspect the rendered result.
Copy-ready Cursor rule
---
description: Apply the approved product design system
globs: ['src/**/*.{css,scss,tsx,jsx,vue,svelte}']
alwaysApply: false
---
Read @DESIGN.md before editing UI. Reuse existing components and semantic tokens. Do not invent visual values. Validate responsive behavior and interaction states against the approved implementation.A better task prompt
Read DESIGN.md and the existing UI components before coding.
Build the account settings page using the approved page shell, form controls,
buttons, spacing rhythm, typography, and responsive breakpoints.
Acceptance criteria:
- no new colors, fonts, radii, shadows, or animation styles
- reuse existing components before adding variants
- include loading, validation, success, keyboard-focus, and mobile states
- compare at 1440px and 390px with the approved dashboard page
- list any intentional exception before implementing itCommon failure modes
- Only saying “follow the design.” Point to DESIGN.md and concrete implementation sources.
- Duplicating all tokens in the rule file. This creates two sources of truth.
- Ignoring non-default states. Empty, error, loading, focus, and narrow-screen states expose drift first.
- Allowing “improvements” during feature work. Treat visual changes as explicit design-system decisions.
Original implementation example
Suppose an approved card uses the semantic surface token, a 16px radius, one border token, and no shadow. A weak prompt may yield a visually plausible card with a 24px radius and a purple glow. The integrated workflow prevents that by requiring the agent to identify and reuse the card recipe before writing markup. If a new variant is genuinely needed, it must be named, implemented centrally, documented, and reviewed.
Frequently asked questions
Where should DESIGN.md go for Cursor?
Put DESIGN.md at the repository root so it is easy to discover, version, review, and reference from the agent instruction file.
Does Cursor read DESIGN.md automatically?
Do not assume it will. Add an explicit persistent instruction that requires the agent to read DESIGN.md before front-end work.
Should DESIGN.md duplicate the component library?
No. Point to real components and tokens, then document usage, composition, responsive behavior, states, and guardrails that code alone does not explain.
How do I know the integration is working?
Ask the agent to identify the relevant tokens and components before coding, then inspect the diff and compare the rendered result at desktop and mobile widths.