component-library

What this skill does

# 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:
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:

**lib/utils.ts** - Essential cn() helper:
```typescript
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"

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

**components.json** - Component registry:
```json
{
  "$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:
```typescript
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:
```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

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

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

When generating components:
- 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