Component Library - shadcn/ui Architecture

Quick Start

1. Create

   /components/ui/

   directory structure
2. Generate

   lib/utils.ts

   with cn() helper first
3. Create requested components with full TypeScript, variants, and accessibility
4. Include example usage for each component

Core Setup Files

Always generate these first:

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

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

{
  "$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

{
  "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

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

Advanced Patterns

• 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

• Include all variant combinations
• Add proper TypeScript types
• Implement keyboard shortcuts
• Include loading and error states
• Provide Storybook stories structure
• Add comprehensive prop documentation
• Include accessibility attributes
• Test with screen readers