All posts
Product design

Cursor Rules and CLAUDE.md for UI Consistency: A Copyable Template

A copyable template for Cursor rules for UI and CLAUDE.md files that encodes your tokens, components and banned patterns so AI agents stop inventing styles.

By Mehdi Hassan8 min read

The short answer

Cursor rules for UI are project instructions that tell a coding agent which components, tokens and patterns to use and which to never write by hand. A good rules file names your sources of truth, maps each UI job to one component, bans raw values, and says what to do when nothing fits. The same content works in CLAUDE.md.

Key takeaways

  • Point to your token file and components folder instead of pasting their contents into the rules.
  • A 'need this, use that' component map stops agents from building new buttons and cards.
  • Banned patterns (hex values, arbitrary spacing, inline styles) are the easiest rules to follow and check.
  • Keep one shared source, such as AGENTS.md, so Cursor and Claude Code follow the same rules.
  • Rules guide agents; lint rules and typed props enforce them.

Part of Design Systems for Startups: What You Need, When and How to Build One

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.

  1. 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.
  2. 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).
  3. 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.
  4. Typography. Use the Heading and Text components or the type utilities defined in tokens.css. Don't set font sizes or weights by hand.
  5. 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.
  6. Accessibility. Every input has a visible label. Every icon-only button has an aria-label. Don't remove focus outlines.
  7. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Frequently asked questions

Do I need both a .cursor/rules file and a CLAUDE.md?
Not necessarily. Both Cursor and Claude Code can read an AGENTS.md file according to their docs, so one shared file can cover both tools. Add a Cursor rule or a .claude/rules file only for scoped rules, such as a component map that should load only when the agent works in UI folders. Keep the shared core in one place.
Should the rules file list every design token value?
No. List the semantic token names the agent may use and point to the token file for the rest. Copying values into the rules means two sources of truth, and the rules version goes stale the next time someone updates a color or a spacing step. The agent can read the token file when it needs a specific value.
Can I use the same template for Copilot or other agents?
Yes. The content is plain instructions with file paths, so it works in any tool that reads a markdown instructions file. Only the file location and scoping syntax differ between tools. Check each tool's current documentation for where it looks for project instructions, since these conventions change often.
How often should I update UI rules?
Update them whenever the design system changes: a new component, a renamed token or a deprecated pattern. A quick monthly review also helps, ideally after running the same few test prompts through your agents. Out-of-date rules are worse than none, because they send agents toward components that no longer exist.
What's the difference between Cursor rules and a design system?
A design system is the tokens, components and usage guidelines themselves. Cursor rules are a short set of instructions telling an agent how to use that system. The rules can only be as good as the system they describe, so a clean component set and semantic tokens come first, and the rules file comes last.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Monthly retainer, $6,000.

Your ongoing design and development team, for products that keep shipping. $6,000, per month, flat fee. Book a free 30-minute call to see if it fits.

Schedule Call