@adlas/create-app 1.0.0

package/templates/docs/SHADCN_TO_HEROUI_MIGRATION.md

@@ -0,0 +1,1375 @@
+# shadcn/ui to HeroUI Migration Guide
+
+This guide provides complete component mappings and conversion patterns for migrating from shadcn/ui to HeroUI.
+
+---
+
+## 📚 Table of Contents
+
+1. [Key Differences](#key-differences)
+2. [Installation & Setup](#installation--setup)
+3. [Component Mappings](#component-mappings)
+4. [Common Patterns](#common-patterns)
+5. [Migration Checklist](#migration-checklist)
+
+---
+
+## Key Differences
+
+### Philosophy
+- **shadcn/ui:** Copy-paste components into your project, full customization
+- **HeroUI:** NPM package components, theme-based customization
+
+### Styling Approach
+- **shadcn/ui:** Uses `cn()` utility for merging Tailwind classes
+- **HeroUI:** Uses `classNames` prop for different component parts
+
+### Import Pattern
+```tsx
+// shadcn/ui
+import { Button } from "@/components/ui/button"
+
+// HeroUI
+import { Button } from "@heroui/button"
+// or
+import { Button } from "@heroui/react"
+```
+
+### Props Philosophy
+- **shadcn/ui:** Single `className` prop
+- **HeroUI:** Structured `classNames` object for different parts
+
+---
+
+## Installation & Setup
+
+### Remove shadcn/ui
+```bash
+# Remove shadcn components folder
+rm -rf src/components/ui/
+
+# Remove from package.json (if added as dependency)
+pnpm remove @radix-ui/react-* class-variance-authority clsx tailwind-merge
+```
+
+### Install HeroUI
+```bash
+# Already installed in this project
+# If needed in target project:
+pnpm add @heroui/react framer-motion
+```
+
+### Update tailwind.config.js
+```js
+// Remove shadcn config
+// Add HeroUI config (already in this project)
+import { heroui } from "@heroui/react"
+
+module.exports = {
+  plugins: [heroui()],
+}
+```
+
+---
+
+## Component Mappings
+
+### Form Components
+
+#### Input
+
+**shadcn/ui:**
+```tsx
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+<div className="space-y-2">
+  <Label htmlFor="email">Email</Label>
+  <Input
+    id="email"
+    type="email"
+    placeholder="Enter your email"
+    className="w-full"
+  />
+</div>
+```
+
+**HeroUI:**
+```tsx
+import { Input } from "@heroui/input"
+
+<Input
+  type="email"
+  label="Email"
+  placeholder="Enter your email"
+  variant="bordered"
+  classNames={{
+    input: "w-full",
+  }}
+/>
+```
+
+**Key Changes:**
+- ✅ Label is built-in via `label` prop
+- ✅ Use `variant="bordered"` for outlined style
+- ✅ Use `classNames` object instead of `className`
+
+**Common Variants:**
+```tsx
+// Bordered (most common - similar to shadcn default)
+<Input variant="bordered" />
+
+// Flat
+<Input variant="flat" />
+
+// Faded
+<Input variant="faded" />
+
+// Underlined
+<Input variant="underlined" />
+```
+
+**With Error State:**
+```tsx
+<Input
+  type="email"
+  label="Email"
+  variant="bordered"
+  isInvalid={!!errors.email}
+  errorMessage={errors.email?.message}
+/>
+```
+
+---
+
+#### Textarea
+
+**shadcn/ui:**
+```tsx
+import { Textarea } from "@/components/ui/textarea"
+
+<Textarea
+  placeholder="Enter description"
+  className="min-h-[100px]"
+/>
+```
+
+**HeroUI:**
+```tsx
+import { Textarea } from "@heroui/input"
+
+<Textarea
+  label="Description"
+  placeholder="Enter description"
+  variant="bordered"
+  minRows={3}
+/>
+```
+
+---
+
+#### Button
+
+**shadcn/ui:**
+```tsx
+import { Button } from "@/components/ui/button"
+
+<Button variant="default" size="lg">
+  Click me
+</Button>
+
+<Button variant="destructive">
+  Delete
+</Button>
+
+<Button variant="outline">
+  Cancel
+</Button>
+
+<Button variant="ghost">
+  Ghost
+</Button>
+```
+
+**HeroUI:**
+```tsx
+import { Button } from "@heroui/button"
+
+<Button color="primary" size="lg">
+  Click me
+</Button>
+
+<Button color="danger">
+  Delete
+</Button>
+
+<Button variant="bordered">
+  Cancel
+</Button>
+
+<Button variant="light">
+  Ghost
+</Button>
+```
+
+**Variant Mapping:**
+| shadcn/ui | HeroUI |
+|-----------|---------|
+| `variant="default"` | `color="primary"` |
+| `variant="destructive"` | `color="danger"` |
+| `variant="outline"` | `variant="bordered"` |
+| `variant="ghost"` | `variant="light"` |
+| `variant="secondary"` | `color="secondary"` |
+
+**With Loading State:**
+```tsx
+// shadcn/ui
+<Button disabled={isLoading}>
+  {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+  Submit
+</Button>
+
+// HeroUI
+<Button isLoading={isLoading}>
+  Submit
+</Button>
+```
+
+---
+
+#### Select
+
+**shadcn/ui:**
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+<Select onValueChange={setValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Select option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+**HeroUI:**
+```tsx
+import { Select, SelectItem } from "@heroui/select"
+
+<Select
+  label="Select option"
+  placeholder="Choose an option"
+  variant="bordered"
+  onChange={(e) => setValue(e.target.value)}
+>
+  <SelectItem key="option1" value="option1">
+    Option 1
+  </SelectItem>
+  <SelectItem key="option2" value="option2">
+    Option 2
+  </SelectItem>
+</Select>
+```
+
+**Dynamic Options:**
+```tsx
+const options = [
+  { value: "1", label: "Option 1" },
+  { value: "2", label: "Option 2" },
+]
+
+<Select
+  label="Select option"
+  variant="bordered"
+  items={options}
+>
+  {(item) => (
+    <SelectItem key={item.value}>
+      {item.label}
+    </SelectItem>
+  )}
+</Select>
+```
+
+---
+
+#### Checkbox
+
+**shadcn/ui:**
+```tsx
+import { Checkbox } from "@/components/ui/checkbox"
+
+<div className="flex items-center space-x-2">
+  <Checkbox id="terms" />
+  <label htmlFor="terms">Accept terms</label>
+</div>
+```
+
+**HeroUI:**
+```tsx
+import { Checkbox } from "@heroui/checkbox"
+
+<Checkbox>Accept terms</Checkbox>
+```
+
+**Controlled:**
+```tsx
+<Checkbox
+  isSelected={isAccepted}
+  onValueChange={setIsAccepted}
+>
+  Accept terms
+</Checkbox>
+```
+
+---
+
+#### Radio Group
+
+**shadcn/ui:**
+```tsx
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
+
+<RadioGroup value={value} onValueChange={setValue}>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option1" id="option1" />
+    <Label htmlFor="option1">Option 1</Label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option2" id="option2" />
+    <Label htmlFor="option2">Option 2</Label>
+  </div>
+</RadioGroup>
+```
+
+**HeroUI:**
+```tsx
+import { RadioGroup, Radio } from "@heroui/radio"
+
+<RadioGroup
+  label="Select option"
+  value={value}
+  onValueChange={setValue}
+>
+  <Radio value="option1">Option 1</Radio>
+  <Radio value="option2">Option 2</Radio>
+</RadioGroup>
+```
+
+---
+
+#### Switch
+
+**shadcn/ui:**
+```tsx
+import { Switch } from "@/components/ui/switch"
+
+<Switch checked={isEnabled} onCheckedChange={setIsEnabled} />
+```
+
+**HeroUI:**
+```tsx
+import { Switch } from "@heroui/switch"
+
+<Switch isSelected={isEnabled} onValueChange={setIsEnabled}>
+  Enable feature
+</Switch>
+```
+
+---
+
+#### Slider
+
+**shadcn/ui:**
+```tsx
+import { Slider } from "@/components/ui/slider"
+
+<Slider
+  value={[value]}
+  onValueChange={([val]) => setValue(val)}
+  max={100}
+  step={1}
+/>
+```
+
+**HeroUI:**
+```tsx
+import { Slider } from "@heroui/slider"
+
+<Slider
+  label="Price Range"
+  value={value}
+  onChange={setValue}
+  maxValue={100}
+  step={1}
+  formatOptions={{ style: "currency", currency: "EUR" }}
+/>
+```
+
+**Range Slider:**
+```tsx
+<Slider
+  label="Price Range"
+  value={[minPrice, maxPrice]}
+  onChange={([min, max]) => {
+    setMinPrice(min)
+    setMaxPrice(max)
+  }}
+  minValue={0}
+  maxValue={1000}
+  step={10}
+/>
+```
+
+---
+
+### Display Components
+
+#### Card
+
+**shadcn/ui:**
+```tsx
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Content goes here
+  </CardContent>
+  <CardFooter>
+    Footer content
+  </CardFooter>
+</Card>
+```
+
+**HeroUI:**
+```tsx
+import { Card, CardHeader, CardBody, CardFooter } from "@heroui/card"
+
+<Card>
+  <CardHeader className="flex flex-col items-start">
+    <h4 className="text-lg font-bold">Title</h4>
+    <p className="text-sm text-default-500">Description</p>
+  </CardHeader>
+  <CardBody>
+    Content goes here
+  </CardBody>
+  <CardFooter>
+    Footer content
+  </CardFooter>
+</Card>
+```
+
+**Variants:**
+```tsx
+// Bordered
+<Card variant="bordered">...</Card>
+
+// Elevated (shadow)
+<Card shadow="md">...</Card>
+
+// Hoverable
+<Card isHoverable isPressable>...</Card>
+```
+
+---
+
+#### Badge / Chip
+
+**shadcn/ui:**
+```tsx
+import { Badge } from "@/components/ui/badge"
+
+<Badge variant="default">Badge</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="outline">Outline</Badge>
+```
+
+**HeroUI:**
+```tsx
+import { Chip } from "@heroui/chip"
+
+<Chip color="primary">Chip</Chip>
+<Chip color="danger">Error</Chip>
+<Chip variant="bordered">Outline</Chip>
+```
+
+**With Close Button:**
+```tsx
+<Chip
+  onClose={() => console.log("closed")}
+  variant="flat"
+>
+  Closeable
+</Chip>
+```
+
+**As Status:**
+```tsx
+<Chip color="success" variant="dot">Active</Chip>
+<Chip color="warning" variant="dot">Pending</Chip>
+<Chip color="danger" variant="dot">Inactive</Chip>
+```
+
+---
+
+#### Avatar
+
+**shadcn/ui:**
+```tsx
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
+
+<Avatar>
+  <AvatarImage src="/avatar.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+**HeroUI:**
+```tsx
+import { Avatar } from "@heroui/avatar"
+
+<Avatar
+  src="/avatar.jpg"
+  alt="User"
+  showFallback
+  name="John Doe"
+/>
+```
+
+**Sizes:**
+```tsx
+<Avatar size="sm" />
+<Avatar size="md" />
+<Avatar size="lg" />
+```
+
+**With Badge:**
+```tsx
+<Avatar
+  isBordered
+  color="success"
+  src="/avatar.jpg"
+/>
+```
+
+---
+
+#### Alert / Callout
+
+**shadcn/ui:**
+```tsx
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
+
+<Alert variant="destructive">
+  <AlertCircle className="h-4 w-4" />
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>
+    Something went wrong
+  </AlertDescription>
+</Alert>
+```
+
+**HeroUI:**
+```tsx
+// HeroUI doesn't have Alert component
+// Use custom component or Card with colors
+
+import { Card, CardBody } from "@heroui/card"
+
+<Card className="bg-danger-50 border-l-4 border-danger">
+  <CardBody>
+    <div className="flex gap-2">
+      <AlertCircle className="text-danger" />
+      <div>
+        <h4 className="text-danger font-semibold">Error</h4>
+        <p className="text-danger-600">Something went wrong</p>
+      </div>
+    </div>
+  </CardBody>
+</Card>
+```
+
+**Or create reusable Alert component:**
+```tsx
+// components/ui/Alert.tsx
+import { Card, CardBody } from "@heroui/card"
+import { cn } from "@/lib/utils"
+
+type AlertProps = {
+  variant?: "info" | "success" | "warning" | "danger"
+  title?: string
+  children: React.ReactNode
+}
+
+export function Alert({ variant = "info", title, children }: AlertProps) {
+  const colors = {
+    info: "bg-primary-50 border-primary text-primary-900",
+    success: "bg-success-50 border-success text-success-900",
+    warning: "bg-warning-50 border-warning text-warning-900",
+    danger: "bg-danger-50 border-danger text-danger-900",
+  }
+
+  return (
+    <Card className={cn("border-l-4", colors[variant])}>
+      <CardBody>
+        {title && <h4 className="font-semibold mb-1">{title}</h4>}
+        <div>{children}</div>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+---
+
+### Navigation Components
+
+#### Tabs
+
+**shadcn/ui:**
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
+
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">
+    Content 1
+  </TabsContent>
+  <TabsContent value="tab2">
+    Content 2
+  </TabsContent>
+</Tabs>
+```
+
+**HeroUI:**
+```tsx
+import { Tabs, Tab } from "@heroui/tabs"
+
+<Tabs>
+  <Tab key="tab1" title="Tab 1">
+    Content 1
+  </Tab>
+  <Tab key="tab2" title="Tab 2">
+    Content 2
+  </Tab>
+</Tabs>
+```
+
+**Controlled:**
+```tsx
+<Tabs
+  selectedKey={selected}
+  onSelectionChange={setSelected}
+>
+  <Tab key="tab1" title="Tab 1">Content 1</Tab>
+  <Tab key="tab2" title="Tab 2">Content 2</Tab>
+</Tabs>
+```
+
+**With Icons:**
+```tsx
+import { User, Settings } from "lucide-react"
+
+<Tabs>
+  <Tab
+    key="profile"
+    title={
+      <div className="flex items-center gap-2">
+        <User size={16} />
+        Profile
+      </div>
+    }
+  >
+    Profile content
+  </Tab>
+  <Tab
+    key="settings"
+    title={
+      <div className="flex items-center gap-2">
+        <Settings size={16} />
+        Settings
+      </div>
+    }
+  >
+    Settings content
+  </Tab>
+</Tabs>
+```
+
+---
+
+#### Dropdown Menu
+
+**shadcn/ui:**
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">Open</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Item 1</DropdownMenuItem>
+    <DropdownMenuItem>Item 2</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+**HeroUI:**
+```tsx
+import {
+  Dropdown,
+  DropdownTrigger,
+  DropdownMenu,
+  DropdownItem,
+} from "@heroui/dropdown"
+import { Button } from "@heroui/button"
+
+<Dropdown>
+  <DropdownTrigger>
+    <Button variant="bordered">Open</Button>
+  </DropdownTrigger>
+  <DropdownMenu>
+    <DropdownItem key="item1">Item 1</DropdownItem>
+    <DropdownItem key="item2">Item 2</DropdownItem>
+  </DropdownMenu>
+</Dropdown>
+```
+
+**With Actions:**
+```tsx
+<DropdownMenu
+  onAction={(key) => {
+    if (key === "edit") handleEdit()
+    if (key === "delete") handleDelete()
+  }}
+>
+  <DropdownItem key="edit">Edit</DropdownItem>
+  <DropdownItem key="delete" color="danger">
+    Delete
+  </DropdownItem>
+</DropdownMenu>
+```
+
+---
+
+#### Breadcrumbs
+
+**shadcn/ui:**
+```tsx
+// Usually custom implementation
+<nav className="flex">
+  <Link href="/">Home</Link>
+  <span>/</span>
+  <Link href="/products">Products</Link>
+  <span>/</span>
+  <span>Current</span>
+</nav>
+```
+
+**HeroUI:**
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from "@heroui/breadcrumbs"
+
+<Breadcrumbs>
+  <BreadcrumbItem href="/">Home</BreadcrumbItem>
+  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
+  <BreadcrumbItem>Current</BreadcrumbItem>
+</Breadcrumbs>
+```
+
+---
+
+### Overlay Components
+
+#### Dialog / Modal
+
+**shadcn/ui:**
+```tsx
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog"
+
+<Dialog open={isOpen} onOpenChange={setIsOpen}>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    <div>Content</div>
+  </DialogContent>
+</Dialog>
+```
+
+**HeroUI:**
+```tsx
+import {
+  Modal,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  useDisclosure,
+} from "@heroui/modal"
+import { Button } from "@heroui/button"
+
+const { isOpen, onOpen, onClose } = useDisclosure()
+
+<>
+  <Button onPress={onOpen}>Open Modal</Button>
+  <Modal isOpen={isOpen} onClose={onClose}>
+    <ModalContent>
+      <ModalHeader>Title</ModalHeader>
+      <ModalBody>
+        <p>Content goes here</p>
+      </ModalBody>
+      <ModalFooter>
+        <Button variant="light" onPress={onClose}>
+          Cancel
+        </Button>
+        <Button color="primary" onPress={onClose}>
+          Confirm
+        </Button>
+      </ModalFooter>
+    </ModalContent>
+  </Modal>
+</>
+```
+
+**Key Differences:**
+- Use `useDisclosure()` hook for state management
+- ModalContent wraps all content
+- More structured layout with Header/Body/Footer
+
+---
+
+#### Popover
+
+**shadcn/ui:**
+```tsx
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover"
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    Content here
+  </PopoverContent>
+</Popover>
+```
+
+**HeroUI:**
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from "@heroui/popover"
+import { Button } from "@heroui/button"
+
+<Popover>
+  <PopoverTrigger>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <div className="p-2">
+      Content here
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+---
+
+#### Tooltip
+
+**shadcn/ui:**
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button>Hover me</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      Tooltip text
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+**HeroUI:**
+```tsx
+import { Tooltip } from "@heroui/tooltip"
+import { Button } from "@heroui/button"
+
+<Tooltip content="Tooltip text">
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+**Much simpler!** No provider needed.
+
+---
+
+### Feedback Components
+
+#### Progress
+
+**shadcn/ui:**
+```tsx
+import { Progress } from "@/components/ui/progress"
+
+<Progress value={progress} max={100} />
+```
+
+**HeroUI:**
+```tsx
+import { Progress } from "@heroui/progress"
+
+<Progress
+  value={progress}
+  maxValue={100}
+  color="primary"
+  showValueLabel
+/>
+```
+
+**Circular Progress:**
+```tsx
+import { CircularProgress } from "@heroui/progress"
+
+<CircularProgress
+  value={progress}
+  color="primary"
+  showValueLabel
+/>
+```
+
+---
+
+#### Skeleton
+
+**shadcn/ui:**
+```tsx
+import { Skeleton } from "@/components/ui/skeleton"
+
+<Skeleton className="h-12 w-12 rounded-full" />
+<Skeleton className="h-4 w-[250px]" />
+```
+
+**HeroUI:**
+```tsx
+import { Skeleton } from "@heroui/skeleton"
+
+<Skeleton className="rounded-full w-12 h-12" />
+<Skeleton className="h-4 w-[250px] rounded-lg" />
+```
+
+**With isLoaded:**
+```tsx
+<Skeleton isLoaded={!isLoading} className="rounded-lg">
+  <div className="h-24 bg-default-200"></div>
+</Skeleton>
+```
+
+---
+
+#### Spinner
+
+**shadcn/ui:**
+```tsx
+// Usually custom or lucide-react Loader2
+import { Loader2 } from "lucide-react"
+
+<Loader2 className="animate-spin" />
+```
+
+**HeroUI:**
+```tsx
+import { Spinner } from "@heroui/spinner"
+
+<Spinner />
+<Spinner size="sm" />
+<Spinner size="lg" />
+<Spinner color="primary" />
+```
+
+---
+
+### Data Display Components
+
+#### Table
+
+**shadcn/ui:**
+```tsx
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table"
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John</TableCell>
+      <TableCell>john@example.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+**HeroUI:**
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableColumn,
+  TableBody,
+  TableRow,
+  TableCell,
+} from "@heroui/table"
+
+<Table>
+  <TableHeader>
+    <TableColumn>NAME</TableColumn>
+    <TableColumn>EMAIL</TableColumn>
+  </TableHeader>
+  <TableBody>
+    <TableRow key="1">
+      <TableCell>John</TableCell>
+      <TableCell>john@example.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+**Dynamic Rendering:**
+```tsx
+const columns = [
+  { key: "name", label: "NAME" },
+  { key: "email", label: "EMAIL" },
+]
+
+const rows = [
+  { id: 1, name: "John", email: "john@example.com" },
+  { id: 2, name: "Jane", email: "jane@example.com" },
+]
+
+<Table>
+  <TableHeader columns={columns}>
+    {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+  </TableHeader>
+  <TableBody items={rows}>
+    {(item) => (
+      <TableRow key={item.id}>
+        {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+      </TableRow>
+    )}
+  </TableBody>
+</Table>
+```
+
+---
+
+#### Pagination
+
+**shadcn/ui:**
+```tsx
+// Usually custom implementation
+```
+
+**HeroUI:**
+```tsx
+import { Pagination } from "@heroui/pagination"
+
+<Pagination
+  total={10}
+  page={currentPage}
+  onChange={setCurrentPage}
+/>
+```
+
+**With boundary & siblings:**
+```tsx
+<Pagination
+  total={20}
+  initialPage={1}
+  boundaries={2}
+  siblings={1}
+  onChange={setPage}
+/>
+```
+
+---
+
+## Common Patterns
+
+### Form with Validation
+
+**shadcn/ui:**
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import * as z from "zod"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form"
+
+const schema = z.object({
+  email: z.string().email(),
+})
+
+function MyForm() {
+  const form = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+**HeroUI:**
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import * as z from "zod"
+import { Button } from "@heroui/button"
+import { Input } from "@heroui/input"
+
+const schema = z.object({
+  email: z.string().email("Invalid email"),
+})
+
+function MyForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <Input
+        {...register("email")}
+        type="email"
+        label="Email"
+        variant="bordered"
+        isInvalid={!!errors.email}
+        errorMessage={errors.email?.message}
+      />
+      <Button type="submit" color="primary">
+        Submit
+      </Button>
+    </form>
+  )
+}
+```
+
+**Key Differences:**
+- No Form wrapper component needed
+- Simpler field registration
+- Built-in error display with `isInvalid` and `errorMessage`
+
+---
+
+### Loading States
+
+**shadcn/ui:**
+```tsx
+<Button disabled={isLoading}>
+  {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+  Submit
+</Button>
+```
+
+**HeroUI:**
+```tsx
+<Button isLoading={isLoading}>
+  Submit
+</Button>
+```
+
+Much cleaner! 🎉
+
+---
+
+### Conditional Rendering
+
+**shadcn/ui:**
+```tsx
+{isLoading ? (
+  <Skeleton className="h-20 w-full" />
+) : (
+  <Card>Content</Card>
+)}
+```
+
+**HeroUI:**
+```tsx
+<Skeleton isLoaded={!isLoading}>
+  <Card>Content</Card>
+</Skeleton>
+```
+
+---
+
+## Migration Checklist
+
+Use this checklist when converting a page:
+
+### Before Starting
+- [ ] Read this migration guide
+- [ ] Identify all shadcn components used in the page
+- [ ] Check if HeroUI equivalent exists
+
+### During Migration
+- [ ] Replace imports
+- [ ] Update component names
+- [ ] Convert `className` to `classNames` where needed
+- [ ] Update variant prop names
+- [ ] Update boolean prop names (checked → isSelected, disabled → isDisabled)
+- [ ] Replace custom loading spinners with `isLoading` prop
+- [ ] Update form validation display
+- [ ] Test all interactive states
+
+### After Migration
+- [ ] Remove unused shadcn component files
+- [ ] Test all functionality
+- [ ] Check mobile responsiveness
+- [ ] Verify accessibility
+- [ ] Check loading states
+- [ ] Verify error states
+- [ ] Test form validation
+
+---
+
+## Quick Reference: Prop Name Changes
+
+| shadcn/ui | HeroUI |
+|-----------|---------|
+| `className` | `classNames` (object) or `className` (string) |
+| `checked` | `isSelected` |
+| `disabled` | `isDisabled` |
+| `onCheckedChange` | `onValueChange` |
+| `onValueChange` (select) | `onChange` |
+| `open` | `isOpen` |
+| `onOpenChange` | `onClose` / `onOpenChange` |
+| `variant="default"` | `color="primary"` |
+| `variant="destructive"` | `color="danger"` |
+| `variant="outline"` | `variant="bordered"` |
+
+---
+
+## Tips
+
+1. **Start Simple:** Begin with simple components (Button, Input) before tackling complex ones
+
+2. **Use TypeScript:** HeroUI has excellent TypeScript support - use it!
+
+3. **Leverage Built-in States:** HeroUI components have built-in loading, disabled, invalid states
+
+4. **Consistent Variants:** Use `variant="bordered"` consistently for form inputs to match shadcn style
+
+5. **Check Examples:** See `UI_COMPONENTS_GUIDE.md` for complete HeroUI examples
+
+6. **Theme Customization:** If you need custom colors, use HeroUI's theme configuration
+
+7. **Accessibility:** HeroUI components are accessible by default - maintain this!
+
+---
+
+## Need Help?
+
+- **HeroUI Docs:** https://www.heroui.com/docs
+- **This Project Examples:** Check `src/components/` folder for real implementations
+- **UI Components Guide:** See `UI_COMPONENTS_GUIDE.md` for detailed HeroUI patterns
+
+---
+
+**Remember:** The goal is not just to replace components, but to leverage HeroUI's strengths:
+- Built-in states (loading, disabled, invalid)
+- Better TypeScript support
+- Consistent theming
+- Less custom code
+
+Good luck with your migration! 🚀