shadcn-ui

What this skill does

# shadcn/ui Expert

Guidance for building production UIs with shadcn/ui. Covers component composition, advanced patterns, registry authoring, theming, and integration with the broader frontend ecosystem.

Docs: https://ui.shadcn.com/docs

## Core Philosophy

shadcn/ui is NOT a component library -- it is a collection of beautifully designed, accessible components you copy into your project and own. Five pillars:

1. **Open Code** - components live in your codebase, fully editable
2. **Composition** - small primitives combine into complex UI
3. **Distribution** - registry system for sharing component sets
4. **Beautiful Defaults** - production-ready out of the box
5. **AI-Ready** - `data-slot` attributes and structured props for LLM tooling

## When This Skill Activates

- Adding shadcn/ui to a project (`npx shadcn@latest init`)
- Installing or customizing individual components (`npx shadcn@latest add`)
- Building complex patterns: data tables, forms with validation, sidebar navigation
- Theming, color system customization, dark mode
- Creating or consuming a custom registry
- Migrating from Tailwind v3 to v4 with shadcn

## Synergy with Other Frontend Skills

This skill works alongside the other frontend skills. Route to them when appropriate:

| Need | Route to |
|------|----------|
| CSS architecture, modern CSS features, responsive patterns | **frontend-design** |
| Page layout composition, grid systems, breakpoint strategy | **frontend-layout** agent |
| Animations, micro-interactions, visual polish | **frontend-design** agent |
| UX flows, design tokens, component hierarchy | **frontend-design** agent |
| Distinctive visual identity, avoiding generic AI aesthetics | **frontend-css** skill |
| React 19 patterns, Server Components, performance | **react-performance-optimizer** agent |

**This skill** handles shadcn-specific concerns: which components to use, how to compose them, registry patterns, form/table/sidebar architecture, and shadcn theming.

## Live Component Lookup

This skill contains reference patterns for the most complex components (Data Table, Form, Sidebar, Dialog). For any other component's API, props, or usage -- spawn a **quick-searcher** agent to fetch the docs in real time.

### URL patterns

All component docs follow a predictable URL scheme:

| Resource | URL pattern |
|----------|-------------|
| Component docs | `https://ui.shadcn.com/docs/components/{name}` |
| Form integrations | `https://ui.shadcn.com/docs/forms/{library}` |
| Blocks | `https://ui.shadcn.com/blocks` |
| Registry | `https://ui.shadcn.com/docs/registry` |
| Themes | `https://ui.shadcn.com/themes` |
| CLI reference | `https://ui.shadcn.com/docs/cli` |
| Tailwind v4 | `https://ui.shadcn.com/docs/tailwind-v4` |
| Changelog | `https://ui.shadcn.com/docs/changelog` |

### How to look up a component

When you need API details for a specific component (e.g., Combobox, Toast, Sheet):

1. Spawn a **research:quick-searcher** agent with this prompt template:
   ```
   Fetch https://ui.shadcn.com/docs/components/{component-name} and extract:
   - Sub-components and their props
   - Required accessibility attributes
   - Install command
   - Key usage patterns and code examples
   Return structured findings.
   ```

2. For Radix primitive API details (inherited by shadcn), fetch:
   `https://www.radix-ui.com/primitives/docs/components/{component-name}`

3. For TanStack Table API (used by Data Table), fetch:
   `https://tanstack.com/table/latest/docs/introduction`

### Component catalog (by category)

For quick reference when choosing components:

| Category | Components |
|----------|------------|
| Layout | Sidebar, Resizable, Collapsible, Separator, Aspect Ratio |
| Overlay | Dialog, Sheet, Drawer, Alert Dialog, Popover, Tooltip, Hover Card |
| Form | Input, Textarea, Select, Checkbox, Radio Group, Switch, Slider, Toggle, Toggle Group, Date Picker, Combobox |
| Data Display | Table, Data Table, Card, Badge, Avatar, Calendar |
| Feedback | Alert, Toast (Sonner), Progress, Skeleton |
| Navigation | Navigation Menu, Breadcrumb, Pagination, Tabs, Command, Menubar, Dropdown Menu, Context Menu |
| Typography | Label, Separator |

## Installation and Setup

### New project

```bash
npx shadcn@latest init
# Choose: New York style (default, "default" style is deprecated)
# Choose: Tailwind v4 + React 19 (current default)
```

### Add components

```bash
npx shadcn@latest add button dialog form sidebar data-table
# Or add a block:
npx shadcn@latest add dashboard-01
```

### CLI v4 features (March 2026+)

```bash
shadcn add --dry-run dialog    # preview changes without writing
shadcn add --diff dialog       # show diff of what would change
shadcn info                    # show installed components, framework, CSS vars
shadcn docs dialog             # fetch component docs from CLI
shadcn init --template next    # scaffold with framework template
```

## Component Composition

shadcn components are composable primitives. Build complex UI by nesting them.

### Pattern: Sub-component composition

```tsx
<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Edit Profile</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>Update your information.</DialogDescription>
    </DialogHeader>
    {/* your content */}
  </DialogContent>
</Dialog>
```

### Pattern: Slot/asChild delegation

Use `asChild` to delegate rendering to a child element -- avoids extra DOM nodes and lets you use router Links, custom buttons, etc.

```tsx
<DialogTrigger asChild>
  <Link href="/settings">Open Settings</Link>
</DialogTrigger>
```

### Pattern: cn() utility for conditional classes

```tsx
import { cn } from "@/lib/utils"

<div className={cn(
  "rounded-lg border p-4",
  isActive && "border-primary bg-primary/5",
  className
)} />
```

### Pattern: CVA variants for custom components

```tsx
import { cva, type VariantProps } from "class-variance-authority"

const badgeVariants = cva("inline-flex items-center rounded-full px-2.5 py-0.5 text-xs", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      destructive: "bg-destructive text-destructive-foreground",
      outline: "border text-foreground",
    },
  },
  defaultVariants: { variant: "default" },
})
```

## Key Patterns

### Data Table

3-file architecture with TanStack Table. See [references/advanced-patterns.md](references/advanced-patterns.md) for full column definition, sorting, filtering, pagination, and row selection patterns.

- `columns.tsx` - column definitions (`ColumnDef<TData>[]`)
- `data-table.tsx` - table wrapper with `useReactTable`
- `page.tsx` - server component for data fetching

### Form + Zod Validation

React Hook Form + Zod resolver. See [references/advanced-patterns.md](references/advanced-patterns.md) for field patterns, dynamic arrays, and validation modes.

```tsx
const form = useForm<z.infer<typeof schema>>({
  resolver: zodResolver(schema),
  defaultValues: { title: "" }
})
```

### Sidebar Navigation

Provider-based with `SidebarProvider`. Supports `collapsible="icon"` and `collapsible="offcanvas"`. See [references/advanced-patterns.md](references/advanced-patterns.md) for nested navigation, mobile responsive, and `useSidebar()` hook.

## Theming

### Color system (Tailwind v4 / OKLCH)

New projects use OKLCH for perceptual color uniformity. Colors defined as CSS variables in `globals.css`:

```css
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... */
}
```

### Dark mode

Toggle via class on `<html>`. All shadcn components respect `dark:` variants automatically.

### Customization approach

1. Edit CSS variables in `globals.css` for global theme changes
2. Use `cn()` for per-instance overrides
3. Edit the component source directly for structural cha