Component Library - shadcn/ui Architecture

Generate production-ready React components with shadcn/ui patterns, saving 8-10 hours per project.

Quick Start

When generating components:

Create /components/ui/ directory structure
Generate lib/utils.ts with cn() helper first
Create requested components with full TypeScript, variants, and accessibility
Include example usage for each component

Core Setup Files

Always generate these first:

lib/utils.ts - Essential cn() helper:

import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

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

components.json - Component registry:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Component Categories

Form Components

Input - Text input with variants (default, ghost, underline)
Select - Custom dropdown with search, multi-select options
Checkbox - With indeterminate state support
Radio - Radio groups with custom styling
Switch - Toggle switches with labels
Textarea - Auto-resize, character count variants
DatePicker - Calendar integration, range selection
FileUpload - Drag & drop, preview, progress
Slider - Range input with marks, tooltips
Form - React Hook Form wrapper with validation

Display Components

Card - Container with header/footer slots
Table - Sortable, filterable, pagination
Badge - Status indicators with variants
Avatar - Image/initials with fallback
Progress - Linear and circular variants
Skeleton - Loading states
Separator - Visual dividers
ScrollArea - Custom scrollbars

Feedback Components

Alert - Info/warning/error/success states
Toast - Notifications with actions
Dialog/Modal - Accessible overlays
Tooltip - Hover information
Popover - Positioned content
AlertDialog - Confirmation dialogs

Navigation Components

Navigation - Responsive nav with mobile menu
Tabs - Tab panels with keyboard nav
Breadcrumb - Path navigation
Pagination - Page controls
CommandMenu - Command palette (⌘K)
ContextMenu - Right-click menus
DropdownMenu - Action menus

Layout Components

Accordion - Collapsible sections
Collapsible - Show/hide content
ResizablePanels - Draggable split panes
Sheet - Slide-out panels
AspectRatio - Maintain ratios

Component Implementation Patterns

Use CVA for all variants:

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

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    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 hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
        lg: "h-11 rounded-md px-8",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

Accessibility Requirements:

ARIA labels and roles on all interactive elements
Keyboard navigation (Tab, Arrow keys, Enter, Escape)
Focus management and trapping for modals
Screen reader announcements
Semantic HTML elements

Dark Mode Support:

Use Tailwind dark: modifier
CSS variables for theme colors
Smooth transitions between modes

Responsive Design:

Mobile-first approach
Container queries where appropriate
Touch-friendly tap targets (min 44x44px)
Responsive typography scale

Dependencies

Include in package.json:

{
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-progress": "^1.0.3",
    "@radix-ui/react-radio-group": "^1.1.3",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "cmdk": "^0.2.0",
    "date-fns": "^2.30.0",
    "lucide-react": "^0.263.1",
    "react-day-picker": "^8.8.0",
    "react-hook-form": "^7.45.4",
    "tailwind-merge": "^1.14.0",
    "tailwindcss-animate": "^1.0.7"
  }
}

Implementation Workflow

Assess Requirements: Identify which components are needed
Generate Base Files: Create utils.ts and components.json
Create Components: Generate requested components with all features
Provide Examples: Include usage examples for each component
Document Props: Add TypeScript interfaces with JSDoc comments

Advanced Patterns

For complex requirements, see:

references/form-patterns.md - Advanced form handling
references/data-tables.md - Complex table implementations
references/animation-patterns.md - Framer Motion integration
references/testing-setup.md - Component testing patterns

Performance Optimization

Use React.memo for expensive components
Implement virtual scrolling for long lists
Lazy load heavy components
Optimize bundle size with tree shaking
Use CSS containment for layout stability

Component Generation Tips