Home › shadcn/ui › shadcn/ui component rules

shadcn/ui component rules

Cursor rules for shadcn/ui with Tailwind CSS v4 and Radix: adding, composing, and theming components.

Cursorshadcn/ui

How to use

Save this as .cursor/rules/shadcn.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: shadcn/ui component conventions
globs: ["components/**/*.tsx","app/**/*.tsx","src/**/*.tsx"]
alwaysApply: false
---

# shadcn/ui

- Add components with the CLI: `npx shadcn@latest add <name>`. Don't hand-copy component source from the web.
- Generated files in `components/ui/` are owned by the project. Edit them only for project-wide changes; build features by composing them in `components/<feature>/`.
- Merge classes with the `cn()` helper from `lib/utils`. Accept a `className` prop and pass it last.
- Variants via `cva` inside the component, not by long conditional class strings at call sites.
- Theme via the CSS variables in the global stylesheet (`--background`, `--primary`, ...) with Tailwind v4 `@theme inline`. Use semantic classes (`bg-primary`, `text-muted-foreground`), not raw colors like `bg-zinc-900`.
- Dark mode by the `.dark` class variables; never duplicate `dark:` overrides per component when a token exists.
- Forms: `react-hook-form` + `zod` with the `Form`/`Field` components the project has installed.
- Keep Radix accessibility: `asChild` for custom triggers, `DialogTitle` on every dialog (visually hidden if needed), labels on inputs.
- Icons from `lucide-react` with `aria-hidden` when decorative.

## Don't
- Don't install a second UI kit (MUI, Chakra) alongside it.
- Don't remove `focus-visible` styles.

## Done when
Lint, typecheck and build pass and the component looks right in both light and dark mode.