Cursor design system setup: rules, MCP and checks
Make Cursor build UI with your tokens and components using a project rule, an MCP server and a check on every change. Files and commands included.
Thiago Baptistella · · 5 min read
Cursor's agent can build a settings page in a minute. If your company has a design system, the page it builds will usually ignore it: a Tailwind bg-blue-600 where your primary colour should be, a raw <button> where you have a Button component, p-[14px] where your spacing scale says 12 or 16.
That isn't a Cursor bug. The agent only knows what's in its context, and your design system usually isn't there. This guide shows how to put it there with files Cursor already reads, in three layers: a project rule, an MCP server, and a check that catches what slips through.
What Cursor reads before it writes UI
Cursor builds its context from three places you control:
- Project rules in
.cursor/rules/*.mdc, committed to the repo. These are the main lever. AGENTS.mdat the repo root, which Cursor and several other agents also read.- MCP servers listed in
.cursor/mcp.json, which give the agent tools it can call while it works.
User rules in Cursor's settings apply only to one person's machine, so they're the wrong place for a team's design system. Put it in the repo, where every developer and every review sees the same rules.
Step 1: Put your tokens in a file the agent can see
Rules work best when they point at real values. Plain CSS custom properties are the easiest format: the browser uses them and the model reads them.
/* src/styles/tokens.css */
:root {
--color-action-primary: #0f766e;
--color-text-default: #111827;
--color-surface: #ffffff;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-6: 24px;
--radius-md: 8px;
--font-body: "Inter", system-ui, sans-serif;
}If your tokens live in Figma or Tokens Studio, export them once and generate this file. The point is a single source in the repo that both the app and the agent use.
Step 2: Write a project rule
Create .cursor/rules/design-system.mdc. The front matter decides when Cursor attaches the rule:
---
description: Design system rules for all UI code
globs: ["**/*.{tsx,jsx,vue,svelte,html,css,scss}"]
alwaysApply: true
---
# Design system
- Use the components in `src/components/ui` for buttons, inputs, selects, dialogs and cards.
Never re-create them with raw HTML elements.
- Colours: only the CSS variables in `src/styles/tokens.css`. No hex values, no Tailwind
palette classes such as `bg-blue-600`.
- Spacing: 4, 8, 12, 16 or 24px (`--space-1` to `--space-6`). No arbitrary values.
- Radius: `--radius-md` unless a component sets its own.
- Fonts: `--font-body` only.
- Don't import from `@mui/material` or `bootstrap`: they are being removed.How the front matter works
alwaysApply: trueadds the rule to every agent request. Use it for a short design-system rule; it's the one thing you never want the agent to miss.globsattaches a rule automatically when matching files are in play. Handy for splitting rules, for example one for*.vueand one for*.tsx.descriptionlets the agent decide to pull a rule in when it looks relevant. Good for long reference rules you don't want in every request.
Keep the rule short and specific
A rule is read on every request, so every line costs context. Name components by import path, give token names rather than descriptions ("use --color-action-primary", not "use our brand colour"), and list forbidden imports explicitly. If your list of components runs past a screen, move the detail into tools (step 3) and keep only the rules here.
Step 3: Give Cursor tools instead of more text
Rules tell the agent what to do. An MCP server lets it look things up: the props of your DataTable, whether Badge is deprecated, which token to use for a warning border. That scales to a component library that would never fit in a rule file.
Cursor reads project MCP servers from .cursor/mcp.json:
{
"mcpServers": {
"design-system": {
"command": "npx",
"args": ["-y", "your-design-system-mcp"]
}
}
}Once it's committed, Cursor lists the server under its MCP settings and the agent can call its tools mid-task. If you build your own, the tools worth having are: get the tokens, find a component by what it does, get a component's props and usage, and validate a snippet before it's written.
Step 4: Check what the agent wrote
Rules and tools reduce drift. They don't stop it: an agent under a long context will still reach for #fff now and then, and so will a tired human. You need a check that runs without anyone remembering to run it.
A quick version with no tools beyond grep:
# Hex colours and Tailwind palette classes in changed UI files
git diff --name-only origin/main -- '*.tsx' '*.vue' '*.css' \
| xargs grep -nE '#[0-9a-fA-F]{3,8}\b|\b(bg|text|border)-(red|blue|green|gray|slate)-[0-9]{2,3}\b'It's crude: it misses spacing, raw components and forbidden imports, and it flags hex values in comments. But in a pre-commit hook or a CI step it catches the most common drift on day one.
The same setup with Brandrail in one command
Doing the above by hand works for one repo. It gets harder with five repos, three frameworks and a design system that changes every month, because every copy of the rule goes stale.
Brandrail generates and maintains these files from one Brand Kit:
npx brandrail connectIt signs you in through the browser, detects the framework (React, Angular, Vue, Svelte, Solid, Web Components or plain HTML), and writes:
.cursor/rules/brandrail.mdcwithalwaysApply: true, your tokens, components and rulesAGENTS.md,CLAUDE.md,.github/copilot-instructions.mdand the Windsurf and Gemini files, so every tool in the team gets the same rules.cursor/mcp.jsonpointing at the Brandrail MCP server, which runs locally (npx -y brandrail mcp), so your code never leaves the machine
The MCP server gives Cursor seven tools, including get_design_tokens, find_component, get_component_docs and validate_snippet, which checks a snippet against your rules before the agent writes it.
For step 4, the checker covers 12 rules (hard-coded colours, palette classes, spacing and radius scale, fonts, raw HTML instead of components, forbidden and legacy imports, component props, deprecated components and tokens, alt text):
# Only the lines changed against main
npx brandrail check --changed
# Before every commit
npx brandrail hook installWhen you publish a change to the Brand Kit, the GitHub App opens a sync pull request in every connected repo, so the Cursor rule never goes stale.
Try it
Run npx brandrail connect in a repo you use with Cursor, then ask the agent for a settings page and compare it with what you got last week. The free plan covers one repo, three people and 100 checks a month, and without an account the MCP server still works with starter tokens.