shadcn-ui-Claude-Skill-Package

Use when running any shadcn CLI command (init, add, view, search, apply, preset, build, docs, info, migrate), when writing or editing components.json, when choosing between tsconfig path aliases and package.json#imports aliases (new in shadcn@4.7.0), when wiring a custom or private registry, or when a shadcn invocation overwrote local component edits unexpectedly. Prevents the silent-overwrite trap from running `add` without `--diff` after local modifications, the "Cannot find baseColor" failure from a malformed components.json, the registry-resolution miss from forgetting the `{name}` placeholder, and the immutable-field surprise from trying to change `style`, `baseColor`, or `cssVariables` after init. Covers every CLI command and flag, the complete components.json schema, registry resolution semantics, and the package.json#imports alternative to tsconfig paths. Keywords: shadcn cli, npx shadcn add, pnpm dlx shadcn, shadcn init, shadcn diff, shadcn update, shadcn migrate, shadcn migrate icons, shadcn migrate

Use when adding a new component to a project that already uses shadcn, when bootstrapping shadcn for the first time in a fresh app, when deciding between `shadcn add`, a hand-built primitive, or a pre-built block, when wiring path aliases (tsconfig paths or the new package.json#imports resolver from shadcn@4.7.0), when re-running `add` against a file you have already customised, or when an `add` invocation has surfaced broken imports or missing radix dependencies. Prevents the silent-overwrite destruction from running `add --overwrite` without `--diff` first, the broken-imports trap from running `add` before `init`, the alias-mismatch bug where `tsconfig` paths and `components.json` aliases disagree, the bypass-the-CLI mistake of pip-installing `@radix-ui/react-*` packages by hand instead of letting `add` resolve them, and the long-tail stale-code problem from never re-running the CLI after upstream bug fixes ship. Covers the full add-or-customise-or-block decision tree, the init-then-add-then-customise workf

Use when authoring or consuming a shadcn registry, when configuring the `registries` field in components.json, when wiring a private or paid component library behind a namespace prefix like `@myorg/datepicker`, when securing a custom registry with bearer tokens or API keys, when hosting a `registry.json` plus per-item JSON files, or when explaining why the `style`, `baseColor`, or `cssVariables` fields cannot be changed after `init`. Prevents the missing-`{name}`-placeholder trap that breaks every namespace install, the committed-secret leak from inlining an API key instead of using `${ENV_VAR}` expansion, the alias-mismatch silent failure from setting `aliases.components` to one path while imports reference another, the immutable-field surprise from editing `style`/`baseColor`/`cssVariables` post-init, and the Tailwind v3-vs-v4 config-shape confusion. Covers every components.json field in depth (purpose, constraints, defaults, immutability), the URL-template syntax with `{name}` and `{style}` placeholders, e

Use when a shadcn ui Command primitive (command palette, Combobox, search list, fuzzy filter, multi-select dropdown) stops filtering, renders the full list regardless of typing, fails to highlight or click items, throws "TypeError : undefined is not iterable (cannot read property Symbol(Symbol.iterator))" on a CommandItem rendered outside CommandList, silently ignores a third `keywords` argument passed to the `filter` prop, no longer matches values typed in uppercase, loses keyboard focus inside a Vaul Drawer, returns zero results despite `shouldFilter={false}`, or fails to import `CommandLoading` from the shadcn wrapper. Prevents the six recurring drift traps : (1) writing a 2-arg `(value, search) => number` filter against cmdk >= 1.0.0 where the signature is `(value, search, keywords) => number` so the third argument is silently dropped and per-item `keywords` boosting never fires, (2) writing a custom `filter` that does a case-sensitive `===` or `includes` check against raw `value` and raw `search` so that

Use when initializing shadcn ui inside a Vite, Next.js (App or Pages Router), React Router v7 (former Remix), Astro, or TanStack Start project, or when diagnosing per-framework init issues like wrong rsc flag, broken `@/*` alias resolution, or missing ThemeProvider wiring. Prevents the recurring failure mode where the CLI is run with the wrong `-t` template and produces a `components.json` whose `rsc` value mismatches the framework's RSC capability, silently dropping `"use client"` directives in Vite or duplicating them in Next.js. Covers per-framework init commands, the four alias-resolution systems (tsconfig paths for Next/Vite/React-Router, package.json#imports for TanStack Start, astro.config + tsconfig for Astro), components.json defaults per framework, Tailwind v3 vs v4 wiring per framework, and the three distinct ThemeProvider patterns (next-themes for Next.js, custom React Context for Vite/React-Router/TanStack Start, inline script for Astro). Keywords: shadcn vite, shadcn nextjs, shadcn nextjs app ro

Use when reviewing, validating, or auditing a shadcn ui component that uses class-variance-authority (cva), when an LLM has just produced a Button-like, Badge-like, Alert-like, or any other cva-driven component and you must verify the variant API before accepting the diff, when a consumer className does not visually win and you suspect cva merge order or a missing cn() call, when extending an existing shadcn component with a new variant or compoundVariant and you want a deterministic checklist before commit, when porting a hand-written variants-via-if-branches component to cva, when writing a custom primitive that should follow the shadcn convention, when verifying that VariantProps inference is exported so consumers can extend the component type, or when running a code-review pass on AI-generated cva code to catch the canonical mistakes (nested cn inside cva, compoundVariants placed before variants, missing defaultVariants, raw className concatenation, asChild without Slot, variant key typos that silently di

Use when validating a react-hook-form + zod + shadcn Form integration in a code review, a draft AI-generated form, or a bug report ("my validation does not trigger", "the error message never shows", "the Select does not bind", "submit fires but values are undefined", "the field reads as uncontrolled then controlled"), when auditing whether a zod schema and a shadcn Form composition agree on every field name, when verifying Controller-vs-register correctness for custom controls (Select, Checkbox, RadioGroup, Switch, DatePicker, Combobox), when confirming every FormField has a FormMessage so zod errors are visible to the user, when checking that defaultValues covers every schema key (no undefined-to-string controlled / uncontrolled warning), when verifying the submit handler is wrapped in form.handleSubmit, when checking that zodResolver is actually passed to useForm, when ensuring no nested FormProvider / shadcn Form context is duplicated, and when emitting a structured pass / fail verdict over a form code blo

Use when auditing a Next.js App Router codebase that consumes shadcn ui for misplaced or missing `"use client"` directives, when reviewing a pull request that adds shadcn primitives and you must confirm the boundary is correct before merging, when a build fails with the `useState is not a function` / `Cannot read properties of null (reading useContext)` Radix hydration crash, when `components.json` has been edited (toggled `rsc:true` <-> `rsc:false`, or added to a Vite / Astro / Pages-Router project where the flag must be `false`), when an AI-generated patch has slapped `"use client"` on `app/layout.tsx` or on every component file, when a Server Component tries to pass `onClick` / `onChange` / a class instance into a client child, when a Provider (next-themes ThemeProvider, TanStack Query QueryClientProvider, jotai Provider, zustand Provider, Sonner Toaster) has been imported directly into a server layout instead of through a thin client wrapper, or when a code-review checklist must enforce the RSC boundary r

Use when a user describes a UI requirement in plain English ("a modal to edit a record", "a searchable dropdown of countries", "show a non-blocking success message", "a right-click menu on a table row", "a sortable table of users") and the correct shadcn primitive is not yet obvious, when an existing implementation picks the wrong shadcn component for the interaction model ("Dialog used as a mobile bottom-sheet", "Select used for a 200-item searchable list", "Tooltip used for content with a link inside", "Toast (Sonner) used for a destructive confirmation"), when validating a code-review or AI-generated draft against the shadcn component catalogue, when choosing between Dialog vs Sheet vs Drawer, Select vs Combobox vs Command, DropdownMenu vs ContextMenu vs Menubar vs NavigationMenu, Tooltip vs HoverCard vs Popover, Button vs Link vs asChild composition, Toast (Sonner) vs Alert vs AlertDialog, Card vs Skeleton vs Spinner for loading states, Form (react-hook-form) vs Field (new 2026 primitive) for form composi

Use when a shadcn `Calendar` (or any direct `react-day-picker` DayPicker) silently renders nothing, throws a TypeScript error on the `selected` prop, loses every CSS rule after a `react-day-picker` upgrade, shows an unstyled grid of buttons, fails to compile a custom `Caption` / `Day` / `IconLeft` / `IconRight` component, fires a Matcher warning for `disabledDays`, ignores `selectedDays` entirely, throws "DayPickerProps is not a function" or "Cannot read properties of undefined (reading 'mode')", crashes after `npm install react-day-picker@9` on a code base that pre-dates the v9 release, or no longer responds to the `fromMonth` / `toMonth` boundary props. Prevents the v8 syntax in v9 trap (the file compiles but the calendar is read-only, invisible, or unstyled because every prop name moved), the missing `mode` prop trap (v9 makes `mode` mandatory on every `selected` usage and TypeScript fails the type narrowing), the classNames-with-old-keys trap (v9 keys every entry by a `UI` enum string like `day_button` /

Use when a shadcn Form built on react-hook-form silently submits with missing values, when a Radix Select or Checkbox or RadioGroup or Switch never updates form state, when FormMessage refuses to render the zod error, when the console logs "A component is changing an uncontrolled input to be controlled" on first keystroke, when the entire form re-renders on every character typed, when an async zod refine never blocks submission, when handleSubmit fires with no validation, when formState.isDirty or formState.isValid stays stuck at false, when reset() does not clear errors, when a file input loses its FileList after the first render, when a server validation response should light up specific field errors, when defaultValues is partially specified and some fields jump from uncontrolled to controlled, or when a typo in the zod schema field path causes a field to never validate without warning. Prevents the six recurring react-hook-form failures inside shadcn Form composition : using register on a non-native contr

Use when a shadcn Dialog / Sheet / Drawer / DropdownMenu / Popover / HoverCard / Select / AlertDialog / ContextMenu / Collapsible / Accordion / Tabs is stuck open, refuses to close, never opens, fires `onOpenChange` at unexpected times, drops focus after a form submit, crashes with "React.Children.only expected to receive a single child" when wrapped in `asChild`, renders behind another element with higher z-index, anchors its popper to the wrong position inside a `transform`ed parent, traps focus inside the wrong container, or swallows the Escape key. Prevents the half-controlled state trap (passing `open` without `onOpenChange` makes the primitive read-only and uncloseable), the `asChild` Slot crash (Slot accepts exactly one child and that child MUST forward refs), the `asChild` silent-prop- swallow (a `<div>` child ignores `onClick` and `aria-*` that Slot forwards), the Portal stacking-context trap (a `transform` / `filter` / `perspective` / `will-change` ancestor reroots the popper coordinate system), the

Use when a shadcn ui project must move from Tailwind CSS v3 to v4, when colors break or look washed out after a Tailwind upgrade, when the dark mode toggle stops applying after switching the stylesheet, when `bg-background` renders transparent instead of the theme color, when `tailwindcss-animate` is missing in `package.json` but components still try to animate, when the Tailwind build emits "unknown at-rule @theme" or "unknown at-rule @custom-variant", when `tailwind.config.js` is still present in a project that imports the v4 stylesheet, when ring outlines on Button or Input changed thickness after the upgrade, when PostCSS fails with "tailwindcss is not a PostCSS plugin", or when AI-generated code mixes v3 syntax (`@tailwind base`, `hsl(var(--background))`, `darkMode: ['class']`) with v4 syntax (`@import "tailwindcss"`, `oklch()`, `@custom-variant dark`) in the same file. Prevents the canonical migration bugs: keeping `tailwind.config.js` alongside `@theme inline` so two config sources fight, leaving HSL s

Use when re-running `shadcn add <component>` would overwrite a file in `components/ui/` that you have edited locally, when a teammate reports that "the CLI wiped my changes", when deciding whether to update a shadcn component to pick up upstream fixes (Calendar v9, cmdk break, security patch) without losing custom variants, or when you need a deterministic strategy to keep custom code alive across `--overwrite` runs. Prevents the silent-destruction trap where `pnpm dlx shadcn@latest add button --overwrite` blasts local edits with zero confirmation, the miss-the-upstream-fix trap where teams freeze a component and stop receiving critical patches, and the inline-custom-variants trap where edits embedded directly in `components/ui/<name>.tsx` are unrecoverable after a re-add. Covers the diff-first workflow with `add --diff`, the three resolution strategies (vendor / diff-merge / fork), the custom-variants-in-a-separate-file pattern that survives any re-add, pre-update git hygiene, the `migrate icons` and `migrat

Use when a className override on a shadcn component does not visually take effect, when two Tailwind utility classes appear in the rendered DOM but only one applies, when a cva variant looks correct in code but the consumer className does not win, when porting code from Tailwind v3 to v4 and class semantics shift, when adding arbitrary values (bg-[#fff], size-[28px]) next to preset utilities, when the important modifier (! prefix in v3, suffix in v4) behaves unexpectedly, when a component built with cva looks unstyled or doubled-up, or when reviewing PRs that build className strings with template literals or string concatenation. Prevents the canonical class-merging bugs: skipping cn() so duplicates leak through the DOM, calling cn() inside cva (no-op since cva already runs clsx), assuming the important modifier always overrides plain utilities, mixing arbitrary properties with their preset equivalents, and applying v3-only class names in a v4 project. Covers the cn() helper rule (clsx + tailwind-merge wrappe

Use when building a modal surface that must look correct on both desktop and mobile in shadcn ui, when the design calls for a centered Dialog on large screens but a bottom-sheet Drawer on phones, when the user reports that the current Dialog feels cramped on a phone or that the on-screen keyboard covers the form fields, when wiring a delete-confirmation, edit-profile, filter-panel, share-sheet, or settings modal that must respect platform conventions (native swipe-down dismiss on iOS / Android), when building a responsive Combobox where the dropdown must become a full-height Drawer on mobile, when porting an existing Dialog to also work well on touch devices, or when the user asks "how do I make a responsive modal". Prevents the recurring failure modes of an ad-hoc responsive modal: rendering BOTH the Dialog and the Drawer simultaneously so two open surfaces appear at once and the ARIA tree has duplicate role=dialog nodes, calling useMediaQuery without an SSR guard so Next.js logs a hydration mismatch on ever

Use when wiring shadcn components into a Next.js App Router project, when deciding whether a given shadcn primitive needs a `"use client"` directive, when seeing the "Error: useState is not a function" or "Cannot read properties of null (reading useContext)" hydration errors from a Radix primitive in a server component, when designing the server-shell-plus-client-island layout for a page, when wrapping a context-providing library (next-themes, TanStack Query, jotai, zustand) for the App Router, or when the `rsc` field in `components.json` is set but the generated component file is still missing the directive. Prevents the over-clientification anti-pattern of marking the whole layout `"use client"` (defeats the streaming + RSC bundle savings of App Router), the missing-directive crash where a Radix-state component (Dialog, Select, Sidebar) renders on the server and throws `useState is not a function`, the forgotten Provider wrapper where next-themes ThemeProvider is imported directly into a server layout and c

Use when building or customizing a theme in a shadcn ui project, wiring the dark mode toggle, replacing the default primary color with a brand color, copying the output of the ui.shadcn.com themes builder into globals.css, or overriding the styling of one specific component instance without touching the global tokens. This is the end-to-end workflow recipe : the token catalog, oklch versus HSL format split, and v3 versus v4 wiring rules live in shadcn-core-theming. Prevents the flash-of-unstyled-content on first paint that comes from a missing suppressHydrationWarning, the silent "bg-primary did not change" symptom that comes from editing tokens without re-running the dev server, the two-ThemeProvider double-mount that breaks the toggle, the next-themes attribute mismatch that disables Tailwind's dark variants, and the brand-color contrast trap that ships an inaccessible palette. Covers the three-step theme-builder workflow (pick base style and radius, pick primary, copy CSS), the Tailwind v3 globals.css plus

Use when building any sortable, filterable, paginated, selectable, or column-toggleable table in shadcn ui : the official shadcn DataTable is NOT a primitive component but a documented recipe that composes TanStack Table v8 (@tanstack/react-table) with the shadcn Table primitive. Use this skill any time the task involves columns of data, row selection with bulk actions, pagination of a list, server-side data loading with sorting or filtering, column-visibility toggles, or resizable columns. Prevents the recurring bugs : forgetting getCoreRowModel and getting zero rows, mixing client-side and server-side state so sorting fires twice, missing getRowId so row-selection keys collide, setting manualPagination without pageCount so pagination breaks, forgetting 'use client' on the DataTable component, defining a ColumnDef without accessorKey or accessorFn so cells render undefined, and importing TanStack helpers from the wrong package. Covers the ColumnDef typing pattern, the useReactTable hook composition, the six

Use when building an end-to-end form workflow in shadcn ui that combines the Form composition primitives with react-hook-form and zod, when wiring the full pipeline from zod schema to typed submit handler to server-error display, when adding async validation (email availability, username taken, coupon check), when surfacing API errors back to a specific field via setError, when toggling a submit button between idle, submitting, success, and disabled states, when resetting a form after successful submit to clear stale state, when building a multi-step wizard that preserves form state across pages, or when wiring a file upload control into the react-hook-form value tree. Prevents the common end-to-end form failures: defining the zod schema inside the component so the resolver re-creates every render, mixing schema validation with manual setError on the same field so the two systems race and the user sees flickering error text, omitting form.handleSubmit on the form element so the browser submits natively and re

Use when building a one-time-password, verification-code, MFA, two-factor, SMS-code, or PIN-entry input in shadcn ui evergreen-2026, when composing InputOTP, InputOTPGroup, InputOTPSlot, and InputOTPSeparator, when wiring a 6-digit numeric code, a 4-digit PIN, or an alphanumeric token, when enabling iOS and Android SMS autofill via autoComplete one-time-code, when handling paste of a full code in one operation, when constraining allowed characters via the pattern prop, when reacting to a fully entered code via onComplete, when integrating an OTP input with react-hook-form Controller, or when an OTP renders as a single empty input with no slots visible. Prevents the common Input OTP failures : omitting maxLength so the underlying OTPInput renders zero slots and the user sees an empty box, forgetting the index prop on InputOTPSlot so every slot reads from the same context entry, passing a JavaScript RegExp object to the pattern prop instead of a regex source string or one of the exported constants, trying to re

Use when adding, debugging, or refactoring any of the four shadcn ui layout-helper primitives : Resizable (drag-to-resize split panes), ScrollArea (custom-styled scrollable region with a Radix scrollbar), Separator (horizontal or vertical divider), or AspectRatio (lock a container to a width:height ratio like 16/9, 1/1, 9/16). Composes the right subcomponents per primitive (ResizablePanelGroup / ResizablePanel / ResizableHandle ; ScrollArea / ScrollBar ; Separator with orientation + decorative ; AspectRatio with ratio), wires their prop surfaces against the underlying libraries (react-resizable-panels v4 for Resizable, Radix UI for ScrollArea / Separator / AspectRatio), and explains the `"use client"` story per primitive (all four ship with `"use client"` in the v4 registry source, contrary to the "pure-styling = server-safe" rumor). Prevents the canonical layout-helper failures : rendering a ResizablePanel outside a ResizablePanelGroup so react-resizable- panels crashes ("Panel components must be rendered wi

Use when building an application shell, dashboard navigation, admin sidebar, collapsible side navigation, or any persistent vertical navigation rail in shadcn ui. Prevents the common mistakes of rendering Sidebar outside a SidebarProvider (throws "useSidebar must be used within a SidebarProvider"), omitting the 'use client' directive on the layout that hosts the Provider, choosing the wrong collapsible variant for desktop versus mobile, placing SidebarInset without a sibling Sidebar (layout collapse), and skipping the cookie-based persistence handshake in server-rendered frameworks. Covers all 23 exported primitives (SidebarProvider, Sidebar, SidebarTrigger, SidebarRail, SidebarInset, SidebarInput, SidebarHeader, SidebarFooter, SidebarSeparator, SidebarContent, SidebarGroup, SidebarGroupLabel, SidebarGroupAction, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuAction, SidebarMenuBadge, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuSubButton) plus the useS

Use when adding, customising, or debugging a shadcn ui Calendar or Date Picker, choosing between the three react-day-picker v9 selection modes (single / multiple / range), typing the `selected` state and the `onSelect` callback for each mode (Date vs Date[] vs DateRange), wiring a DatePicker by composing Calendar inside a Popover with a Button trigger that formats the date via date-fns, localising the calendar to Dutch / German / French via the `dateLib` adapter, disabling specific dates with a `disabled` matcher or a date-fns predicate, styling the calendar via `classNames` + `modifiers` + `modifiersClassNames`, swapping the day renderer through the `components` prop, or migrating an existing Calendar file from react-day-picker v8 to v9 after running `shadcn add calendar --overwrite`. Prevents the canonical Calendar failures : omitting the required `mode` prop so TypeScript narrows `selected` to `undefined` and the calendar never marks any day as selected, importing v8-only props (`selectedDays`, `disabledDa

Use when building data visualizations with the shadcn Chart primitive that wraps Recharts (Bar, Line, Area, Pie, Radar, Scatter, RadialBar, Composed). Prevents the common mistake of using Recharts directly (loses shadcn theming), inlining hex colors (breaks dark mode), forgetting `'use client'` (RSC crash), or omitting `ChartConfig` (no CSS-var color generation). Covers the five wrappers (ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent), the `ChartConfig` type, the `--chart-1..5` and `var(--color-<dataKey>)` color convention, theme-aware light/dark color resolution, and per-chart-type Recharts composition. Keywords: shadcn chart, shadcn ui chart, recharts wrapper, ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartConfig, bar chart, line chart, area chart, pie chart, radar chart, scatter chart, stacked area chart, chart colors, theme-aware chart, --chart-1 css var, --color-dataKey, dark mode chart, how do I make a chart in shadcn, my cha

Use when adding, customising, or debugging the shadcn ui Table primitive (the eight subcomponents Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption), rendering a static, read-only table for product lists, invoice line-items, settings rows, metric summaries, or any tabular data that does NOT need sorting, filtering, pagination, or row selection, deciding between the styling primitive (this skill) and the TanStack-Table-driven DataTable recipe (shadcn-impl-data-table), composing a TableFooter sum row, adding a TableCaption for screen-reader access, dropping a shadcn Table inside a Card / Dialog / Drawer / Sheet surface, or diagnosing why a Table renders unstyled, breaks alignment, or refuses to scroll horizontally on mobile. Prevents the canonical Table-primitive failures : reaching for the Table primitive when the design actually needs sortable / filterable / paginated columns (those require the TanStack recipe in shadcn-impl-data-table, NOT this skill), shipping a Table

Use when adding, debugging, or refactoring any shadcn ui menu surface : DropdownMenu (button-triggered popup), ContextMenu (right-click on an area), Menubar (horizontal File / Edit / View desktop-app bar), or NavigationMenu (site-wide nav with viewport + mega-menu content). Picks the correct primitive family from the interaction model rather than from the visual shape, composes the shared Radix Menu surface (Root / Trigger / Content / Item / Group / Label / Separator / CheckboxItem / RadioGroup / RadioItem / Sub / SubTrigger / SubContent / Portal / Shortcut), and wires CheckboxItem / RadioGroup state, sub- menus, item shortcuts, and the special NavigationMenu surface (List / Item / Trigger / Content / Link / Indicator / Viewport). Prevents the canonical menu failures : stripping `"use client"` from the menu file so DropdownMenu / ContextMenu / Menubar break with a hydration error, reaching for DropdownMenu when the UX is a right- click context menu (or vice versa), nesting MenubarSeparator outside MenubarCont

Use when picking between Popover, Tooltip, and HoverCard for any floating panel above the page : a click-to-open form panel, a short hover hint on an icon button, a rich preview card that appears when the cursor lingers on a user mention, a date picker container, a filter popover, or any other "small panel anchored to an element" UX. Use when debugging why a Tooltip never appears (missing `TooltipProvider` at the app root), why a HoverCard flickers as the cursor passes over an avatar list (zero `openDelay`), why a Tooltip works on desktop but is invisible on iPad (Radix hides Tooltip on touch by design), why focus jumps to the body after a Popover closes (`modal={true}` focus-trap on a non-modal panel), or why a Popover refuses to close when controlled (passing `open` without `onOpenChange`). Use when choosing which primitive to install for an emoji-picker, a colour-picker, a notification preview, a profile-card preview on hover, a help-text hint on a form label, or a confirm-action popover. Prevents the cano

Use when adding, debugging, or migrating notification toasts in a shadcn ui project, mounting the top-level `<Toaster />` in your app root, calling `toast()` / `toast.success` / `toast.error` / `toast.warning` / `toast.info` / `toast.loading` / `toast.promise`, configuring the Toaster's `position`, `duration`, `expand`, `richColors`, or `closeButton` props, dismissing a toast programmatically via `toast.dismiss(id)`, wrapping a fetch / mutation with `toast.promise` for the loading -> success / error state machine, or removing dead `useToast()` hook calls left over from a pre-2026 shadcn project. Prevents the canonical toast failures : trying to import `useToast` from `@/components/ui/use-toast` (the file no longer exists ; the hook + the Radix-based Toast component were REMOVED per the shadcn 2026 changelog), calling `toast()` before any `<Toaster />` is mounted (the call is silently dropped), mounting two `<Toaster />` instances and getting duplicated stacks, calling `toast()` from inside a React Server Comp

Use when adding, debugging, or refactoring a shadcn ui Command primitive (the cmdk-backed command-palette / fuzzy-filter list), composing its nine parts (Command / CommandDialog / CommandInput / CommandList / CommandEmpty / CommandGroup / CommandItem / CommandSeparator / CommandShortcut), deciding between an inline Command surface and the modal CommandDialog wrapping, wiring the Cmd+K / Ctrl+K global hotkey via useEffect + keydown listener, switching from cmdk's built-in fuzzy filter to server-side / async filtering via `shouldFilter={false}` with externally-managed `items` state plus CommandLoading, providing a stable `value` prop on every CommandItem so cmdk can identify it for filtering and keyboard navigation, handling `onSelect: (value: string) => void` to route the user's choice, building a Combobox by rendering Command inside a Popover (the canonical shadcn recipe), or building nested / multi-page command palettes with sub-routes via a React-state `pages` stack. Prevents the canonical Command failures

Use when building a mobile-first bottom-sheet, swipe-to-dismiss panel, multi-stop drawer (snap points), or any sliding surface that enters from the bottom (default), top, left, or right edge of the viewport in shadcn ui. The Drawer is Vaul-backed (emilkowalski/vaul) and is a separate primitive family from Dialog and Sheet : it owns its own `Drawer / DrawerTrigger / DrawerPortal / DrawerOverlay / DrawerContent / DrawerHeader / DrawerFooter / DrawerTitle / DrawerDescription / DrawerClose` composition, exposes Vaul-only props (`snapPoints`, `shouldScaleBackground`, `setBackgroundColorOnScale`, `direction`, `dismissible`, `nested`, `handleOnly`, `closeThreshold`, `activeSnapPoint`, `onDrag`, `onRelease`), and is the documented half of the responsive Dialog-on-desktop / Drawer-on-mobile recipe. Prevents the canonical Drawer failures : omitting DrawerTitle (Radix Dialog a11y rule applies via Vaul ; axe-core flags the dialog as missing accessible name), reaching for Drawer on a desktop side-panel (Sheet is the corre

Use when picking the right "selector" primitive in a shadcn ui app and you are unsure whether to reach for a Native HTML `<select>`, a shadcn Select (Radix Select wrapped, 10 primitives), a Combobox recipe (Popover + Command composed by hand or the new 2026 Combobox primitive), or a Command palette (CommandDialog as a Cmd+K action launcher) ; covers the four-way decision criteria (list size, searchability, async loading, palette UX, mobile-native-picker need), the form-binding contract per selector (Native works with `register`, Radix Select and Combobox require `Controller`), the Combobox-as-recipe composition (Popover + Command + CommandInput + CommandList + CommandEmpty + CommandGroup + CommandItem), the Command-palette hotkey wiring (Cmd+K via `useEffect` + `keydown` listener), the async options pattern (server-fetched, loading state, empty state, error state), and the a11y wiring per selector (`aria-expanded` / `aria-controls` / `aria-activedescendant`). Prevents the canonical selector failures : binding

Use when adding, debugging, or refactoring a shadcn ui Dialog (a focus- trapped modal that overlays the page), composing its ten primitives (Dialog / DialogTrigger / DialogPortal / DialogOverlay / DialogContent / DialogHeader / DialogFooter / DialogTitle / DialogDescription / DialogClose), deciding between controlled (`open` + `onOpenChange`) and uncontrolled (`defaultOpen` or no state at all) operation, visually hiding the title with an sr-only span while keeping screen- reader compliance, closing the dialog after a form submit, swapping the default close button via `showCloseButton={false}` on DialogContent, retargeting the portal container, or wrapping a custom button via `<DialogClose asChild>`. Prevents the canonical Dialog failures : passing `open` without `onOpenChange` (the dialog becomes read-only and uncloseable), omitting DialogTitle (Radix dev-mode throws an a11y warning + axe flags it as critical), rendering DialogContent outside DialogPortal (z-index conflicts and stacking-context bugs in transf

Use when building forms in shadcn ui evergreen-2026 and the new Field primitive family is the recommended path, when composing Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet, FieldLegend, FieldContent, FieldSeparator, or FieldTitle, when wiring accessibility attributes (htmlFor, id, aria-invalid, aria-describedby) by hand around a controlled input, when integrating shadcn inputs with react-hook-form Controller WITHOUT the higher-level Form / FormField wrappers, when integrating with TanStack Form, when choosing between the older Form composition path and the newer Field path, or when an error message fails to render under a Field-wrapped input. Prevents the common Field failures : omitting FieldLabel htmlFor so the label does not focus the control, rendering FieldError outside its parent Field so data-invalid styling never applies, mixing Field with FormField in the same field tree, forgetting aria-invalid on the inner input so screen readers do not announce the error, and using Field a

Use when building a side panel, slide-in drawer, off-canvas navigation, filter panel, settings tray, or any container that enters from the top, right, bottom, or left edge of the viewport in shadcn ui. Prevents the common mistakes of omitting SheetTitle (Radix a11y violation), choosing Sheet on mobile where Drawer would feel native, using side="bottom" Sheet where Drawer is the documented mobile-first pattern, and overriding SheetContent styles in a way that breaks the slide-in animation. Covers the side prop (top, right, bottom, left), the eight exported primitives (Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription), controlled vs uncontrolled state (open + onOpenChange forwarded to the Radix Dialog primitive), showCloseButton prop on SheetContent, Sheet-vs-Dialog decision, and Sheet-vs-Drawer decision. Keywords: shadcn sheet, side panel, drawer-style dialog, SheetContent, SheetTitle, SheetTrigger, SheetClose, SheetDescription, navigation menu sheet, settin

Use when adding, customising, or debugging a shadcn ui Button, choosing between the six built-in variants (default / destructive / outline / secondary / ghost / link), choosing between the size variants (default / sm / lg / icon plus the v4-only xs / icon-xs / icon-sm / icon-lg), using the `asChild` Slot pattern to wrap a Next.js Link, a react-router Link, or any other custom anchor as the rendered button element, typing a Button-derived component with `VariantProps<typeof buttonVariants>`, building an icon-only button, building a loading button with a spinner, understanding the focus-ring difference between Tailwind v3 and v4 output, or diagnosing why a Button renders unstyled, ignores `className`, or crashes the page after `asChild` is added. Prevents the canonical Button-level failures : passing multiple children inside `<Button asChild>` (Slot.Root only accepts one), using `asChild` with a child that is not a forwardRef-compatible component, dropping an icon into `size="default"` instead of `size="icon"`

Use when building forms with shadcn ui and react-hook-form plus zod, when composing the seven Form primitives (Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage), when wiring zodResolver to useForm, when deciding between Controller and register for a given input type, when validation errors fail to render under a field, when an input value never reaches the submit handler, or when an input throws a "switched from uncontrolled to controlled" warning. Prevents the common form failures : using register on a non-native control (Select, Checkbox, RadioGroup, Switch) so its value never enters form-state, forgetting FormMessage so zod errors silently never render, defining the zod schema inside the component body so it re-creates every render and kills memoised resolver references, calling handleSubmit without wiring it to the form's onSubmit prop so validation never runs, omitting the outer Form spread so FormField cannot reach the form context, and setting defaultValues to undefined s

Use when defining or modifying variants on a shadcn ui component, writing a new component that needs `variant` / `size` props, extending the Button with a custom variant, debugging why a `className` override is not winning, or inferring TypeScript props from a `cva()` call. Prevents the common mistakes : concatenating Tailwind class strings with `+ " "` instead of `cn()`, forgetting `tailwind-merge` so duplicate utilities leak through, mis-ordering `compoundVariants` so the override loses to the default, omitting `VariantProps` so consumers cannot extend the component type, and re-implementing variant logic with hand-written `if`-branches that destroy type inference. Covers the full `cva(base, config)` signature (base as string or string array, `variants`, `compoundVariants`, `defaultVariants`), the `VariantProps<typeof X>` inference pattern, the canonical `cn(...inputs)` helper composition of `clsx` plus `twMerge`, the evaluation order (default then variant then compound), and the Radix `Slot` (`asChild`) po

Use when scaffolding a full page (dashboard, login, signup, sidebar layout, calendar app), bootstrapping a starter template from shadcn's gallery, evaluating block vs hand-composed components, choosing between the default / new-york / sera / luma styles, or recovering after a `shadcn add <block>` rerun overwrote local customisations. Prevents six common block-system failures : treating blocks as immutable starter templates (they are owned code, edit freely), running `shadcn add <block>` over a customised copy without `--diff` and losing work, mixing multiple style enum values inside one project, importing block sub-components from package paths instead of the local copied location, expecting blocks to auto-update when shadcn ships new revisions, and conflating blocks with components in CLI invocation when they accept different mental models for ownership and customisation. Covers the blocks distribution surface (a separate gallery at /blocks distinct from /components), block category landscape (dashboard, sid

Use when wiring shadcn ui colors, dark mode, the design-token palette, or migrating a project between Tailwind v3 and Tailwind v4, or when pasting theme output from https://ui.shadcn.com/themes into a project. Prevents the single largest source of AI-generated style bugs in shadcn projects : the HSL-space-separated (Tailwind v3) versus oklch (Tailwind v4) format split, the hsl(var(--background)) wrapper convention versus the bare var(--background) convention, the bg-background utility semantics difference, and dark-mode flash-of-unstyled-content from a missing suppressHydrationWarning on the html element. Covers the exhaustive CSS-custom-property token catalog (core, sidebar, chart, radius scale), the @theme inline directive (v4) versus the tailwind.config.js theme.extend.colors block (v3), the next-themes ThemeProvider wiring on Next.js, the custom localStorage ThemeProvider on Vite, the useTheme hook, the mode-toggle component, and the copy-from-themes-page workflow. Keywords: shadcn theming, design tokens,