[
{
"No": "1",
"Category": "Setup",
"Guideline": "Use CLI for installation",
"Description": "Install components via shadcn CLI for proper setup",
"Do": "npx shadcn@latest add component-name",
"Don't": "Manual copy-paste from docs",
"Code Good": "npx shadcn@latest add button",
"Code Bad": "Copy component code manually",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/cli"
},
{
"No": "2",
"Category": "Setup",
"Guideline": "Initialize project properly",
"Description": "Run init command to set up components.json and globals.css",
"Do": "npx shadcn@latest init before adding components",
"Don't": "Skip init and add components directly",
"Code Good": "npx shadcn@latest init",
"Code Bad": "npx shadcn@latest add button (without init)",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/installation"
},
{
"No": "3",
"Category": "Setup",
"Guideline": "Configure path aliases",
"Description": "Set up proper import aliases in tsconfig and components.json",
"Do": "Use @/components/ui path aliases",
"Don't": "Relative imports like ../../components",
"Code Good": "import { Button } from \"@/components/ui/button\"",
"Code Bad": "import { Button } from \"../../components/ui/button\"",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/installation"
},
{
"No": "4",
"Category": "Theming",
"Guideline": "Use CSS variables for colors",
"Description": "Define colors as CSS variables in globals.css for theming",
"Do": "CSS variables in :root and .dark",
"Don't": "Hardcoded color values in components",
"Code Good": "bg-primary text-primary-foreground",
"Code Bad": "bg-blue-500 text-white",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/theming"
},
{
"No": "5",
"Category": "Theming",
"Guideline": "Follow naming convention",
"Description": "Use semantic color names with foreground pattern",
"Do": "primary/primary-foreground secondary/secondary-foreground",
"Don't": "Generic color names",
"Code Good": "--primary --primary-foreground",
"Code Bad": "--blue --light-blue",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/theming"
},
{
"No": "6",
"Category": "Theming",
"Guideline": "Support dark mode",
"Description": "Include .dark class styles for all custom CSS",
"Do": "Define both :root and .dark color schemes",
"Don't": "Only light mode colors",
"Code Good": ".dark { --background: 240 10% 3.9%; }",
"Code Bad": "No .dark class styles",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/dark-mode"
},
{
"No": "7",
"Category": "Components",
"Guideline": "Use component variants",
"Description": "Leverage cva variants for consistent styling",
"Do": "Use variant prop for different styles",
"Don't": "Inline conditional classes",
"Code Good": "<Button variant=\"destructive\">",
"Code Bad": "<Button className={isError ? \"bg-red-500\" : \"bg-blue-500\"}>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/button"
},
{
"No": "8",
"Category": "Components",
"Guideline": "Compose with className",
"Description": "Add custom classes via className prop for overrides",
"Do": "Extend with className for one-off customizations",
"Don't": "Modify component source directly",
"Code Good": "<Button className=\"w-full\">",
"Code Bad": "Edit button.tsx to add w-full",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/button"
},
{
"No": "9",
"Category": "Components",
"Guideline": "Use size variants consistently",
"Description": "Apply size prop for consistent sizing across components",
"Do": "size=\"sm\" size=\"lg\" for sizing",
"Don't": "Mix size classes inconsistently",
"Code Good": "<Button size=\"lg\">",
"Code Bad": "<Button className=\"text-lg px-8 py-4\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/button"
},
{
"No": "10",
"Category": "Components",
"Guideline": "Prefer compound components",
"Description": "Use provided sub-components for complex UI",
"Do": "Card + CardHeader + CardContent pattern",
"Don't": "Single component with many props",
"Code Good": "<Card><CardHeader><CardTitle>",
"Code Bad": "<Card title=\"x\" content=\"y\" footer=\"z\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/card"
},
{
"No": "11",
"Category": "Dialog",
"Guideline": "Use Dialog for modal content",
"Description": "Dialog component for overlay modal windows",
"Do": "Dialog for confirmations forms details",
"Don't": "Alert for modal content",
"Code Good": "<Dialog><DialogContent>",
"Code Bad": "<Alert> styled as modal",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/dialog"
},
{
"No": "12",
"Category": "Dialog",
"Guideline": "Handle dialog state properly",
"Description": "Use open and onOpenChange for controlled dialogs",
"Do": "Controlled state with useState",
"Don't": "Uncontrolled with default open only",
"Code Good": "<Dialog open={open} onOpenChange={setOpen}>",
"Code Bad": "<Dialog defaultOpen={true}>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/dialog"
},
{
"No": "13",
"Category": "Dialog",
"Guideline": "Include proper dialog structure",
"Description": "Use DialogHeader DialogTitle DialogDescription",
"Do": "Complete semantic structure",
"Don't": "Missing title or description",
"Code Good": "<DialogHeader><DialogTitle><DialogDescription>",
"Code Bad": "<DialogContent><p>Content</p></DialogContent>",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/dialog"
},
{
"No": "14",
"Category": "Sheet",
"Guideline": "Use Sheet for side panels",
"Description": "Sheet component for slide-out panels and drawers",
"Do": "Sheet for navigation filters settings",
"Don't": "Dialog for side content",
"Code Good": "<Sheet side=\"right\">",
"Code Bad": "<Dialog> with slide animation",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/sheet"
},
{
"No": "15",
"Category": "Sheet",
"Guideline": "Specify sheet side",
"Description": "Set side prop for sheet slide direction",
"Do": "Explicit side=\"left\" or side=\"right\"",
"Don't": "Default side without consideration",
"Code Good": "<Sheet><SheetContent side=\"left\">",
"Code Bad": "<Sheet><SheetContent>",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/sheet"
},
{
"No": "16",
"Category": "Form",
"Guideline": "Use Form with react-hook-form",
"Description": "Integrate Form component with react-hook-form for validation",
"Do": "useForm + Form + FormField pattern",
"Don't": "Custom form handling without Form",
"Code Good": "<Form {...form}><FormField control={form.control}>",
"Code Bad": "<form onSubmit={handleSubmit}>",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/form"
},
{
"No": "17",
"Category": "Form",
"Guideline": "Use FormField for inputs",
"Description": "Wrap inputs in FormField for proper labeling and errors",
"Do": "FormField + FormItem + FormLabel + FormControl",
"Don't": "Input without FormField wrapper",
"Code Good": "<FormField><FormItem><FormLabel><FormControl><Input>",
"Code Bad": "<Input onChange={...}>",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/form"
},
{
"No": "18",
"Category": "Form",
"Guideline": "Display form messages",
"Description": "Use FormMessage for validation error display",
"Do": "FormMessage after FormControl",
"Don't": "Custom error text without FormMessage",
"Code Good": "<FormControl><Input/></FormControl><FormMessage/>",
"Code Bad": "<Input/>{error && <span>{error}</span>}",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/form"
},
{
"No": "19",
"Category": "Form",
"Guideline": "Use Zod for validation",
"Description": "Define form schema with Zod for type-safe validation",
"Do": "zodResolver with form schema",
"Don't": "Manual validation logic",
"Code Good": "zodResolver(formSchema)",
"Code Bad": "validate: (values) => { if (!values.email) }",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/form"
},
{
"No": "20",
"Category": "Select",
"Guideline": "Use Select for dropdowns",
"Description": "Select component for option selection",
"Do": "Select for choosing from list",
"Don't": "Native select element",
"Code Good": "<Select><SelectTrigger><SelectContent>",
"Code Bad": "<select><option>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/select"
},
{
"No": "21",
"Category": "Select",
"Guideline": "Structure Select properly",
"Description": "Include Trigger Value Content and Items",
"Do": "Complete Select structure",
"Don't": "Missing SelectValue or SelectContent",
"Code Good": "<SelectTrigger><SelectValue/></SelectTrigger><SelectContent><SelectItem>",
"Code Bad": "<Select><option>",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/select"
},
{
"No": "22",
"Category": "Command",
"Guideline": "Use Command for search",
"Description": "Command component for searchable lists and palettes",
"Do": "Command for command palette search",
"Don't": "Input with custom dropdown",
"Code Good": "<Command><CommandInput><CommandList>",
"Code Bad": "<Input><div className=\"dropdown\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/command"
},
{
"No": "23",
"Category": "Command",
"Guideline": "Group command items",
"Description": "Use CommandGroup for categorized items",
"Do": "CommandGroup with heading for sections",
"Don't": "Flat list without grouping",
"Code Good": "<CommandGroup heading=\"Suggestions\"><CommandItem>",
"Code Bad": "<CommandItem> without groups",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/command"
},
{
"No": "24",
"Category": "Table",
"Guideline": "Use Table for data display",
"Description": "Table component for structured data",
"Do": "Table for tabular data display",
"Don't": "Div grid for table-like layouts",
"Code Good": "<Table><TableHeader><TableBody><TableRow>",
"Code Bad": "<div className=\"grid\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/table"
},
{
"No": "25",
"Category": "Table",
"Guideline": "Include proper table structure",
"Description": "Use TableHeader TableBody TableRow TableCell",
"Do": "Semantic table structure",
"Don't": "Missing thead or tbody",
"Code Good": "<TableHeader><TableRow><TableHead>",
"Code Bad": "<Table><TableRow> without header",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/table"
},
{
"No": "26",
"Category": "DataTable",
"Guideline": "Use DataTable for complex tables",
"Description": "Combine Table with TanStack Table for features",
"Do": "DataTable pattern for sorting filtering pagination",
"Don't": "Custom table implementation",
"Code Good": "useReactTable + Table components",
"Code Bad": "Custom sort filter pagination logic",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/data-table"
},
{
"No": "27",
"Category": "Tabs",
"Guideline": "Use Tabs for content switching",
"Description": "Tabs component for tabbed interfaces",
"Do": "Tabs for related content sections",
"Don't": "Custom tab implementation",
"Code Good": "<Tabs><TabsList><TabsTrigger><TabsContent>",
"Code Bad": "<div onClick={() => setTab(...)}",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/tabs"
},
{
"No": "28",
"Category": "Tabs",
"Guideline": "Set default tab value",
"Description": "Specify defaultValue for initial tab",
"Do": "defaultValue on Tabs component",
"Don't": "No default leaving first tab",
"Code Good": "<Tabs defaultValue=\"account\">",
"Code Bad": "<Tabs> without defaultValue",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/tabs"
},
{
"No": "29",
"Category": "Accordion",
"Guideline": "Use Accordion for collapsible",
"Description": "Accordion for expandable content sections",
"Do": "Accordion for FAQ settings panels",
"Don't": "Custom collapse implementation",
"Code Good": "<Accordion><AccordionItem><AccordionTrigger>",
"Code Bad": "<div onClick={() => setOpen(!open)}>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/accordion"
},
{
"No": "30",
"Category": "Accordion",
"Guideline": "Choose accordion type",
"Description": "Use type=\"single\" or type=\"multiple\" appropriately",
"Do": "type=\"single\" for one open type=\"multiple\" for many",
"Don't": "Default type without consideration",
"Code Good": "<Accordion type=\"single\" collapsible>",
"Code Bad": "<Accordion> without type",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/accordion"
},
{
"No": "31",
"Category": "Toast",
"Guideline": "Use Sonner for toasts",
"Description": "Sonner integration for toast notifications",
"Do": "toast() from sonner for notifications",
"Don't": "Custom toast implementation",
"Code Good": "toast(\"Event created\")",
"Code Bad": "setShowToast(true)",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/sonner"
},
{
"No": "32",
"Category": "Toast",
"Guideline": "Add Toaster to layout",
"Description": "Include Toaster component in root layout",
"Do": "<Toaster /> in app layout",
"Don't": "Toaster in individual pages",
"Code Good": "app/layout.tsx: <Toaster />",
"Code Bad": "page.tsx: <Toaster />",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/sonner"
},
{
"No": "33",
"Category": "Toast",
"Guideline": "Use toast variants",
"Description": "Apply toast.success toast.error for context",
"Do": "Semantic toast methods",
"Don't": "Generic toast for all messages",
"Code Good": "toast.success(\"Saved!\") toast.error(\"Failed\")",
"Code Bad": "toast(\"Saved!\") toast(\"Failed\")",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/sonner"
},
{
"No": "34",
"Category": "Popover",
"Guideline": "Use Popover for floating content",
"Description": "Popover for dropdown menus and floating panels",
"Do": "Popover for contextual actions",
"Don't": "Absolute positioned divs",
"Code Good": "<Popover><PopoverTrigger><PopoverContent>",
"Code Bad": "<div className=\"relative\"><div className=\"absolute\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/popover"
},
{
"No": "35",
"Category": "Popover",
"Guideline": "Handle popover alignment",
"Description": "Use align and side props for positioning",
"Do": "Explicit alignment configuration",
"Don't": "Default alignment for all",
"Code Good": "<PopoverContent align=\"start\" side=\"bottom\">",
"Code Bad": "<PopoverContent>",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/popover"
},
{
"No": "36",
"Category": "DropdownMenu",
"Guideline": "Use DropdownMenu for actions",
"Description": "DropdownMenu for action lists and context menus",
"Do": "DropdownMenu for user menu actions",
"Don't": "Popover for action lists",
"Code Good": "<DropdownMenu><DropdownMenuTrigger><DropdownMenuContent>",
"Code Bad": "<Popover> for menu actions",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/dropdown-menu"
},
{
"No": "37",
"Category": "DropdownMenu",
"Guideline": "Group menu items",
"Description": "Use DropdownMenuGroup and DropdownMenuSeparator",
"Do": "Organized menu with separators",
"Don't": "Flat list of items",
"Code Good": "<DropdownMenuGroup><DropdownMenuItem><DropdownMenuSeparator>",
"Code Bad": "<DropdownMenuItem> without organization",
"Severity": "Low",
"Docs URL": "https://ui.shadcn.com/docs/components/dropdown-menu"
},
{
"No": "38",
"Category": "Tooltip",
"Guideline": "Use Tooltip for hints",
"Description": "Tooltip for icon buttons and truncated text",
"Do": "Tooltip for additional context",
"Don't": "Title attribute for tooltips",
"Code Good": "<Tooltip><TooltipTrigger><TooltipContent>",
"Code Bad": "<button title=\"Delete\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/tooltip"
},
{
"No": "39",
"Category": "Tooltip",
"Guideline": "Add TooltipProvider",
"Description": "Wrap app or section in TooltipProvider",
"Do": "TooltipProvider at app level",
"Don't": "TooltipProvider per tooltip",
"Code Good": "<TooltipProvider><App/></TooltipProvider>",
"Code Bad": "<Tooltip><TooltipProvider>",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/tooltip"
},
{
"No": "40",
"Category": "Skeleton",
"Guideline": "Use Skeleton for loading",
"Description": "Skeleton component for loading placeholders",
"Do": "Skeleton matching content layout",
"Don't": "Spinner for content loading",
"Code Good": "<Skeleton className=\"h-4 w-[200px]\"/>",
"Code Bad": "<Spinner/> for card loading",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/skeleton"
},
{
"No": "41",
"Category": "Skeleton",
"Guideline": "Match skeleton dimensions",
"Description": "Size skeleton to match loaded content",
"Do": "Skeleton same size as expected content",
"Don't": "Generic skeleton size",
"Code Good": "<Skeleton className=\"h-12 w-12 rounded-full\"/>",
"Code Bad": "<Skeleton/> without sizing",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/skeleton"
},
{
"No": "42",
"Category": "AlertDialog",
"Guideline": "Use AlertDialog for confirms",
"Description": "AlertDialog for destructive action confirmation",
"Do": "AlertDialog for delete confirmations",
"Don't": "Dialog for confirmations",
"Code Good": "<AlertDialog><AlertDialogTrigger><AlertDialogContent>",
"Code Bad": "<Dialog> for delete confirmation",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/alert-dialog"
},
{
"No": "43",
"Category": "AlertDialog",
"Guideline": "Include action buttons",
"Description": "Use AlertDialogAction and AlertDialogCancel",
"Do": "Standard confirm/cancel pattern",
"Don't": "Custom buttons in AlertDialog",
"Code Good": "<AlertDialogCancel>Cancel</AlertDialogCancel><AlertDialogAction>",
"Code Bad": "<Button>Cancel</Button><Button>Confirm</Button>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/alert-dialog"
},
{
"No": "44",
"Category": "Sidebar",
"Guideline": "Use Sidebar for navigation",
"Description": "Sidebar component for app navigation",
"Do": "Sidebar for main app navigation",
"Don't": "Custom sidebar implementation",
"Code Good": "<SidebarProvider><Sidebar><SidebarContent>",
"Code Bad": "<div className=\"w-64 fixed\">",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/sidebar"
},
{
"No": "45",
"Category": "Sidebar",
"Guideline": "Wrap in SidebarProvider",
"Description": "Use SidebarProvider for sidebar state management",
"Do": "SidebarProvider at layout level",
"Don't": "Sidebar without provider",
"Code Good": "<SidebarProvider><Sidebar></SidebarProvider>",
"Code Bad": "<Sidebar> without provider",
"Severity": "High",
"Docs URL": "https://ui.shadcn.com/docs/components/sidebar"
},
{
"No": "46",
"Category": "Sidebar",
"Guideline": "Use SidebarTrigger",
"Description": "Include SidebarTrigger for mobile toggle",
"Do": "SidebarTrigger for responsive toggle",
"Don't": "Custom toggle button",
"Code Good": "<SidebarTrigger/>",
"Code Bad": "<Button onClick={() => toggleSidebar()}>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/sidebar"
},
{
"No": "47",
"Category": "Chart",
"Guideline": "Use Chart for data viz",
"Description": "Chart component with Recharts integration",
"Do": "Chart component for dashboards",
"Don't": "Direct Recharts without wrapper",
"Code Good": "<ChartContainer config={chartConfig}>",
"Code Bad": "<ResponsiveContainer><BarChart>",
"Severity": "Medium",
"Docs URL": "https://ui.shadcn.com/docs/components/chart"
}
]
