shadcn-ui

shadcn/ui Rules

Component Usage

• Import components from @/components/ui/, never from the underlying Radix/react-aria source directly
• Add new components via CLI: npx shadcn-ui@latest add [component] — this copies source into your project, not a node_modules dependency
• Do not modify files in components/ui/ directly — create wrapper components in components/ that compose the ui/ primitives. When you re-run add, your changes get overwritten
• Check if a shadcn component exists before building custom: Button, Dialog, Sheet, Popover, Command, Table, Form, Toast, Tabs, Accordion, etc. — the library covers more than people expect
• shadcn components are unstyled skeletons using your theme — they look broken without your tailwind config and globals.css set up

Styling

• Use the cn() utility (lib/utils.ts) for all conditional classes — it wraps clsx + tailwind-merge so conflicting utilities resolve correctly
• Follow the existing color convention: CSS variables in globals.css (--primary, --secondary, --muted, --destructive, --ring, etc.) mapped in tailwind.config — never use raw Tailwind colors like bg-blue-500 in shadcn components
• Dark mode is built in via CSS variable switching — the same component renders both modes if your CSS variables are set up for both .dark and :root
• When extending a component's style, pass className to the component root — shadcn components forward className and merge it with cn()

Forms

• Use react-hook-form + zod + shadcn <Form> components together — FormField, FormItem, FormLabel, FormControl, FormMessage provide accessible wiring automatically
• FormField's render prop gives you field — spread it onto the shadcn input: <Input {...field} />. Don't manually wire onChange/value
• FormMessage renders the zod error for that field automatically — no need for custom error display logic
• For select/combobox in forms, use shadcn Select inside FormControl — it handles the hidden input value that react-hook-form needs