shadcn/ui Component Patterns

Quick Guide: shadcn/ui is a copy-and-own component system built on Radix primitives and Tailwind. Use npx shadcn@latest add to install components into components/ui/. Theme via CSS custom properties in OKLCH format. Compose with compound component patterns. Use the cn() utility for class merging. New Field component replaces the old Form/FormField pattern for form-library-agnostic field layout.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use the CLI to add components - npx shadcn@latest add [component] - not manual copy)

(You MUST customize components through CSS variables and the cn() utility - not direct style overrides)

(You MUST keep components in the components/ui/ directory - this is the shadcn convention)

(You MUST define foreground colors for every new background color - --brand needs --brand-foreground)

</critical_requirements>

Auto-detection: shadcn/ui, shadcn, @shadcn, components.json, npx shadcn, cn() utility, ui components, Radix-based components, data-slot, Field component, cva variants

When to use:

• Building React applications with accessible, customizable UI components
• Setting up a copy-and-own component library with full source control
• Implementing CSS variable theming with OKLCH colors and dark mode
• Creating forms with the new Field component (form-library-agnostic)
• Using compound components (Card, Dialog, Sheet, Tabs, Command)

When NOT to use:

• Projects requiring a specific opinionated design system
• Applications where you cannot control the component source
• Projects not using Tailwind CSS

Key patterns covered:

• CLI installation, inspection flags, and component management
• CSS variable theming with OKLCH format and Tailwind v4
• cn() utility for conflict-free class merging
• Compound component composition and extension
• Field component for form-library-agnostic field layout
• Variant system with cva (class-variance-authority)

Philosophy

shadcn/ui is not a traditional component library - it is how you build your component library. Components are copied into your codebase via CLI, giving you full ownership. Core functionality (accessibility, keyboard nav) comes from Radix primitives; the styling layer is yours to customize.

Five Core Principles:

1. Open Code - Component source is visible and modifiable
2. Composition - Consistent, composable compound component interfaces
3. Distribution - CLI and flat-file schema enable component distribution
4. Beautiful Defaults - Carefully curated styling that works out of the box
5. AI-Ready - Open source architecture allows tools to read and improve components

What shadcn/ui handles vs what other skills handle:

• shadcn/ui: component structure, CSS variables, cn() utility, composition patterns, Field layout
• Your styling approach: Tailwind configuration, utility class conventions, custom CSS
• Your form library: useForm hook, validation schemas, submission logic, state management

Core Patterns

Pattern 1: CLI Installation and Management

Always use the CLI to add components. It resolves dependencies, installs Radix packages, and creates proper file structure.

# Initialize (creates components.json)
npx shadcn@latest init

# Add components
npx shadcn@latest add button card dialog

# Inspection flags (CLI v4)
npx shadcn@latest add button --dry-run   # Preview changes
npx shadcn@latest add button --diff      # Check for updates
npx shadcn@latest add button --view      # Display component payload

# Monorepo support
npx shadcn@latest add button --path=packages/ui/src/components

# Project info (useful for AI agents)
npx shadcn@latest info

# View component docs from CLI (v4)
npx shadcn@latest docs combobox

Components go in components/ui/. The cn() utility goes in lib/utils.ts. Both are created automatically.

Why good: CLI handles dependency resolution, provides inspection before changes, components become owned source code

Pattern 2: CSS Variable Theming (OKLCH)

shadcn/ui uses CSS custom properties with OKLCH color format (Tailwind v4). Every color follows a background/foreground naming convention.

/* The naming convention - understand this, don't memorize values */
:root {
  --primary: oklch(0.205 0 0); /* Background color */
  --primary-foreground: oklch(0.985 0 0); /* Text ON that background */
}

.dark {
  --primary: oklch(0.985 0 0); /* Inverted for dark mode */
  --primary-foreground: oklch(0.205 0 0);
}

Key Tailwind v4 changes from older shadcn versions:

• OKLCH replaces HSL for better perceptual uniformity
• @theme inline directive maps CSS variables to Tailwind utilities
• @custom-variant dark defines dark mode selector
• --chart-* and --sidebar-* variable families for specialized components
• Computed radius: --radius-sm/md/lg/xl derived from base --radius

Adding custom colors requires both the CSS variable AND the @theme inline mapping:

:root {
  --brand: oklch(0.627 0.265 303.9);
  --brand-foreground: oklch(1 0 0);
}

@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
}

Then use as: bg-brand text-brand-foreground hover:bg-brand/90

See examples/theming.md for complete variable reference and custom color examples.

Pattern 3: The cn() Utility

Combines clsx (conditional classes) with tailwind-merge (conflict resolution). Consumer className always comes last so overrides work.

// lib/utils.ts - auto-generated by shadcn init
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Usage in components - className last for consumer overrides
function Card({ className, ...props }: CardProps) {
  return (
    <div
      className={cn("rounded-lg border bg-card shadow-sm", className)}
      {...props}
    />
  );
}

Critical behavior: cn("px-4", "px-8") produces "px-8" (last wins), not "px-4 px-8". This is why consumer className overrides work correctly.

See examples/core.md for more cn() examples.

Pattern 4: Component Extension with Variants

Use cva (class-variance-authority) for variant-based component styling. This is how shadcn/ui itself structures Button, Badge, and Alert.

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

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive:
          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent",
        ghost: "hover:bg-accent hover:text-accent-foreground",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 px-3",
        lg: "h-11 px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  },
);

To add a new variant, edit the component source directly - you own it. To use variants: <Button variant="destructive" size="sm">.

See examples/composition.md for extended button with loading state and responsive dialog/drawer patterns.

Pattern 5: Field Component (Form Layout)

The Field component is the modern form-library-agnostic way to compose form fields. It provides labels, descriptions, error messages, and accessibility - without coupling to any specific form library.

import {
  Field,