ui-ux-pro-max-skill/.qoder/rules/shadcn.md

trigger

trigger
always_on

No	Category	Guideline	Description	Do	Don't	Code Good	Code Bad	Severity	Docs URL
1	Setup	Use CLI for installation	Install components via shadcn CLI for proper setup	npx shadcn@latest add component-name	Manual copy-paste from docs	npx shadcn@latest add button	Copy component code manually	High	shadcn CLI
2	Setup	Initialize project properly	Run init command to set up components.json and globals.css	npx shadcn@latest init before adding components	Skip init and add components directly	npx shadcn@latest init	npx shadcn@latest add button (without init)	High	shadcn Installation
3	Setup	Configure path aliases	Set up proper import aliases in tsconfig and components.json	Use @/components/ui path aliases	Relative imports like ../../components	import { Button } from "@/components/ui/button"	import { Button } from "../../components/ui/button"	Medium	shadcn Installation
4	Theming	Use CSS variables for colors	Define colors as CSS variables in globals.css for theming	CSS variables in :root and .dark	Hardcoded color values in components	bg-primary text-primary-foreground	bg-blue-500 text-white	High	shadcn Theming
5	Theming	Follow naming convention	Use semantic color names with foreground pattern	primary/primary-foreground secondary/secondary-foreground	Generic color names	--primary --primary-foreground	--blue --light-blue	Medium	shadcn Theming
6	Theming	Support dark mode	Include .dark class styles for all custom CSS	Define both :root and .dark color schemes	Only light mode colors	.dark { --background: 240 10% 3.9%; }	No .dark class styles	High	shadcn Dark Mode
7	Components	Use component variants	Leverage cva variants for consistent styling	Use variant prop for different styles	Inline conditional classes		<Button className={isError ? "bg-red-500" : "bg-blue-500"}>	Medium	shadcn Button
8	Components	Compose with className	Add custom classes via className prop for overrides	Extend with className for one-off customizations	Modify component source directly		Edit button.tsx to add w-full	Medium	shadcn Button
9	Components	Use size variants consistently	Apply size prop for consistent sizing across components	size="sm" size="lg" for sizing	Mix size classes inconsistently			Medium	shadcn Button
10	Components	Prefer compound components	Use provided sub-components for complex UI	Card + CardHeader + CardContent pattern	Single component with many props			Medium	shadcn Card
11	Dialog	Use Dialog for modal content	Dialog component for overlay modal windows	Dialog for confirmations forms details	Alert for modal content		styled as modal	High	shadcn Dialog
12	Dialog	Handle dialog state properly	Use open and onOpenChange for controlled dialogs	Controlled state with useState	Uncontrolled with default open only			Medium	shadcn Dialog
13	Dialog	Include proper dialog structure	Use DialogHeader DialogTitle DialogDescription	Complete semantic structure	Missing title or description		Content	High	shadcn Dialog
14	Sheet	Use Sheet for side panels	Sheet component for slide-out panels and drawers	Sheet for navigation filters settings	Dialog for side content		with slide animation	Medium	shadcn Sheet
15	Sheet	Specify sheet side	Set side prop for sheet slide direction	Explicit side="left" or side="right"	Default side without consideration			Low	shadcn Sheet
16	Form	Use Form with react-hook-form	Integrate Form component with react-hook-form for validation	useForm + Form + FormField pattern	Custom form handling without Form	<Form {...form}>		High	shadcn Form
17	Form	Use FormField for inputs	Wrap inputs in FormField for proper labeling and errors	FormField + FormItem + FormLabel + FormControl	Input without FormField wrapper			High	shadcn Form
18	Form	Display form messages	Use FormMessage for validation error display	FormMessage after FormControl	Custom error text without FormMessage		{error && {error}}	Medium	shadcn Form
19	Form	Use Zod for validation	Define form schema with Zod for type-safe validation	zodResolver with form schema	Manual validation logic	zodResolver(formSchema)	validate: (values) => { if (!values.email) }	Medium	shadcn Form
20	Select	Use Select for dropdowns	Select component for option selection	Select for choosing from list	Native select element			Medium	shadcn Select
21	Select	Structure Select properly	Include Trigger Value Content and Items	Complete Select structure	Missing SelectValue or SelectContent			High	shadcn Select
22	Command	Use Command for search	Command component for searchable lists and palettes	Command for command palette search	Input with custom dropdown			Medium	shadcn Command
23	Command	Group command items	Use CommandGroup for categorized items	CommandGroup with heading for sections	Flat list without grouping		without groups	Low	shadcn Command
24	Table	Use Table for data display	Table component for structured data	Table for tabular data display	Div grid for table-like layouts	Medium shadcn Table 25 Table Include proper table structure Use TableHeader TableBody TableRow TableCell Semantic table structure Missing thead or tbody without header High shadcn Table 26 DataTable Use DataTable for complex tables Combine Table with TanStack Table for features DataTable pattern for sorting filtering pagination Custom table implementation useReactTable + Table components Custom sort filter pagination logic Medium shadcn DataTable 27 Tabs Use Tabs for content switching Tabs component for tabbed interfaces Tabs for related content sections Custom tab implementation <div onClick={() => setTab(...)} Medium shadcn Tabs 28 Tabs Set default tab value Specify defaultValue for initial tab defaultValue on Tabs component No default leaving first tab without defaultValue Low shadcn Tabs 29 Accordion Use Accordion for collapsible Accordion for expandable content sections Accordion for FAQ settings panels Custom collapse implementation <div onClick={() => setOpen(!open)}> Medium shadcn Accordion 30 Accordion Choose accordion type Use type="single" or type="multiple" appropriately type="single" for one open type="multiple" for many Default type without consideration without type Low shadcn Accordion 31 Toast Use Sonner for toasts Sonner integration for toast notifications toast() from sonner for notifications Custom toast implementation toast("Event created") setShowToast(true) Medium shadcn Sonner 32 Toast Add Toaster to layout Include Toaster component in root layout in app layout Toaster in individual pages app/layout.tsx: page.tsx: High shadcn Sonner 33 Toast Use toast variants Apply toast.success toast.error for context Semantic toast methods Generic toast for all messages toast.success("Saved!") toast.error("Failed") toast("Saved!") toast("Failed") Medium shadcn Sonner 34 Popover Use Popover for floating content Popover for dropdown menus and floating panels Popover for contextual actions Absolute positioned divs Medium shadcn Popover 35 Popover Handle popover alignment Use align and side props for positioning Explicit alignment configuration Default alignment for all Low shadcn Popover 36 DropdownMenu Use DropdownMenu for actions DropdownMenu for action lists and context menus DropdownMenu for user menu actions Popover for action lists for menu actions Medium shadcn DropdownMenu 37 DropdownMenu Group menu items Use DropdownMenuGroup and DropdownMenuSeparator Organized menu with separators Flat list of items without organization Low shadcn DropdownMenu 38 Tooltip Use Tooltip for hints Tooltip for icon buttons and truncated text Tooltip for additional context Title attribute for tooltips Medium shadcn Tooltip 39 Tooltip Add TooltipProvider Wrap app or section in TooltipProvider TooltipProvider at app level TooltipProvider per tooltip High shadcn Tooltip 40 Skeleton Use Skeleton for loading Skeleton component for loading placeholders Skeleton matching content layout Spinner for content loading for card loading Medium shadcn Skeleton 41 Skeleton Match skeleton dimensions Size skeleton to match loaded content Skeleton same size as expected content Generic skeleton size without sizing Medium shadcn Skeleton 42 AlertDialog Use AlertDialog for confirms AlertDialog for destructive action confirmation AlertDialog for delete confirmations Dialog for confirmations for delete confirmation High shadcn AlertDialog 43 AlertDialog Include action buttons Use AlertDialogAction and AlertDialogCancel Standard confirm/cancel pattern Custom buttons in AlertDialog Cancel CancelConfirm Medium shadcn AlertDialog 44 Sidebar Use Sidebar for navigation Sidebar component for app navigation Sidebar for main app navigation Custom sidebar implementation Medium shadcn Sidebar 45 Sidebar Wrap in SidebarProvider Use SidebarProvider for sidebar state management SidebarProvider at layout level Sidebar without provider without provider High shadcn Sidebar 46 Sidebar Use SidebarTrigger Include SidebarTrigger for mobile toggle SidebarTrigger for responsive toggle Custom toggle button <Button onClick={() => toggleSidebar()}> Medium shadcn Sidebar 47 Chart Use Chart for data viz Chart component with Recharts integration Chart component for dashboards Direct Recharts without wrapper Medium shadcn Chart 48 Chart Define chart config Create chartConfig for consistent theming chartConfig with color definitions Inline colors in charts { desktop: { label: "Desktop", color: "#2563eb" } } Medium shadcn Chart 49 Chart Use ChartTooltip Apply ChartTooltip for interactive charts ChartTooltip with ChartTooltipContent Recharts Tooltip directly <ChartTooltip content={}/> from recharts Low shadcn Chart 50 Blocks Use blocks for scaffolding Start from shadcn blocks for common layouts npx shadcn@latest add dashboard-01 Build dashboard from scratch npx shadcn@latest add login-01 Custom login page from scratch Medium shadcn Blocks 51 Blocks Customize block components Modify copied block code to fit needs Edit block files after installation Use blocks without modification Customize dashboard-01 layout Use dashboard-01 as-is Low shadcn Blocks 52 A11y Use semantic components Shadcn components have built-in ARIA Rely on component accessibility Override ARIA attributes has button role High shadcn Button 53 A11y Maintain focus management Dialog Sheet handle focus automatically Let components manage focus Custom focus handling traps focus document.querySelector().focus() High shadcn Dialog 54 A11y Provide labels Use FormLabel and aria-label appropriately FormLabel for form inputs Placeholder as only label Email High shadcn Form 55 Performance Import components individually Import only needed components Named imports from component files Import all from index import { Button } from "@/components/ui/button" import { Button Card Dialog } from "@/components/ui" Medium - 56 Performance Lazy load dialogs Dynamic import for heavy dialog content React.lazy for dialog content Import all dialogs upfront const HeavyContent = lazy(() => import('./Heavy')) import HeavyContent from './Heavy' Medium - 57 Customization Extend variants with cva Add new variants using class-variance-authority Extend buttonVariants for new styles Inline classes for variants variants: { size: { xl: "h-14 px-8" } } className="h-14 px-8" Medium shadcn Button 58 Customization Create custom components Build new components following shadcn patterns Use cn() and cva for custom components Different patterns for custom const Custom = ({ className }) => <div className={cn("base", className)}> const Custom = ({ style }) => Medium - 59 Patterns Use asChild for composition asChild prop for component composition Slot pattern with asChild Wrapper divs for composition Medium shadcn Button 60 Patterns Combine with React Hook Form Form + useForm for complete forms RHF Controller with shadcn inputs Custom form state management <Input value={email} onChange={(e) => setEmail(e.target.value)} High shadcn Form