shadcn/ui
Overview
Guides building accessible, customizable UI with shadcn/ui as a code generation platform (not an npm dependency). Components are copied into your project via the CLI and fully owned. Supports Radix UI or Base UI primitives, Tailwind CSS 4 with oklch color tokens, React 19 direct ref patterns, and type-safe form validation with the Field component and Zod.
When to use: Adding shadcn/ui components, theming with CSS variables and oklch colors, building forms with React Hook Form or TanStack Form, creating custom registries, composing accessible component variants, setting up dark mode.
When NOT to use: Non-React frameworks (use shadcn-vue or shadcn-svelte instead), projects using a different component library (MUI, Chakra), projects not using Tailwind CSS.
Quick Reference
| Pattern |
API / Approach |
Key Points |
| Init project |
npx shadcn@latest init |
Auto-detects framework, configures CSS variables |
| Add component |
npx shadcn@latest add [name] |
Copies source code into your project |
| Custom project |
npx shadcn@latest create |
Pick library (Radix/Base UI), style, theme, fonts |
| Check updates |
npx shadcn@latest diff [component] |
Shows upstream changes for your components |
| Search registry |
npx shadcn@latest search @registry |
Browse and install from namespaced registries |
| Build registry |
npx shadcn@latest build |
Generate registry JSON from registry.json |
| Theme tokens |
:root vars + @theme inline mapping |
oklch color values, dark mode via .dark class |
| Dark mode |
@custom-variant dark (&:is(.dark *)) |
Swaps CSS variables under .dark selector |
| Component variant |
cva() from class-variance-authority |
Type-safe variant definitions |
| Polymorphic slot |
asChild prop with <Slot> from Radix |
Merge props onto child element |
| Direct ref |
ref as a regular prop |
forwardRef is deprecated in React 19 |
| Form (current) |
<Field /> + React Hook Form + Zod |
Replaces legacy <Form /> component |
| Form (legacy) |
<Form /> + <FormField /> + Zod |
Still works but no longer actively developed |
| Class merging |
cn() utility wrapping clsx + twMerge |
Safely merge Tailwind classes without conflicts |
| Toast / notification |
Sonner (npx shadcn@latest add sonner) |
Default notification approach; auto-dismiss, stacking |
| Init with blocks |
npx shadcn@latest init sidebar-01 |
Bootstrap project with pre-built page blocks |
| RTL support |
dir="rtl" on root element |
Built-in RTL layout support for all components |
| New components |
Spinner, Kbd, ButtonGroup |
Recently added utility and layout components |
Common Mistakes
| Mistake |
Correct Pattern |
| Installing shadcn/ui as an npm dependency |
Use the CLI (npx shadcn@latest add) to copy source into your project |
Using forwardRef with React 19 components |
Pass ref directly as a prop -- forwardRef is deprecated in React 19 |
| Using HSL values for color tokens |
Use oklch format: --primary: oklch(0.205 0 0) |
Wrapping variables with hsl() or oklch() in utilities |
Reference CSS variables directly: var(--primary) |
Putting tokens directly in @theme {} |
Use :root for values + @theme inline to map them to Tailwind |
Using legacy <Form /> for new forms |
Use <Field /> component with React Hook Form or TanStack Form |
| Skipping Zod validation in form components |
Always pair forms with Zod schemas for type-safe validation |
Using div elements for interactive controls |
Use Radix or Base UI primitives for semantic HTML and accessibility |
Modifying components in node_modules |
Components live in your source tree -- own and customize directly |
Using old CLI command shadcn-ui@canary |
Use npx shadcn@latest for all CLI operations |
Delegation
- Component discovery and primitive lookup: Use
Explore agent
- Theme migration or multi-file refactoring: Use
Task agent
- Design system architecture planning: Use
Plan agent
- Registry setup and distribution: Use
Task agent
If the tanstack-form skill is available, delegate advanced form state management (array fields, linked fields, async validation) to it.
If the tailwind skill is available, delegate utility class patterns and design token architecture to it.
References
- Theming and dark mode
- Component patterns and variants
- Form patterns with Field, React Hook Form, and Zod
- CLI and registry
1---2name: shadcn-ui3description: Builds accessible, customizable component libraries using shadcn/ui with Radix UI or Base UI, Tailwind CSS 4, and React 19. Covers component ownership, oklch CSS theming, type-safe forms with Field and Zod, CLI workflows, and registry patterns. Use when adding shadcn/ui components, configuring themes, building forms with Zod, creating custom registries, or composing accessible component variants. Use for shadcn CLI, dark mode, component variants, form validation.4license: MIT5---6
7# shadcn/ui
8
9## Overview
10
11Guides building accessible, customizable UI with shadcn/ui as a code generation platform (not an npm dependency). Components are copied into your project via the CLI and fully owned. Supports Radix UI or Base UI primitives, Tailwind CSS 4 with oklch color tokens, React 19 direct ref patterns, and type-safe form validation with the Field component and Zod.
12
13**When to use:** Adding shadcn/ui components, theming with CSS variables and oklch colors, building forms with React Hook Form or TanStack Form, creating custom registries, composing accessible component variants, setting up dark mode.
14
15**When NOT to use:** Non-React frameworks (use shadcn-vue or shadcn-svelte instead), projects using a different component library (MUI, Chakra), projects not using Tailwind CSS.
16
17## Quick Reference
18
19| Pattern | API / Approach | Key Points |
20| -------------------- | ------------------------------------------ | ----------------------------------------------------- |
21| Init project | `npx shadcn@latest init` | Auto-detects framework, configures CSS variables |
22| Add component | `npx shadcn@latest add [name]` | Copies source code into your project |
23| Custom project | `npx shadcn@latest create` | Pick library (Radix/Base UI), style, theme, fonts |
24| Check updates | `npx shadcn@latest diff [component]` | Shows upstream changes for your components |
25| Search registry | `npx shadcn@latest search @registry` | Browse and install from namespaced registries |
26| Build registry | `npx shadcn@latest build` | Generate registry JSON from `registry.json` |
27| Theme tokens | `:root` vars + `@theme inline` mapping | oklch color values, dark mode via `.dark` class |
28| Dark mode | `@custom-variant dark (&:is(.dark *))` | Swaps CSS variables under `.dark` selector |
29| Component variant | `cva()` from `class-variance-authority` | Type-safe variant definitions |
30| Polymorphic slot | `asChild` prop with `<Slot>` from Radix | Merge props onto child element |
31| Direct ref | `ref` as a regular prop | `forwardRef` is deprecated in React 19 |
32| Form (current) | `<Field />` + React Hook Form + Zod | Replaces legacy `<Form />` component |
33| Form (legacy) | `<Form />` + `<FormField />` + Zod | Still works but no longer actively developed |
34| Class merging | `cn()` utility wrapping `clsx` + `twMerge` | Safely merge Tailwind classes without conflicts |
35| Toast / notification | Sonner (`npx shadcn@latest add sonner`) | Default notification approach; auto-dismiss, stacking |
36| Init with blocks | `npx shadcn@latest init sidebar-01` | Bootstrap project with pre-built page blocks |
37| RTL support | `dir="rtl"` on root element | Built-in RTL layout support for all components |
38| New components | `Spinner`, `Kbd`, `ButtonGroup` | Recently added utility and layout components |
39
40## Common Mistakes
41
42| Mistake | Correct Pattern |
43| --------------------------------------------------------- | ----------------------------------------------------------------------- |
44| Installing shadcn/ui as an npm dependency | Use the CLI (`npx shadcn@latest add`) to copy source into your project |
45| Using `forwardRef` with React 19 components | Pass `ref` directly as a prop -- `forwardRef` is deprecated in React 19 |
46| Using HSL values for color tokens | Use oklch format: `--primary: oklch(0.205 0 0)` |
47| Wrapping variables with `hsl()` or `oklch()` in utilities | Reference CSS variables directly: `var(--primary)` |
48| Putting tokens directly in `@theme {}` | Use `:root` for values + `@theme inline` to map them to Tailwind |
49| Using legacy `<Form />` for new forms | Use `<Field />` component with React Hook Form or TanStack Form |
50| Skipping Zod validation in form components | Always pair forms with Zod schemas for type-safe validation |
51| Using `div` elements for interactive controls | Use Radix or Base UI primitives for semantic HTML and accessibility |
52| Modifying components in `node_modules` | Components live in your source tree -- own and customize directly |
53| Using old CLI command `shadcn-ui@canary` | Use `npx shadcn@latest` for all CLI operations |
54
55## Delegation
56
57- **Component discovery and primitive lookup**: Use `Explore` agent
58- **Theme migration or multi-file refactoring**: Use `Task` agent
59- **Design system architecture planning**: Use `Plan` agent
60- **Registry setup and distribution**: Use `Task` agent
61
62> If the `tanstack-form` skill is available, delegate advanced form state management (array fields, linked fields, async validation) to it.
63> If the `tailwind` skill is available, delegate utility class patterns and design token architecture to it.
64
65## References
66
67- [Theming and dark mode](references/theming-and-dark-mode.md)
68- [Component patterns and variants](references/component-patterns.md)
69- [Form patterns with Field, React Hook Form, and Zod](references/form-patterns.md)
70- [CLI and registry](references/cli-and-registry.md)
oakoss