Cursor Rules for shadcn/ui
Cursor keeps recreating components that shadcn already has. Here's how to teach it your shadcn setup.
The shadcn/ui problem with AI agents
shadcn/ui components live in your codebase -they're yours to modify. But AI agents don't know which components you've installed, how you've customized them, or that they should reach for the cn() utility for class merging. Without rules, Cursor will create duplicate custom components instead of using your existing shadcn ones.
What shadcn rules need to cover
(1) Import paths -your shadcn components live in src/components/ui/, not in node_modules. (2) cn() utility for class merging -always use it, never template literals. (3) Never re-implement a component that shadcn provides. (4) Variant patterns -how to extend components with cva(). (5) Tailwind class conventions consistent with your design system.
shadcn/ui cursor rules template
Place this at .cursor/rules/shadcn.mdc.
---
description: shadcn/ui component conventions
globs: ["src/components/**", "**/*.tsx"]
alwaysApply: true
---
# shadcn/ui Rules
## Component Imports
- shadcn/ui components live in src/components/ui/
- Import from there: import { Button } from '@/components/ui/button'
- Never import shadcn from node_modules -they are installed components.
## Available Components
Before creating any UI component, check if a shadcn equivalent exists:
Button, Input, Label, Select, Checkbox, RadioGroup, Switch, Slider,
Textarea, Form (with react-hook-form), Dialog, Sheet, Popover, Tooltip,
Card, Badge, Alert, AlertDialog, Separator, Avatar, Skeleton,
Table, Tabs, Accordion, Collapsible, DropdownMenu, NavigationMenu.
## Class Merging
- ALWAYS use cn() from @/lib/utils for conditional or merged Tailwind classes.
✓ className={cn("base-class", isActive && "active-class", className)}
✗ className={`base-class ${isActive ? 'active-class' : ''}`}
## Extending Components
- Use cva() (class-variance-authority) for variants, not manual className branching.
- Extend shadcn components by wrapping them, not by modifying the file in ui/.
- Pass className prop through to allow caller customization.
## Never Do
- Never recreate a component that shadcn provides -use and extend the existing one.
- Never use inline styles -use Tailwind classes with cn().
- Never hardcode colors -use Tailwind CSS variables (bg-background, text-foreground).