Teach Cursor Your Design System with Rules

Rules are a standing brief for the agent. Write your colours, spacing and component choices down once, and every request follows them without you repeating yourself.

Why rules matter for designers

Without rules, the agent makes sensible guesses: a blue button here, 15px of padding there. Each guess is reasonable and together they drift from your system. A rule turns your design decisions into instructions the agent reads before it writes anything.

Where rules live

Project rules

Files in a .cursor/rules folder inside your project, ending in .mdc. They travel with the project, so anyone who opens it gets the same rules. This is where a design system belongs.

AGENTS.md

One plain Markdown file in the project root. The simplest option: no settings, just write. Other AI tools read it too.

User rules

Short personal preferences that apply to every chat in every project, such as "explain changes in plain language". You add them in Customize → Rules.

Team rules

Set once for a whole team in Cursor's dashboard. Teams and Enterprise plans only.

Add a user rule

Create a project rule

Your design system belongs in a project rule, so it travels with the project. Type /create-rule in the prompt box with your project selected, and describe what the rule should cover, for example: "a design-system rule with our colours, spacing scale and components". The agent writes the file into .cursor/rules for you. You can also ask in plain words: "Create a project rule for our design system."

A design-system rule to start from

---
description: Design system for all UI work
alwaysApply: true
---

# Design system

## Colour
- Use the CSS variables in @src/index.css. Never hard-code hex values.
- Primary actions use --color-primary. One primary button per view.

## Spacing
- Spacing scale: 4, 8, 12, 16, 24, 32, 48. Nothing in between.
- Cards use 24px padding and 16px gaps.

## Components
- Reuse what is in @src/components before creating anything new.
- Buttons: Button component only, variants primary, secondary, ghost.

## Accessibility
- Text contrast at least 4.5:1.
- Every interactive element reachable by keyboard, with a visible focus state.

The part between the --- lines is settings. alwaysApply: true means the agent reads this rule on every request. The @ references point the agent at real files instead of copying their contents into the rule.

When a rule applies

Always Apply

Read on every request. Right for a design system.

Apply Intelligently

The agent reads the rule's description and decides when it is relevant. Good for "how we write empty states".

Apply to Specific Files

Used when matching files are involved, for example only components. You set this with a file pattern.

Apply Manually

Only when you mention it, for example @launch-checklist.

The type is set in the settings lines at the top of the rule file. When the agent creates a rule for you, tell it which behaviour you want, for example "apply this to every request".

The quick version: AGENTS.md

If one file of guidance is enough, create AGENTS.md in the root of your project and write plain instructions. No settings needed. The agent reads it on every request.

# Notes for the agent

- This is a prototype for usability testing, so favour clarity over completeness.
- Use the colours and spacing in src/index.css.
- Keep copy short and in sentence case.

Try it