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]

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

(You MUST keep components in the

components/ui/

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

--brand

--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/

cn()

lib/utils.ts

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

: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

tailwind-merge

className

// 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")

"px-8"

"px-4 px-8"

className

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

Pattern 4: Component Extension with Variants

Use

cva

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

import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";

// Field is a layout primitive - bring your own form library
<Field data-invalid={hasError}>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid={hasError} {...fieldProps} />
  <FieldDescription>We will never share your email.</FieldDescription>
  {hasError && <FieldError errors={errors} />}
</Field>;

Replaces the old

Form/FormField/FormItem/FormControl/FormMessage

Related components:

FieldGroup

FieldSet

FieldLegend

See examples/forms.md for complete form integration examples.

Pattern 6: Compound Component Composition

shadcn/ui uses compound components (Card, Dialog, Sheet, Tabs, Command) with consistent sub-component patterns. Extend by wrapping, not replacing.

// CORRECT: Extend by wrapping compound components
function ProductCard({ title, price, ...props }: ProductCardProps) {
  return (
    <Card {...props}>
      <CardHeader>
        <CardTitle>{title}</CardTitle>
        <CardDescription>${price}</CardDescription>
      </CardHeader>
    </Card>
  );
}

// WRONG: Breaking compound structure with plain divs
<div className="card">
  <div className="card-header">
    <h2>{title}</h2>
  </div>
</div>;

asChild

<Button asChild>
  <Link href="/dashboard">Dashboard</Link>
</Button>

See examples/dialogs.md for AlertDialog, Sheet, and toast patterns. See examples/data-table.md for table with row actions. See examples/command-palette.md for command menu.

Pattern 7: New Components (October 2025+)

Recent additions that solve common patterns:

npx shadcn@latest add field

npx shadcn@latest add spinner

npx shadcn@latest add kbd

npx shadcn@latest add button-group

npx shadcn@latest add input-group

npx shadcn@latest add item

npx shadcn@latest add empty

These components work across Radix and Base UI primitives.

Pattern 8: Recent Platform Changes

Unified Radix UI package (Feb 2026): Individual

@radix-ui/react-*

radix-ui

npx shadcn@latest migrate radix

// Old (pre-Feb 2026)
import * as DialogPrimitive from "@radix-ui/react-dialog";

// New (unified package)
import { Dialog as DialogPrimitive } from "radix-ui";

CLI v4 (March 2026):

• npx shadcn@latest docs [component]

  - View component docs from CLI (useful for AI agents)

• npx shadcn@latest init --template

  - Full project scaffolding for Next.js, Vite, Astro, React Router, TanStack Start, Laravel

• --preset

  flag packs entire design system config (colors, fonts, radius, icons) into a shareable code

• shadcn/skills

  - AI agent context for component patterns and registry workflows

• registry:base

  - Distribute entire design systems as single payloads

RTL support (Jan 2026): First-class right-to-left layout support. The CLI transforms physical CSS classes to logical equivalents at install time.

Detailed Resources:

• examples/core.md - Setup, cn() utility, skeleton loading
• examples/composition.md - Extended button, responsive dialog/drawer
• examples/forms.md - Field component, form integration patterns
• examples/dialogs.md - AlertDialog, Sheet, toast patterns, dark mode provider
• examples/data-table.md - Sortable table with row actions
• examples/command-palette.md - Command menu with keyboard navigation
• examples/theming.md - Complete CSS variables, custom colors, theme toggle
• reference.md - Decision frameworks, anti-patterns, checklists

<red_flags>

RED FLAGS

High Priority Issues:

• Not using CLI for installation - Manual copy misses dependencies and proper file structure
• Breaking OKLCH format - Wrapping values in

  hsl()

  when they are already OKLCH
• Not using cn() - Direct className concatenation breaks Tailwind class merging
• Missing components.json - CLI commands will fail without configuration
• Hardcoding colors - Use CSS variables for theme consistency

Medium Priority Issues:

• Overriding styles with !important - Use cn() and proper class ordering instead
• Not exposing className prop - Custom components should accept className for override
• Ignoring accessibility attributes - Radix provides them; custom extensions can break them
• Not updating both :root and .dark - New colors need both light and dark mode

Gotchas & Edge Cases:

• Foreground convention -

  --primary-foreground

  is text color ON

  --primary

  background, not primary-colored text
• React 19 - No

  forwardRef

  needed;

  ref

  is now a regular prop. Components use

  data-slot

  attributes

• asChild

  required for Link composition - Prevents nested interactive elements (button inside anchor)
• Select controlled usage - Requires both

  onValueChange

  and

  defaultValue

  (or

  value

  )
• Chart config (Tailwind v4) - Use

  var(--chart-1)

  directly, no

  hsl()

  wrapper needed

• suppressHydrationWarning

  - Required on

  <html>

  when using theme provider to prevent hydration mismatch
• Old Form components -

  Form/FormField/FormItem/FormControl/FormMessage

  are legacy; prefer

  Field

  component for new code
• Base UI option - Since Feb 2026, you can choose between Radix and Base UI as the primitive library (

  --base radix

  or

  --base base

  )
• Unified Radix package - Since Feb 2026, import from

  radix-ui

  (not individual

  @radix-ui/react-*

  packages). Migrate with

  npx shadcn@latest migrate radix

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use the CLI to add components -

npx shadcn@latest add [component]

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

(You MUST keep components in the

components/ui/

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

--brand

--brand-foreground

Failure to follow these rules will break component updates, cause styling conflicts, and violate shadcn/ui conventions.

</critical_reminders>