# Shadcn UI Use shadcn when an artifact needs working controls: dialogs, menus, forms, tables, calendars, tabs. The kit is in every project as `kits/shadcn`; import any component or helper by name: ```jsx import { Button, Dialog, DialogContent, DialogTrigger, cn } from "@kits/shadcn"; ``` The installed kit's `kits/shadcn/docs/components.md` lists every export by component, and each component's source sits in `kits/shadcn/src/`. Runtime: React 18, Tailwind 3.4, Recharts 2.15, DayPicker 9.8, Embla 8.6, Sonner 1.7, React Hook Form 7, Zod 3, and Lucide 0.577. ## Principles 1. **Shadcn supplies behavior, never identity.** Build expressive surfaces such as heroes, landing pages, and decks in your own layout; use shadcn where a control needs its interaction mechanics. Derive its theme from the artifact's design plan by overriding the CSS variables in any imported CSS file: ```css :root { --primary: #147d64; --accent: oklch(82% 0.12 72); --radius: 0; } ``` 2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table. Combobox = Popover + Command. 3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc. 4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`. These Tailwind utilities are wired to the theme tokens and work in your own layout too. ## Rules Styling: - **`className` for layout, not styling.** Theme through tokens; never override component colors or typography per instance. - **No `space-x-*`/`space-y-*`.** Use `flex` with `gap-*`; vertical stacks are `flex flex-col gap-*`. - **`size-10`, not `w-10 h-10`.** And `truncate`, not the three-class ellipsis combo. - **`cn()` for conditional classes**, not template-literal ternaries. - **No manual `z-index` on overlays.** Dialog, Sheet, Popover handle their own stacking. Forms: - **Form layout uses `FieldGroup` + `Field`** with `FieldLabel`, `FieldDescription`, `FieldError` — never raw `div`s with `space-y-*`: ```jsx Email We never share it. ``` - **`FieldSet` + `FieldLegend`** for grouping related checkboxes/radios. - **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`**, never raw `Input` inside; buttons and affixes inside inputs use `InputGroupAddon`. - **Option sets of 2–7 choices use `ToggleGroup`**, not looped `Button`s with manual active state. Composition: - **Items always inside their Group.** `SelectItem` → `SelectGroup`, `DropdownMenuItem` → `DropdownMenuGroup`, `CommandItem` → `CommandGroup`, `TabsTrigger` → `TabsList`. - **Custom triggers use `asChild`.** - **Dialog, Sheet, and Drawer always need a Title** (`className="sr-only"` if visually hidden). - **Use full Card composition** — `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`, not everything dumped in `CardContent`. - **Button has no `isLoading`.** Compose `Spinner` + `disabled`. - **Icons come from `lucide-react`.** Inside buttons they need no sizing classes; the component sizes them. - **`Avatar` always needs `AvatarFallback`.** - **Components before custom markup.** Callouts are `Alert`, empty states are `Empty`, loading placeholders are `Skeleton`, dividers are `Separator`, status labels are `Badge`, toasts are `toast()` from `sonner` with one `` rendered. ## Component Selection | Need | Use | | -------------------------- | --------------------------------------------------------------------------------------- | | Button/action | `Button` with appropriate variant, `ButtonGroup` | | Form inputs | `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `InputOTP`, `Calendar` | | Toggle between 2–7 options | `ToggleGroup` + `ToggleGroupItem` | | Data display | `Table`, `Card`, `Badge`, `Avatar`, `Item`, `Kbd` | | Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` | | Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) | | Feedback | `toast()` from `sonner`, `Alert`, `Progress`, `Skeleton`, `Spinner`, `Empty` | | Command palette | `Command` inside `Dialog` | | Charts | `ChartContainer` + Recharts primitives | | Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`, `AspectRatio` | | Menus | `DropdownMenu`, `ContextMenu`, `Menubar` | | Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |