What should Cursor rules for UI include?
Cursor rules for UI should include five things: where the design system lives, which tokens to use, which component handles each job, which patterns are banned, and what to do when nothing fits. That's enough to stop most AI-generated UI from drifting, and short enough that the agent actually follows it.
The rules file is the last layer of a design system for startups, not a replacement for one. If your tokens are messy or you have three button components, the rules file can only paper over it. Fix the system first, then write rules that describe the clean version.
The template below is written for a typical Next.js, Tailwind and shadcn/ui stack, and works the same in Cursor, Claude Code or any agent that reads a markdown instructions file. Swap in your own paths and names.
Where do Cursor rules and CLAUDE.md files live?
Cursor reads project rules from the .cursor/rules folder and also supports a plain AGENTS.md file; Claude Code reads CLAUDE.md and can read AGENTS.md too. This is what each tool's documentation describes as of late 2026, and both change often, so check the current docs before you set up a new repo.
Tool | Where rules live | How to scope them | Size guidance in the docs |
|---|---|---|---|
Cursor | .cursor/rules, as .mdc files | Frontmatter: description, globs, alwaysApply | Keep rules under 500 lines |
Cursor | AGENTS.md in the root or subfolders | Nested files apply to their folder | Not specified |
Claude Code | CLAUDE.md or .claude/CLAUDE.md | Nested CLAUDE.md files load per folder | Target under 200 lines per file |
Claude Code | .claude/rules, as .md files | A paths field in frontmatter | One topic per file |
Claude Code | AGENTS.md | Read when no CLAUDE.md exists, or imported | Same as CLAUDE.md |
Claude Code's docs also describe importing other files into CLAUDE.md with an @ followed by the path, which is the easiest way to share one file across tools. Cursor's docs note that plain .md files inside .cursor/rules are ignored, so use the .mdc extension there.
What does a copyable UI rules template look like?
Here is the template, section by section. Paste it into AGENTS.md, CLAUDE.md or a Cursor rule and replace the paths and names with yours. Each line is a short instruction, because agents follow specific, checkable rules better than principles.
- Sources of truth. UI components live in src/components/ui. Design tokens live in src/styles/tokens.css. Read both before writing or changing any UI. Never create a component that duplicates one in src/components/ui.
- Tokens. Use only semantic token utilities for color: bg-background, bg-card, bg-primary, text-foreground, text-muted-foreground, border-border, text-destructive. Use the spacing scale (gap-2, gap-4, p-6 and so on). Use radius tokens (rounded-md, rounded-lg).
- Components. Actions use Button with variant primary, secondary, ghost or destructive. Forms use Field, Input, Select, Textarea and Checkbox. Confirmations use Dialog. Side panels use Sheet. Feedback uses Toast. Empty screens use EmptyState. Page layout uses PageShell and Section.
- Typography. Use the Heading and Text components or the type utilities defined in tokens.css. Don't set font sizes or weights by hand.
- Banned patterns. No hex, rgb or hsl color values. No arbitrary Tailwind values in square brackets. No inline style attributes. No new button, card, badge or modal components. No icons from a second icon library.
- Accessibility. Every input has a visible label. Every icon-only button has an aria-label. Don't remove focus outlines.
- When nothing fits. Compose from existing components first. If that still doesn't work, stop and explain what's missing instead of building a new component. List any new UI pattern in your summary.
How do you encode design tokens in a rules file?
Encode tokens by listing the semantic names the agent may use and banning raw values outright. The agent doesn't need to know that primary is a particular blue; it needs to know that primary is the only correct choice for a main action.
This works only if your tokens are semantic. If your code exposes blue-500 and gray-700 as the main utilities, the agent has no way to tell which gray means muted text. Our guide to design tokens covers the primitive, semantic and component layers, and the Figma variables to Tailwind pipeline shows how to make the same names exist in Figma and code.
Two details make the difference in practice. Name the token file by path so the agent reads it when it needs a value you didn't list. And add one line for dark mode, such as 'never write dark: color overrides; tokens already switch per theme', because agents often add them out of habit from public code.
How do you stop AI agents inventing new buttons?
Stop agents inventing new buttons by giving them one Button with a closed set of variants, a rule that bans new button components, and a map from each UI job to the component that handles it. Agents invent components when the request doesn't obviously match anything they've seen in your repo.
- Make the map match how people ask. 'Confirm before deleting' should point to Dialog with the destructive variant, in those words.
- Delete duplicates. If an old PrimaryButton still exists, the agent will find it. No rule beats removing the file.
- Type the variants. A TypeScript union on the variant prop means an invented variant fails to compile.
- Ask for a summary. The last template rule makes the agent list new patterns, so you see drift in the summary instead of in production.
If you're starting from shadcn/ui, our shadcn/ui vs custom design system comparison explains how to theme its components so they're the only ones your agents reach for.
How should you split UI rules for Cursor and Claude Code?
Split UI rules into a short always-on core and scoped rules that load only for UI files, and keep one shared source that every tool reads. That way your component rules don't fill the context when an agent is fixing a database query.
Write the core once
Put sources of truth, the banned patterns and the 'when nothing fits' rule in AGENTS.md at the repo root. These apply to every task.
Scope the component map
Move the component map and typography rules into a Cursor rule with globs for your components and app folders, and a .claude/rules file with a matching paths field.
Connect Claude Code
If you also keep a CLAUDE.md, import AGENTS.md from it so Claude Code reads the shared core. Without the import, Claude Code's docs say it reads only CLAUDE.md when both exist.
Test with real requests
Ask each tool for the same three screens, such as a settings page, an empty state and a delete confirmation, and compare the diffs.
Review monthly
When the system gains a component, add it to the map the same day. A map that's out of date sends agents back to inventing.
Hypothetical example: tightening rules after one bad diff
For example, suppose a team asks its agent for a billing settings page. The result uses Button correctly but adds a new 'InfoBox' with a hand-picked yellow background for a payment warning.
The rules didn't cover warnings, and the system had no component for them. The fix has two parts: add an Alert component with info, warning and destructive variants that use the existing tokens, then add 'inline warnings use Alert' to the component map.
The next run of the same request uses Alert. The useful habit is reading the bad diff as a gap in the system, not just a mistake to revert.
Why do agents still ignore UI rules?
Agents still ignore UI rules because rules are context, not enforcement. Claude Code's documentation says this directly about CLAUDE.md, and it holds for every tool: the agent weighs your rules against the request, the code it has read and its own habits.
Long or contradictory files make it worse. Claude Code's docs note that when two instructions conflict, the model may pick one arbitrarily. Keep rules short, delete outdated ones, and back the important ones with tooling: ESLint's no-restricted-imports to block old component paths, a lint rule against arbitrary Tailwind values, and typed props.
If your agents keep missing because the system itself is thin, that's a design problem, not a prompting problem. Our design system service builds the tokens, components and rules together, and the design retainer keeps them in step with the product.
