Cursor rules for a design system: keep AI-written UI on brand
By Wolfpixel3 min read
Put your UI rules in a project rules file Cursor always loads (a file in .cursor/rules/, or an AGENTS.md at the repo root), keep them short and testable: use tokens not hex values, import from your component folder first, one icon set, every list has its states, charts follow fixed rules. Then connect a design-system MCP server so the agent can fetch the components the rules point to.
Summarize withChatGPTClaudePerplexity
On this page
We are Wolfpixel. Rules files are the cheapest way to raise the quality of AI-written UI. These are the ones we use, and why each one exists.
Where the rules live
- **
.cursor/rules/*.mdc: Cursor project rules. Set them to always apply for UI rules, or scope them to `app/andcomponents/**`. - `AGENTS.md` at the repo root: read by Cursor and by other agents (Codex and more), so one file serves the whole team.
- Check the current Cursor docs for the exact rule options; the format has changed over time.
A rules file you can copy
---
description: UI rules for every screen
alwaysApply: true
---
- Build UI from components in components/ingot first. Search the Ingot UI MCP (search_components) before writing a new component.
- Colours, radii and shadows come from --fu-* tokens via Tailwind utilities (bg-fu-surface, text-fu-ink). Never write hex values.
- One icon set: <Icon name=… /> from components/ingot/icons. Every icon must depict its label.
- Every table and list ships with empty, loading, error and no-results states.
- Charts: bars start at zero, one accent series, labelled axes, hover tooltip with value and comparison.
- Modals for decisions (confirm, create, delete); drawers for record detail.
- Numbers use tabular figures. Dates over 7 days old show the full date.
- After each screen, run audit_ui and fix what it reports.What each rule prevents
| Rule | Prevents |
|---|---|
| Components first | A new card or table on every screen, each slightly different |
| Tokens, no hex | Colour drift and a dark mode that can never ship |
| One icon set | Mixed stroke weights and styles |
| Every state | Blank tables and confusing first-run screens |
| Chart rules | Smooth fake curves and rainbow series |
| Modal vs drawer | Record detail trapped in modals |
| Audit step | Gradual drift across sessions |
Pair the rules with an MCP server
Rules say what to use; an MCP server lets the agent fetch it. In Cursor, add the Ingot UI server to .cursor/mcp.json (setup on the MCP page) and ask the agent to run init_project once. It writes tokens and an INGOT.md you can reference from your rules.
{
"mcpServers": {
"ingot-ui": {
"url": "https://mcp.ingotui.com/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}More on why AI UI drifts in why AI-built dashboards look generic.
Frequently asked questions
Where do Cursor rules go?
Project rules live in the .cursor/rules folder. Many teams also keep an AGENTS.md at the repo root, which Cursor and other agents read.
How long should a rules file be?
Short enough to read in a minute: ten or so concrete, checkable rules. Long rule files get ignored by people and diluted for the model.
Does Ingot UI provide a rules file?
Yes. The MCP init_project tool writes an INGOT.md with the system’s rules into your project.
About the author
Wolfpixel is the product design studio that designed the six Ingot UI systems from real dashboard projects, and checks every generated React component against its Figma original before it ships. Read more on wolfpixel.agency.