Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.
Use this skill when
Adding shadcn/ui to a new or existing React project (npx shadcn init, npx shadcn add <component>)
Configuring components.json — style, base color, CSS variables, path aliases
Theming with CSS variables (--background, --foreground, --primary, dark mode via .dark class)
Using or customizing any shadcn component: Button, Dialog, Select, Form, DataTable, Combobox, Sheet, Sonner
Building forms with React Hook Form + Zod wired to shadcn <Form> primitives
Creating a custom registry or publishing your own component registry
Extending components with cva (class-variance-authority) variants
Building a design system or component library on top of shadcn
Debugging Tailwind v4 CSS variable conflicts or dark mode issues
Do not use this skill when
The task is Material UI, Mantine, Chakra UI, Ant Design, or NextUI — those use npm-installed, styled components (different paradigm, different skill)
The task is pure Radix UI primitives without shadcn layer — use radix-ui skill if active
The task is Headless UI (Vue ecosystem) — use vue skill
The task is DaisyUI — separate CSS-class-based approach, not shadcn
The task is Tailwind CSS utility classes only, with no component library — use tailwind skill
The task is React Native styling — shadcn/ui is web-only (DOM)
Purpose
shadcn/ui is not an npm package — it is a copy-paste component collection where npx shadcn add button writes the component source code directly into your project. You own the code; upgrades are opt-in edits, not package bumps. This model means components are fully customizable without fighting a library's internal APIs.
Each component is built on a Radix UI primitive (unstyled, accessible, WAI-ARIA compliant) plus Tailwind CSS utility classes as the visual layer, with CSS variables for theming. The cn() helper (tailwind-merge + clsx) handles class composition without specificity conflicts. This skill covers the full workflow: install, configure, use, theme, extend, and compose into a design system.
Capabilities
Install & CLI Workflow
npx shadcn@latest init generates components.json and writes globals.css with the CSS variable theme. After init, every component is added individually: npx shadcn add button dialog form table. Each run writes the component file to the configured components/ui/ path. No npm version — only the shadcn CLI is a dev dependency.
npx shadcn diff shows upstream component changes since you last added/updated. npx shadcn add --all installs every component. Components can be added from custom registries: npx shadcn add <registry-url>/button.
shadcn themes are entirely CSS variable–based. The :root block defines light mode; .dark defines dark mode. Variables use HSL channel notation without the hsl() wrapper so Tailwind can apply opacity modifiers (bg-primary/50).
Core variable pairs: --background/--foreground, --primary/--primary-foreground, --secondary, --muted, --accent, --destructive, --border, --input, --ring, --card, --popover, --sidebar-*. Each semantic pair has a text-contrast companion (--X-foreground).
Dark mode uses the class strategy — add class="dark" to <html>. Tailwind v4 uses @layer base and @theme inline for variable injection.
class-variance-authority (cva) is the standard way to build variants. The Button component ships with variant (default, destructive, outline, secondary, ghost, link) and size (default, sm, lg, icon) props defined via cva. Extending: add variants to the cva() call in the component file — you own it.
cn() is twMerge(clsx(...)) — it merges Tailwind classes safely (last wins, deduplication) and conditionally applies classes. Always use cn() when composing component classes; never raw string concatenation.
Slot (from @radix-ui/react-slot) implements asChild — it forwards props to the child element instead of rendering a wrapper. Buttons with asChild can render as <a> links or <Link> router components.
shadcn ships a <Form> component that wraps React Hook Form with proper id/aria-describedby/aria-invalid wiring. Pattern: useForm → <Form> → <FormField> → <FormItem> → <FormLabel> + <FormControl> + <FormMessage>. The <FormControl> slot injects id and ARIA props automatically — never set them manually.
Zod schema drives zodResolver for validation. Error messages surface via <FormMessage> without extra wiring.
Every shadcn component inherits Radix UI's accessibility guarantees: keyboard navigation (Arrow keys, Home/End, Escape), focus trapping in modals/dialogs, ARIA roles/states/properties, and WAI-ARIA design pattern compliance. Dialog traps focus and restores on close. Select follows the Listbox pattern. Tabs follows the tab panel pattern with roving tabindex.
Do not add redundant role, aria-label, or tabIndex to shadcn components — Radix already handles them. Add ARIA only to custom content inside the component (e.g., label for an icon-only button).
A registry is a JSON endpoint (or file) that describes components and their dependencies. Publish your own: create a registry.json manifest at a URL, then npx shadcn add <url>/component-name. Used for design system distribution across projects without npm publishing.
Upstream canonical reference (verbatim mirror of github.com/shadcn-ui/ui/tree/main/skills/shadcn — DO NOT EDIT)
These files come from shadcn-ui maintainers and are the authoritative source for CLI behaviour, theming model, MCP server, and component composition rules. Our sibling references above (e.g., theming.md) extend or contextualize these for our workflows but don't override.
