saha-ui 1.2.0 → 1.4.0

package/README.md

@@ -18,7 +18,7 @@
     <a href="#-installation">Installation</a> •
     <a href="#-features">Features</a> •
     <a href="#-components">Components</a> •
-    <a href="#-usage">Usage</a> •
+    <a href="#-quick-examples">Quick Examples</a> •
     <a href="#-documentation">Documentation</a>
   </p>
 </div>
@@ -27,7 +27,7 @@
 
 ## ✨ Features
 
-- 🎨 **14 Modern Components** - Button, ButtonGroup, Alert, Badge, Breadcrumb, Card, Accordion, Avatar, AvatarGroup, Tooltip, Link, List, Image, Carousel
+- 🎨 **29 Modern Components** - Button, ButtonGroup, Alert, Badge, Breadcrumb, Card, Chip, Divider, Accordion, Avatar, AvatarGroup, Tooltip, Link, List, Timeline, Tree, Image, Carousel, Steps, Table, Rating, Progress, Popover, PlayButton, Skeleton, Pagination, DatePicker, Tab, Input
 - 🌓 **Dark Mode** - Seamless theme switching with full dark mode support
 - 🔮 **Glass Morphism** - Beautiful backdrop blur effects across components
 - 🎯 **Type-Safe** - Full TypeScript support with comprehensive prop types
@@ -139,22 +139,502 @@ import { cn } from "saha-ui/lib/utils";
 
 ### Overview
 
-| Component       | Description                                                    | Status | CVA |
-| --------------- | -------------------------------------------------------------- | ------ | --- |
-| **Button**      | Action buttons with 8 variants and 4 sizes                     | ✅     | ✅  |
-| **ButtonGroup** | Grouped buttons with horizontal/vertical layouts               | ✅     | ✅  |
-| **Alert**       | Notification messages with 5 variants × 4 statuses             | ✅     | ✅  |
-| **Badge**       | Status indicators and labels with 9 variants                   | ✅     | ✅  |
-| **Breadcrumb**  | Navigation trail with 5 variants, 4 separators, and collapsing | ✅     | ✅  |
-| **Card**        | Container with 5 variants and sub-components                   | ✅     | ✅  |
-| **Accordion**   | Collapsible content with 5 behavior modes                      | ✅     | ✅  |
-| **Avatar**      | User profile images with status indicators                     | ✅     | ✅  |
-| **AvatarGroup** | Grouped avatars with overlap and count                         | ✅     | ✅  |
-| **Tooltip**     | Contextual hints with 5 variants                               | ✅     | ✅  |
-| **Link**        | Smart links with 9 variants and icon support                   | ✅     | ✅  |
-| **List**        | Modern lists with 5 variants and icon support                  | ✅     | ✅  |
-| **Image**       | Advanced image with lazy loading                               | ✅     | ✅  |
-| **Carousel**    | Image slider with 4 transition effects                         | ✅     | ✅  |
+| Component       | Description                                                              | Status | CVA |
+| --------------- | ------------------------------------------------------------------------ | ------ | --- |
+| **Button**      | Action buttons with 9 variants and 4 sizes                               | ✅     | ✅  |
+| **ButtonGroup** | Grouped buttons with horizontal/vertical layouts                         | ✅     | ✅  |
+| **Alert**       | Notification messages with 5 variants × 4 statuses                       | ✅     | ✅  |
+| **Badge**       | Status indicators and labels with 9 variants                             | ✅     | ✅  |
+| **Breadcrumb**  | Navigation trail with 5 variants, 4 separators, and collapsing           | ✅     | ✅  |
+| **Card**        | Container with 5 variants and sub-components                             | ✅     | ✅  |
+| **Chip**        | Interactive tags with 5 variants, deletable, and avatars                 | ✅     | ✅  |
+| **Divider**     | Content separator with 5 variants and label support                      | ✅     | ✅  |
+| **Accordion**   | Collapsible content with 5 behavior modes                                | ✅     | ✅  |
+| **Avatar**      | User profile images with status indicators                               | ✅     | ✅  |
+| **AvatarGroup** | Grouped avatars with overlap and count                                   | ✅     | ✅  |
+| **Tooltip**     | Contextual hints with 9 variants, 4 triggers, and interactive mode       | ✅     | ✅  |
+| **Link**        | Smart links with 9 variants and icon support                             | ✅     | ✅  |
+| **List**        | Modern lists with 5 variants and icon support                            | ✅     | ✅  |
+| **Timeline**    | Chronological events with 4 variants, positions, and statuses            | ✅     | ✅  |
+| **Tree**        | Hierarchical data with 4 variants, icons, and expand/collapse            | ✅     | ✅  |
+| **Image**       | Advanced image with lazy loading                                         | ✅     | ✅  |
+| **Carousel**    | Image slider with 4 transition effects                                   | ✅     | ✅  |
+| **Steps**       | Progress indicator with 4 variants, horizontal/vertical layouts          | ✅     | ✅  |
+| **Table**       | Data table with sorting, selection, 5 variants, and responsive           | ✅     | ✅  |
+| **Rating**      | Star rating with 6 variants, 4 sizes, multiple icons, half stars         | ✅     | ✅  |
+| **Progress**    | Progress bar with 9 variants, 5 sizes, animations, striped               | ✅     | ✅  |
+| **Popover**     | Rich content popover with 11 variants, 12 positions, 4 triggers          | ✅     | ✅  |
+| **PlayButton**  | Animated play/pause button with 9 variants, 4 sizes, smooth transitions  | ✅     | ✅  |
+| **Skeleton**    | Loading placeholder with 5 variants, 4 shapes, customizable animations   | ✅     | ✅  |
+| **Pagination**  | Page navigation with 5 variants, 3 sizes, ellipsis, customizable labels  | ✅     | ✅  |
+| **DatePicker**  | Calendar date picker with 5 variants, 3 sizes, date restrictions         | ✅     | ✅  |
+| **Tab**         | Tab navigation with 14 variants, 3 sizes, icons, badges, disabled states | ✅     | ✅  |
+| **Input**       | Text input with 10 variants, 4 sizes, icons, validation, all input types | ✅     | ✅  |
+
+---
+
+## ⚡ Quick Examples
+
+Here are simple examples for all 29 components to get you started quickly:
+
+### Button
+
+```tsx
+import { Button } from "saha-ui";
+
+<Button variant="primary">Click Me</Button>
+<Button variant="ghost" size="sm">Small Ghost</Button>
+```
+
+### ButtonGroup
+
+```tsx
+import { ButtonGroup, Button } from "saha-ui";
+
+<ButtonGroup>
+  <Button variant="primary">Save</Button>
+  <Button variant="ghost">Cancel</Button>
+</ButtonGroup>;
+```
+
+### Alert
+
+```tsx
+import { Alert } from "saha-ui";
+
+<Alert status="success">Operation completed successfully!</Alert>
+<Alert status="error" variant="filled" dismissible>
+  Error occurred!
+</Alert>
+```
+
+### Badge
+
+```tsx
+import { Badge } from "saha-ui";
+
+<Badge variant="primary">New</Badge>
+<Badge variant="success" dot pulse>Online</Badge>
+<Badge removable onRemove={() => console.log('removed')}>Tag</Badge>
+```
+
+### Breadcrumb
+
+```tsx
+import { Breadcrumb } from "saha-ui";
+
+const items = [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: 'Details', href: '/products/123' }
+];
+
+<Breadcrumb items={items} />
+<Breadcrumb items={items} variant="pills" separator="arrow" />
+```
+
+### Card
+
+```tsx
+import { Card, CardHeader, CardTitle, CardContent } from "saha-ui";
+
+<Card variant="glass" hoverable>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+  </CardHeader>
+  <CardContent>Your content here</CardContent>
+</Card>;
+```
+
+### Chip
+
+```tsx
+import { Chip } from "saha-ui";
+
+<Chip color="primary">JavaScript</Chip>
+<Chip deletable onDelete={() => console.log('deleted')}>
+  Remove me
+</Chip>
+<Chip clickable onClick={() => alert('clicked')}>
+  Click me
+</Chip>
+```
+
+### Divider
+
+```tsx
+import { Divider } from "saha-ui";
+
+<Divider />
+<Divider label="OR" />
+<Divider variant="gradient" thickness="medium" />
+<Divider orientation="vertical" className="h-24" />
+```
+
+### Accordion
+
+```tsx
+import { Accordion } from "saha-ui";
+
+const items = [
+  {
+    title: 'Section 1',
+    content: 'Content for section 1'
+  },
+  {
+    title: 'Section 2',
+    content: 'Content for section 2'
+  }
+];
+
+<Accordion items={items} />
+<Accordion items={items} variant="bordered" defaultOpen={[0]} />
+```
+
+### Avatar
+
+```tsx
+import { Avatar } from "saha-ui";
+
+<Avatar src="/user.jpg" alt="John" />
+<Avatar name="Jane Doe" size="lg" />
+<Avatar name="Bob" status="online" />
+```
+
+### AvatarGroup
+
+```tsx
+import { AvatarGroup, Avatar } from "saha-ui";
+
+<AvatarGroup max={3}>
+  <Avatar name="Alice" />
+  <Avatar name="Bob" />
+  <Avatar name="Carol" />
+  <Avatar name="Dave" />
+</AvatarGroup>;
+```
+
+### Tooltip
+
+```tsx
+import { Tooltip } from "saha-ui";
+
+// Basic tooltip
+<Tooltip content="This is a tooltip">
+  <Button>Hover me</Button>
+</Tooltip>
+
+// With variant and position
+<Tooltip content="Success message!" variant="success" position="right">
+  <Badge variant="success">Active</Badge>
+</Tooltip>
+
+// Interactive tooltip with click trigger
+<Tooltip
+  content={<div>Click <a href="#">here</a> for more</div>}
+  interactive={true}
+  trigger="click"
+  variant="glass"
+>
+  <Button>Click Me</Button>
+</Tooltip>
+```
+
+### Link
+
+```tsx
+import { Link } from "saha-ui";
+
+<Link href="/about">About Us</Link>
+<Link href="https://example.com" variant="primary" external>
+  External Link
+</Link>
+<Link href="/contact" showIcon>Contact</Link>
+```
+
+### List
+
+```tsx
+import { List } from "saha-ui";
+
+const items = [
+  { id: 1, content: 'First item' },
+  { id: 2, content: 'Second item' },
+  { id: 3, content: 'Third item' }
+];
+
+<List items={items} />
+<List items={items} variant="bordered" />
+```
+
+### Timeline
+
+```tsx
+import { Timeline } from "saha-ui";
+import { Rocket, Package, Check } from "lucide-react";
+
+const events = [
+  { id: 1, title: 'Project Started', description: 'Initial setup', time: '2 hours ago', icon: Rocket },
+  { id: 2, title: 'Development', description: 'Building features', time: '1 hour ago', icon: Package, status: 'primary' as const },
+  { id: 3, title: 'Completed', description: 'Ready to deploy', time: 'Just now', icon: Check, status: 'success' as const }
+];
+
+<Timeline items={events} />
+<Timeline items={events} variant="gradient" position="alternate" />
+```
+
+### Tree
+
+```tsx
+import { Tree } from "saha-ui";
+import { Folder, File } from "lucide-react";
+
+const nodes = [
+  {
+    id: 1,
+    label: 'src',
+    icon: <Folder size={16} />,
+    children: [
+      { id: 2, label: 'components', icon: <Folder size={16} /> },
+      { id: 3, label: 'App.tsx', icon: <File size={16} /> }
+    ]
+  }
+];
+
+<Tree nodes={nodes} />
+<Tree nodes={nodes} variant="glass" onNodeClick={(id) => console.log(id)} />
+```
+
+### Image
+
+```tsx
+import { Image } from "saha-ui";
+
+<Image
+  src="/photo.jpg"
+  alt="Description"
+  variant="rounded"
+/>
+
+<Image
+  src="/photo.jpg"
+  alt="Description"
+  fit="cover"
+  size="lg"
+  loading="lazy"
+/>
+```
+
+### Carousel
+
+```tsx
+import { Carousel } from "saha-ui";
+
+const images = [
+  { src: '/image1.jpg', alt: 'Image 1' },
+  { src: '/image2.jpg', alt: 'Image 2' },
+  { src: '/image3.jpg', alt: 'Image 3' }
+];
+
+<Carousel images={images} />
+<Carousel images={images} effect="fade" autoplay />
+```
+
+### Steps
+
+```tsx
+import { Steps } from "saha-ui";
+
+const steps = [
+  { id: 1, title: 'Account', description: 'Create your account' },
+  { id: 2, title: 'Profile', description: 'Fill in your details' },
+  { id: 3, title: 'Complete', description: 'You're all set!' }
+];
+
+<Steps steps={steps} current={1} />
+<Steps steps={steps} current={1} variant="glass" orientation="vertical" />
+```
+
+### Table
+
+```tsx
+import { Table } from "saha-ui";
+
+const columns = [
+  { id: 'name', header: 'Name', accessor: 'name', sortable: true },
+  { id: 'email', header: 'Email', accessor: 'email' },
+  { id: 'role', header: 'Role', accessor: 'role' }
+];
+
+const data = [
+  { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin' },
+  { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User' }
+];
+
+<Table columns={columns} data={data} sortable />
+<Table columns={columns} data={data} variant="glass" selectable />
+```
+
+### Rating
+
+```tsx
+import { Rating } from "saha-ui";
+
+<Rating value={4} />
+<Rating value={4.5} precision="half" showValue count={128} />
+<Rating value={0} onChange={(value) => console.log(value)} size="lg" />
+<Rating value={4} icon="heart" variant="gradient" size="lg" />
+```
+
+### Progress
+
+```tsx
+import { Progress } from "saha-ui";
+
+<Progress value={75} />
+<Progress value={60} variant="primary" size="lg" showValue />
+<Progress value={80} variant="success" striped stripedAnimated />
+<Progress indeterminate variant="gradient" />
+```
+
+### Popover
+
+```tsx
+import { Popover, Button } from "saha-ui";
+
+<Popover content="Simple popover content">
+  <Button>Click me</Button>
+</Popover>
+
+<Popover
+  title="Settings"
+  variant="primary"
+  position="right"
+  content={<div>Your settings here</div>}
+  footer={<Button size="sm">Save</Button>}
+>
+  <Button>Open Settings</Button>
+</Popover>
+```
+
+### PlayButton
+
+```tsx
+import { PlayButton } from "saha-ui";
+
+<PlayButton />
+
+<PlayButton variant="primary" size="lg" />
+
+<PlayButton
+  isPlaying={playing}
+  onToggle={(playing) => setPlaying(playing)}
+  variant="success"
+  pulse
+  glow
+/>
+```
+
+### Skeleton
+
+```tsx
+import { Skeleton } from "saha-ui";
+
+<Skeleton width="100%" height="20px" />
+
+<Skeleton variant="shimmer" count={3} />
+
+<Skeleton shape="circle" width="48px" height="48px" variant="pulse" />
+```
+
+### Pagination
+
+```tsx
+import { Pagination } from "saha-ui";
+
+<Pagination totalPages={10} currentPage={1} onPageChange={(page) => setPage(page)} />
+
+<Pagination variant="primary" size="lg" totalPages={20} currentPage={5} />
+
+<Pagination variant="minimal" shape="pill" totalPages={50} currentPage={25} />
+```
+
+### DatePicker
+
+```tsx
+import { DatePicker } from "saha-ui";
+
+<DatePicker value={date} onChange={(date) => setDate(date)} />
+
+<DatePicker variant="primary" size="lg" placeholder="Pick a date" />
+
+<DatePicker minDate={new Date()} maxDate={futureDate} />
+```
+
+### Tab
+
+```tsx
+import { Tab } from "saha-ui";
+
+const tabs = [
+  { label: "Profile", value: "profile" },
+  { label: "Settings", value: "settings" },
+];
+
+<Tab tabs={tabs} value={activeTab} onChange={setActiveTab} />
+
+<Tab tabs={tabs} variant="primary" size="lg" fullWidth />
+
+<Tab
+  tabs={[
+    { label: "Home", value: "home", icon: <HomeIcon /> },
+    { label: "Messages", value: "messages", badge: "5" },
+  ]}
+/>
+```
+
+### Input
+
+```tsx
+import { Input } from "saha-ui";
+import { Mail, Lock } from "lucide-react";
+
+// Basic input
+<Input placeholder="Enter text..." />
+
+// With label and variant
+<Input
+  label="Email"
+  type="email"
+  variant="primary"
+  placeholder="you@example.com"
+/>
+
+// With icons
+<Input
+  label="Search"
+  variant="outline"
+  startIcon={<Mail size={18} />}
+  placeholder="Search..."
+/>
+
+// With validation
+<Input
+  label="Password"
+  type="password"
+  variant="error"
+  error="Password is required"
+  startIcon={<Lock size={18} />}
+/>
+
+// With character counter
+<Input
+  label="Bio"
+  maxLength={100}
+  showCounter
+  helperText="Maximum 100 characters"
+/>
+```
 
 ---
 
@@ -162,9 +642,9 @@ import { cn } from "saha-ui/lib/utils";
 
 ### Button
 
-Action buttons with modern effects and 8 visual variants.
+Action buttons with modern effects and 9 visual variants.
 
-**Variants:** `primary` `secondary` `accent` `success` `warning` `error` `ghost` `glass`
+**Variants:** `primary` `secondary` `accent` `success` `warning` `error` `outline` `ghost` `glass`
 **Sizes:** `sm` `md` `lg` `xl`
 
 ```tsx
@@ -630,51 +1110,423 @@ const customClass = cardVariants({ variant: 'glass-strong', padding: 'xl', round
 
 ---
 
-### Accordion
+### Chip
 
-Collapsible content sections with smooth animations and multiple behavior modes.
+Interactive tag component with multiple variants, deletable functionality, and icon/avatar support.
 
-**Variants:** `default` `bordered` `flush` `glass`  
+**Variants:** `filled` `outlined` `soft` `gradient` `glass`  
+**Colors:** `default` `primary` `secondary` `success` `warning` `error` `info`  
 **Sizes:** `sm` `md` `lg`
 
 ```tsx
-import { Accordion } from "saha-ui";
+import { Chip } from "saha-ui";
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionTrigger>Item 1</AccordionTrigger>
-    <AccordionContent>Content for item 1</AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="item-2">
-    <AccordionTrigger>Item 2</AccordionTrigger>
-    <AccordionContent>Content for item 2</AccordionContent>
-  </AccordionItem>
-</Accordion>;
-```
+// Basic chip
+<Chip>JavaScript</Chip>
 
-**Features:**
+// With color and variant
+<Chip color="primary" variant="filled">Premium</Chip>
 
-- 🎭 Multiple types: single, multiple, toggle
-- 🚀 Fast open/close animations
-- 🔒 Collapsible and non-collapsible modes
-- 🎨 Glass morphism and gradient support
-- ♿ Fully accessible with ARIA attributes
+// Deletable chip
+<Chip deletable onDelete={() => console.log('deleted')}>
+  Remove me
+</Chip>
 
----
+// With icon
+import { Tag } from "lucide-react";
+<Chip icon={<Tag size={14} />} color="success">
+  Tagged
+</Chip>
 
-### Avatar
+// With avatar
+<Chip avatar={<Avatar size="xs" src="..." />}>
+  John Doe
+</Chip>
 
-Profile images with status indicators and smart fallbacks.
+// Clickable chip
+<Chip clickable onClick={() => console.log('clicked')}>
+  Click me
+</Chip>
 
-**Sizes:** `xs` `sm` `md` `lg` `xl` `2xl`  
-**Shapes:** `circle` `square` `rounded`  
-**Status:** `online` `offline` `away` `busy` `none`
+// Different sizes
+<Chip size="sm">Small</Chip>
+<Chip size="lg">Large</Chip>
 
-```tsx
-import { Avatar } from "saha-ui";
+// Disabled state
+<Chip disabled color="error">Disabled</Chip>
+
+// Combined features
+<Chip
+  avatar={<Avatar size="xs" name="Alice" />}
+  deletable
+  onDelete={() => handleRemove()}
+  color="primary"
+  variant="outlined"
+>
+  Alice
+</Chip>
+```
 
-<Avatar
-  src="/user.jpg"
+**Features:**
+
+- ✨ **5 Modern Variants** - filled, outlined, soft, gradient, glass
+- 🎨 **7 Color Options** - comprehensive color palette
+- 📏 **3 Size Options** - sm, md, lg for different contexts
+- 🗑️ **Deletable** - built-in close button with callback
+- 🖼️ **Avatar Support** - integrate user avatars seamlessly
+- 🎯 **Icon Support** - add icons for visual context
+- 👆 **Clickable** - interactive chips with hover effects
+- ♿ **Accessible** - keyboard navigation and ARIA support
+- 🎭 **CVA Powered** - type-safe variant composition
+- 🌓 **Dark Mode** - fully themed for light and dark modes
+- 💫 **Interactive States** - hover, active, and disabled states
+
+**Variant Details:**
+
+- **filled** - Solid background with vibrant colors (default)
+- **outlined** - Border-only design with transparent background
+- **soft** - Subtle background with soft color tones
+- **gradient** - Gradient background with depth
+- **glass** - Glassmorphism effect with backdrop blur
+
+**Props:**
+
+```tsx
+interface ChipProps {
+  variant?: "filled" | "outlined" | "soft" | "gradient" | "glass";
+  color?:
+    | "default"
+    | "primary"
+    | "secondary"
+    | "success"
+    | "warning"
+    | "error"
+    | "info";
+  size?: "sm" | "md" | "lg";
+  icon?: React.ReactNode; // Optional icon at start
+  avatar?: React.ReactNode; // Optional avatar at start
+  deletable?: boolean; // Show delete button
+  onDelete?: () => void; // Delete callback
+  disabled?: boolean; // Disable interactions
+  clickable?: boolean; // Enable click interactions
+  onClick?: () => void; // Click handler
+  className?: string;
+}
+```
+
+**Advanced Usage:**
+
+```tsx
+// Tag management system
+<div className="flex flex-wrap gap-2">
+  {tags.map((tag) => (
+    <Chip
+      key={tag.id}
+      deletable
+      onDelete={() => removeTag(tag.id)}
+      color="primary"
+      variant="soft"
+    >
+      {tag.name}
+    </Chip>
+  ))}
+</div>
+
+// User selection with avatars
+<div className="flex flex-wrap gap-2">
+  {selectedUsers.map((user) => (
+    <Chip
+      key={user.id}
+      avatar={<Avatar size="xs" src={user.avatar} name={user.name} />}
+      deletable
+      onDelete={() => removeUser(user.id)}
+      variant="outlined"
+      color="primary"
+    >
+      {user.name}
+    </Chip>
+  ))}
+</div>
+
+// Filter chips
+<div className="flex flex-wrap gap-2">
+  <Chip
+    clickable
+    onClick={() => setFilter('all')}
+    color={filter === 'all' ? 'primary' : 'default'}
+    variant={filter === 'all' ? 'filled' : 'outlined'}
+  >
+    All
+  </Chip>
+  <Chip
+    clickable
+    onClick={() => setFilter('active')}
+    color={filter === 'active' ? 'success' : 'default'}
+    variant={filter === 'active' ? 'filled' : 'outlined'}
+  >
+    Active
+  </Chip>
+  <Chip
+    clickable
+    onClick={() => setFilter('pending')}
+    color={filter === 'pending' ? 'warning' : 'default'}
+    variant={filter === 'pending' ? 'filled' : 'outlined'}
+  >
+    Pending
+  </Chip>
+</div>
+
+// Technology stack showcase
+<div className="space-y-3">
+  <div>
+    <p className="text-sm font-medium mb-2">Frontend</p>
+    <div className="flex flex-wrap gap-2">
+      <Chip icon={<Code size={14} />} color="info" variant="soft">React</Chip>
+      <Chip icon={<Code size={14} />} color="info" variant="soft">Vue</Chip>
+      <Chip icon={<Code size={14} />} color="info" variant="soft">Angular</Chip>
+    </div>
+  </div>
+  <div>
+    <p className="text-sm font-medium mb-2">Backend</p>
+    <div className="flex flex-wrap gap-2">
+      <Chip icon={<Server size={14} />} color="success" variant="soft">Node.js</Chip>
+      <Chip icon={<Server size={14} />} color="success" variant="soft">Python</Chip>
+      <Chip icon={<Server size={14} />} color="success" variant="soft">Go</Chip>
+    </div>
+  </div>
+</div>
+```
+
+**CVA Integration:**
+
+```tsx
+import { chipVariants } from "saha-ui";
+
+// Use exported variants for custom styling
+const customChipClass = chipVariants({
+  variant: "gradient",
+  color: "primary",
+  size: "lg",
+  clickable: true,
+});
+```
+
+---
+
+### Divider
+
+Content separator component with 5 modern variants, optional labels, and decorative elements.
+
+**Variants:** `solid` `dashed` `dotted` `gradient` `glass`  
+**Orientation:** `horizontal` `vertical`  
+**Thickness:** `thin` `medium` `thick`  
+**Spacing:** `none` `xs` `sm` `md` `lg` `xl`
+
+```tsx
+import { Divider } from "saha-ui";
+
+// Basic divider
+<Divider />
+
+// With label
+<Divider label="OR" />
+
+// Gradient variant
+<Divider variant="gradient" thickness="medium" />
+
+// Vertical divider
+<div className="flex items-center h-24">
+  <div>Section 1</div>
+  <Divider orientation="vertical" className="h-full" />
+  <div>Section 2</div>
+</div>
+
+// Decorative with label
+<Divider label="Continue Reading" decorative />
+
+// Custom positioning
+<Divider label="Section Start" labelPosition="left" variant="dashed" />
+
+// Different thickness
+<Divider thickness="thick" variant="solid" />
+
+// Custom spacing
+<Divider spacing="xl" variant="gradient" />
+```
+
+**Features:**
+
+- ✨ **5 Modern Variants** - solid, dashed, dotted, gradient, glass
+- 🔄 **Dual Orientation** - horizontal and vertical support
+- 📏 **3 Thickness Options** - thin, medium, thick
+- 🏷️ **Label Support** - optional text labels with positioning
+- ⭐ **Decorative Elements** - sparkle icons for emphasis
+- 📐 **Flexible Spacing** - 6 spacing options (none to xl)
+- 🎨 **Theme-Aware** - OKLCH colors with dark mode support
+- ♿ **Accessible** - semantic HTML with ARIA roles
+- 🎭 **CVA Powered** - type-safe variant composition
+- 📱 **Responsive** - works in any layout context
+
+**Variant Details:**
+
+- **solid** - Clean solid line (default)
+- **dashed** - Dashed line pattern
+- **dotted** - Dotted line pattern
+- **gradient** - Smooth gradient transition from transparent to border color
+- **glass** - Glassmorphism effect with backdrop blur
+
+**Props:**
+
+```tsx
+interface DividerProps {
+  variant?: "solid" | "dashed" | "dotted" | "gradient" | "glass";
+  orientation?: "horizontal" | "vertical";
+  thickness?: "thin" | "medium" | "thick";
+  spacing?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+  label?: React.ReactNode; // Optional label content
+  labelPosition?: "left" | "center" | "right";
+  decorative?: boolean; // Add sparkle icons
+  className?: string;
+}
+```
+
+**Advanced Usage:**
+
+```tsx
+// In forms - separating auth methods
+<Card>
+  <CardContent>
+    <Button variant="primary" className="w-full">
+      Sign in with Email
+    </Button>
+
+    <Divider label="OR" variant="gradient" spacing="sm" />
+
+    <Button variant="outline" className="w-full">
+      Continue with GitHub
+    </Button>
+  </CardContent>
+</Card>
+
+// Content sections with labels
+<article>
+  <p>Introduction paragraph...</p>
+
+  <Divider
+    label="Section 1"
+    labelPosition="left"
+    variant="dashed"
+    spacing="lg"
+  />
+
+  <p>Main content...</p>
+
+  <Divider
+    label="Conclusion"
+    labelPosition="left"
+    variant="dashed"
+    spacing="lg"
+  />
+
+  <p>Summary...</p>
+
+  <Divider decorative spacing="lg" variant="gradient" />
+</article>
+
+// Vertical layout sections
+<div className="flex h-64">
+  <div className="flex-1">Left Panel</div>
+  <Divider
+    orientation="vertical"
+    variant="gradient"
+    className="h-full"
+  />
+  <div className="flex-1">Right Panel</div>
+</div>
+
+// Dashboard sections
+<div className="flex gap-4 h-48">
+  <Card className="flex-1">Stats 1</Card>
+  <Divider orientation="vertical" variant="glass" className="h-full" />
+  <Card className="flex-1">Stats 2</Card>
+  <Divider orientation="vertical" variant="glass" className="h-full" />
+  <Card className="flex-1">Stats 3</Card>
+</div>
+```
+
+**CVA Integration:**
+
+```tsx
+import {
+  dividerVariants,
+  dividerLineVariants,
+  dividerLabelVariants,
+} from "saha-ui";
+
+// Use exported variants for custom styling
+const customContainerClass = dividerVariants({
+  orientation: "horizontal",
+  spacing: "lg",
+});
+
+const customLineClass = dividerLineVariants({
+  variant: "gradient",
+  orientation: "horizontal",
+  thickness: "medium",
+});
+
+const customLabelClass = dividerLabelVariants({
+  orientation: "horizontal",
+});
+```
+
+---
+
+### Accordion
+
+Collapsible content sections with smooth animations and multiple behavior modes.
+
+**Variants:** `default` `bordered` `flush` `glass`  
+**Sizes:** `sm` `md` `lg`
+
+```tsx
+import { Accordion } from "saha-ui";
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Item 1</AccordionTrigger>
+    <AccordionContent>Content for item 1</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>Item 2</AccordionTrigger>
+    <AccordionContent>Content for item 2</AccordionContent>
+  </AccordionItem>
+</Accordion>;
+```
+
+**Features:**
+
+- 🎭 Multiple types: single, multiple, toggle
+- 🚀 Fast open/close animations
+- 🔒 Collapsible and non-collapsible modes
+- 🎨 Glass morphism and gradient support
+- ♿ Fully accessible with ARIA attributes
+
+---
+
+### Avatar
+
+Profile images with status indicators and smart fallbacks.
+
+**Sizes:** `xs` `sm` `md` `lg` `xl` `2xl`  
+**Shapes:** `circle` `square` `rounded`  
+**Status:** `online` `offline` `away` `busy` `none`
+
+```tsx
+import { Avatar } from "saha-ui";
+
+<Avatar
+  src="/user.jpg"
   alt="John Doe"
   size="lg"
   shape="circle"
@@ -733,33 +1585,229 @@ import { AvatarGroup } from "saha-ui";
 
 ### Tooltip
 
-Contextual hints with smart positioning and delays.
+Contextual hints and information with smart positioning, multiple trigger types, and interactive capabilities.
 
-**Variants:** `default` `dark` `light` `glass` `primary`  
+**Variants:** `default` `dark` `light` `glass` `primary` `success` `warning` `error` `info`  
 **Positions:** `top` `bottom` `left` `right`  
-**Sizes:** `sm` `md` `lg`
+**Sizes:** `sm` `md` `lg`  
+**Triggers:** `hover` `click` `focus` `manual`
 
 ```tsx
 import { Tooltip } from "saha-ui";
 
+// Basic tooltip
 <Tooltip
   content="This is helpful information"
   position="top"
   variant="glass"
-  size="md"
-  delay={200}
-  arrow
 >
   <Button>Hover me</Button>
-</Tooltip>;
+</Tooltip>
+
+// Status tooltips
+<Tooltip content="All systems operational" variant="success">
+  <Badge variant="success">Active</Badge>
+</Tooltip>
+
+<Tooltip content="Warning: Check this!" variant="warning" position="right">
+  <span className="cursor-help">⚠</span>
+</Tooltip>
+
+// Interactive tooltip with click trigger
+<Tooltip
+  content={
+    <div className="space-y-2">
+      <p className="font-semibold">Interactive Content</p>
+      <Button size="sm">Click Me</Button>
+    </div>
+  }
+  interactive={true}
+  trigger="click"
+  variant="glass"
+  maxWidth="200px"
+>
+  <Button>Click for Options</Button>
+</Tooltip>
+
+// Controlled tooltip
+const [open, setOpen] = useState(false);
+<Tooltip
+  content="Controlled tooltip"
+  open={open}
+  onOpenChange={setOpen}
+  trigger="manual"
+>
+  <Button onClick={() => setOpen(!open)}>Toggle</Button>
+</Tooltip>
+
+// Help icon tooltips
+<div className="flex items-center gap-2">
+  <span>Username</span>
+  <Tooltip
+    content="Enter your unique username (3-20 characters)"
+    variant="info"
+    size="sm"
+  >
+    <span className="cursor-help text-muted-foreground">ⓘ</span>
+  </Tooltip>
+</div>
+
+// Custom delay and no arrow
+<Tooltip
+  content="Appears after 1 second"
+  delay={1000}
+  arrow={false}
+  variant="primary"
+>
+  <Button>Delayed Tooltip</Button>
+</Tooltip>
 ```
 
+**Variants:**
+
+- **default** - Standard tooltip with card background and subtle shadow
+- **dark** - Dark theme tooltip with deep gray background
+- **light** - Light theme tooltip, bright background
+- **glass** - Glass morphism effect with backdrop blur
+- **primary** - Primary color with brand styling
+- **success** - Green success indicator
+- **warning** - Yellow warning indicator
+- **error** - Red error indicator
+- **info** - Blue information indicator
+
 **Features:**
 
-- ⏱️ Configurable delay (default 200ms)
-- ➡️ Optional arrow pointer
-- 🎨 5 beautiful variants
-- 🔮 Glass morphism support
+- 🎨 **9 Modern Variants** - Each optimized for different contexts
+- 📍 **4 Positions** - Top, bottom, left, right with smart alignment
+- 🖱️ **4 Trigger Types** - Hover, click, focus, or manual control
+- ⏱️ **Configurable Delay** - Customizable show delay (default 200ms)
+- ➡️ **Optional Arrow** - Pointing arrow for better UX
+- 💫 **Interactive Mode** - Allow interaction with tooltip content
+- 🎯 **Controlled Mode** - Programmatic control via props
+- 📏 **3 Sizes** - sm, md, lg with responsive text
+- 🔮 **Glass Effects** - Beautiful backdrop blur and transparency
+- 🌙 **Dark Mode** - Optimized for both light and dark themes
+- ♿ **Accessible** - Proper ARIA attributes and keyboard support
+- 📦 **Tree-Shakeable** - Import only what you need
+- 🎭 **Custom Styling** - ClassName props for tooltip and wrapper
+- 📐 **Adjustable Offset** - Control distance from trigger element
+- 🚫 **Disable Option** - Conditionally disable tooltips
+- � **Type-Safe** - Full CVA integration with exported variants
+
+**Props:**
+
+- `content`: ReactNode - Tooltip content (required)
+- `children`: ReactNode - Trigger element (required)
+- `variant`: 'default' | 'dark' | 'light' | 'glass' | 'primary' | 'success' | 'warning' | 'error' | 'info' (default: 'default')
+- `position`: 'top' | 'bottom' | 'left' | 'right' (default: 'top')
+- `size`: 'sm' | 'md' | 'lg' (default: 'md')
+- `trigger`: 'hover' | 'click' | 'focus' | 'manual' (default: 'hover')
+- `delay`: number - Show delay in ms (default: 200)
+- `arrow`: boolean - Show arrow pointer (default: true)
+- `interactive`: boolean - Allow interaction with content (default: false)
+- `open`: boolean - Controlled open state
+- `onOpenChange`: (open: boolean) => void - Open state change callback
+- `tooltipClassName`: string - Custom tooltip content class
+- `wrapperClassName`: string - Custom wrapper class
+- `maxWidth`: string - Maximum width (default: '320px')
+- `offset`: number - Distance from trigger in px (default: 8)
+- `disabled`: boolean - Disable tooltip (default: false)
+- `className`: string - Additional CSS classes
+
+**Advanced Usage:**
+
+```tsx
+// Help system with different variants
+const HelpTooltips = () => (
+  <div className="space-y-4">
+    <div className="flex items-center gap-2">
+      <span>Email</span>
+      <Tooltip
+        content="We'll never share your email"
+        variant="success"
+        size="sm"
+      >
+        <span className="cursor-help">✓</span>
+      </Tooltip>
+    </div>
+
+    <div className="flex items-center gap-2">
+      <span>Password</span>
+      <Tooltip
+        content="Must be at least 8 characters"
+        variant="warning"
+        size="sm"
+      >
+        <span className="cursor-help">⚠</span>
+      </Tooltip>
+    </div>
+  </div>
+);
+
+// Interactive tooltip menu
+<Tooltip
+  content={
+    <div className="space-y-2 w-48">
+      <p className="font-semibold text-sm">Quick Actions</p>
+      <div className="space-y-1">
+        <Button size="sm" variant="ghost" className="w-full justify-start">
+          Edit
+        </Button>
+        <Button size="sm" variant="ghost" className="w-full justify-start">
+          Share
+        </Button>
+        <Button
+          size="sm"
+          variant="ghost"
+          className="w-full justify-start text-red-500"
+        >
+          Delete
+        </Button>
+      </div>
+    </div>
+  }
+  interactive={true}
+  trigger="click"
+  variant="glass"
+  maxWidth="220px"
+  arrow={false}
+>
+  <Button size="sm" variant="ghost">
+    ⋯
+  </Button>
+</Tooltip>;
+
+// Status indicator tooltips
+const StatusIndicator = ({ status, message }) => (
+  <Tooltip
+    content={message}
+    variant={status === "online" ? "success" : "error"}
+    size="sm"
+  >
+    <Badge variant={status === "online" ? "success" : "error"}>{status}</Badge>
+  </Tooltip>
+);
+```
+
+**CVA Integration:**
+
+```tsx
+import { tooltipVariants, arrowVariants } from "saha-ui";
+
+// Use exported variants for custom styling
+const customTooltipClass = tooltipVariants({
+  variant: "glass",
+  size: "lg",
+  position: "top",
+  interactive: true,
+  className: "my-custom-class",
+});
+
+const customArrowClass = arrowVariants({
+  variant: "primary",
+  position: "bottom",
+});
+```
 
 ---
 
@@ -1031,38 +2079,543 @@ const customItemClass = listItemVariants({
 
 ---
 
-### Image
+### Timeline
 
-Advanced image component with loading states and effects.
+Chronological event display with 4 modern variants, flexible positioning, status indicators, and icon support powered by CVA.
 
-**Variants:** `default` `rounded` `circular` `bordered` `glass`  
-**Fit:** `cover` `contain` `fill` `none` `scale-down`  
-**Sizes:** `xs` `sm` `md` `lg` `xl` `2xl` `full`
+**Variants:** `default` `outlined` `gradient` `minimal`  
+**Positions:** `left` `right` `alternate`  
+**Sizes:** `sm` `md` `lg`  
+**Status:** `default` `primary` `success` `warning` `error` `info`
 
 ```tsx
-import { Image } from "saha-ui";
+import { Timeline } from 'saha-ui';
+import { Rocket, Code, Package, Check } from 'lucide-react';
 
-<Image
-  src="/photo.jpg"
-  alt="Beautiful photo"
-  variant="rounded"
-  size="lg"
-  fit="cover"
-  zoomOnHover
-  aspectRatio="16/9"
-  lazy
-  showSkeleton
-  fallbackSrc="/fallback.jpg"
-/>;
-```
+// Basic Timeline
+<Timeline
+  items={[
+    { id: 1, title: 'Project Started', description: 'Initial setup', time: '2 hours ago' },
+    { id: 2, title: 'Development', description: 'Building features', time: '1 hour ago' },
+    { id: 3, title: 'Completed', description: 'Ready to deploy', time: 'Just now' }
+  ]}
+/>
 
-**Features:**
+// Timeline with Icons
+<Timeline
+  items={[
+    { id: 1, title: 'Planning', description: 'Define requirements', time: 'Jan 1', icon: Rocket },
+    { id: 2, title: 'Development', description: 'Build features', time: 'Jan 15', icon: Code, status: 'primary' },
+    { id: 3, title: 'Testing', description: 'QA process', time: 'Feb 1', icon: Package, status: 'warning' },
+    { id: 4, title: 'Launch', description: 'Production ready', time: 'Feb 15', icon: Check, status: 'success' }
+  ]}
+  variant="gradient"
+/>
 
-- ⚡ Lazy loading by default
-- 💀 Animated loading skeleton
-- 🔄 Smart error handling with fallback
-- 🔍 Zoom on hover effect
-- 📐 Aspect ratio control
+// Alternate Positioning
+<Timeline
+  items={[
+    { id: 1, title: 'Order Placed', description: 'We received your order', time: '2h ago', status: 'success' },
+    { id: 2, title: 'Processing', description: 'Preparing items', time: '1h ago', status: 'primary', active: true },
+    { id: 3, title: 'Shipped', description: 'On the way', time: 'Pending', status: 'default' },
+    { id: 4, title: 'Delivered', description: 'Enjoy your purchase', time: 'Pending', status: 'default' }
+  ]}
+  position="alternate"
+  variant="outlined"
+/>
+
+// Different Sizes
+<Timeline
+  items={[
+    { id: 1, title: 'Small', description: 'Compact view', time: 'Now' },
+    { id: 2, title: 'Medium', description: 'Default size', time: 'Now' },
+    { id: 3, title: 'Large', description: 'Spacious layout', time: 'Now' }
+  ]}
+  size="lg"
+/>
+
+// Left/Right Positioning
+<Timeline
+  position="right"
+  items={[
+    { id: 1, title: 'Event 1', description: 'Content aligned right', time: '10:00 AM' },
+    { id: 2, title: 'Event 2', description: 'All items on right', time: '11:00 AM' }
+  ]}
+/>
+```
+
+**Variants:**
+
+- **default** - Clean design with colored dot and connecting line
+- **outlined** - Bordered container with subtle background
+- **gradient** - Vibrant gradient background with enhanced visual appeal
+- **minimal** - Ultra-clean design with minimal visual elements
+
+**Features:**
+
+- 🎨 **4 Modern Variants** - Each with unique visual design
+- 📍 **3 Positioning Modes** - Left, right, or alternating layout
+- 🎯 **6 Status Colors** - default, primary, success, warning, error, info
+- ✨ **Icon Support** - Custom icons with automatic fallbacks (Circle for active, Check for success)
+- 💫 **Active State** - Enhanced styling with scale and shadow effects
+- 📏 **3 Sizes** - sm, md, lg with responsive spacing
+- 🔮 **Smart Layout** - Responsive alternate positioning (left on even, right on odd)
+- 🌈 **Status Indicators** - Color-coded dots matching status colors
+- 🎭 **Compound Variants** - Position + size combinations for perfect spacing
+- 🌙 **Dark Mode** - Optimized colors and contrast for dark theme
+- ♿ **Accessible** - Semantic HTML with proper ARIA attributes
+- 📦 **Tree-Shakeable** - Import only what you need
+- 🎯 **Type-Safe** - Full CVA integration with exported variants
+- 🎨 **Custom Styling** - Per-item and global className overrides
+- 🎯 **Dot Shapes** - Circle, square, diamond, ring shapes
+- 📏 **Line Styles** - Solid, dashed, dotted, gradient
+- 🎨 **Custom Colors** - Override line and dot colors
+- 🔄 **Interactive** - Click handlers and custom render functions
+- 👁️ **Conditional Rendering** - Hide dots/lines per item
+- 📍 **Flexible Time Display** - Show time on opposite side in alternate mode
+
+**Props:**
+
+**TimelineItem Interface:**
+
+```tsx
+interface TimelineItem {
+  id: number | string;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  time?: React.ReactNode;
+  icon?: React.ReactNode;
+  status?: "default" | "primary" | "success" | "warning" | "error" | "info";
+  active?: boolean;
+  // New customization props
+  dotColor?: string; // Custom dot color
+  className?: string; // Custom item className
+  dotClassName?: string; // Custom dot className
+  contentClassName?: string; // Custom content className
+  hideDot?: boolean; // Hide dot for this item
+  hideLine?: boolean; // Hide line after this item
+}
+```
+
+**Timeline Component:**
+
+- `items`: TimelineItem[] - Array of timeline events (required)
+- `variant`: 'default' | 'outlined' | 'gradient' | 'minimal' (default: 'default')
+- `position`: 'left' | 'right' | 'alternate' (default: 'left')
+- `size`: 'sm' | 'md' | 'lg' (default: 'md')
+- `className`: string - Additional CSS classes
+- `itemClassName`: string - Custom class for all items
+- `dotClassName`: string - Custom class for all dots
+- `contentClassName`: string - Custom class for all content
+- `lineClassName`: string - Custom class for the timeline line
+- `lineStyle`: 'solid' | 'dashed' | 'dotted' | 'gradient' (default: 'solid')
+- `dotShape`: 'circle' | 'square' | 'diamond' | 'ring' (default: 'circle')
+- `lineColor`: string - Custom line color
+- `lineWidth`: string - Line width (default: '2px')
+- `showTimeOnOppositeSide`: boolean - Show time on opposite side in alternate mode
+- `hideIcons`: boolean - Hide all icons
+- `animateOnScroll`: boolean - Animate items on scroll
+- `renderItem`: (item, index) => ReactNode - Custom render function
+- `onItemClick`: (item, index) => void - Click handler
+
+**Advanced Usage:**
+
+```tsx
+// Custom Dot Shapes and Line Styles
+<Timeline
+  dotShape="diamond"
+  lineStyle="dashed"
+  items={[
+    { id: 1, title: 'Design Phase', time: 'Week 1' },
+    { id: 2, title: 'Development', time: 'Week 2-4', active: true },
+    { id: 3, title: 'Testing', time: 'Week 5' }
+  ]}
+/>
+
+// Custom Colors and Per-Item Styling
+<Timeline
+  lineColor="#ff6b6b"
+  lineWidth="3px"
+  items={[
+    {
+      id: 1,
+      title: 'Custom Dot Color',
+      dotColor: '#ffd93d',
+      dotClassName: 'shadow-xl',
+      time: 'Now'
+    },
+    {
+      id: 2,
+      title: 'Hidden Dot',
+      hideDot: true,
+      description: 'This item has no dot',
+      time: 'Later'
+    },
+    {
+      id: 3,
+      title: 'No Line After',
+      hideLine: true,
+      time: 'End'
+    }
+  ]}
+/>
+
+// Interactive Timeline with Click Handler
+<Timeline
+  onItemClick={(item, index) => {
+    console.log(`Clicked item ${index}:`, item.title);
+  }}
+  items={[
+    { id: 1, title: 'Clickable Item 1', time: '10:00' },
+    { id: 2, title: 'Clickable Item 2', time: '11:00' }
+  ]}
+/>
+
+// Time on Opposite Side (Alternate Mode)
+<Timeline
+  position="alternate"
+  showTimeOnOppositeSide={true}
+  items={[
+    { id: 1, title: 'Event 1', description: 'Time shows on opposite side', time: 'Jan 1' },
+    { id: 2, title: 'Event 2', description: 'Clean, organized layout', time: 'Jan 15' }
+  ]}
+/>
+
+// Different Dot Shapes
+<Timeline
+  dotShape="ring"
+  size="lg"
+  items={[
+    { id: 1, title: 'Ring Shape', status: 'primary' },
+    { id: 2, title: 'Hollow Center', status: 'success' }
+  ]}
+/>
+
+<Timeline
+  dotShape="square"
+  items={[
+    { id: 1, title: 'Square Dots', status: 'info' },
+    { id: 2, title: 'Modern Look', status: 'warning' }
+  ]}
+/>
+
+// E-commerce Order Tracking
+<Timeline
+  variant="outlined"
+  position="alternate"
+  items={[
+    {
+      id: 1,
+      title: 'Order Confirmed',
+      description: 'Your order has been received',
+      time: '2 hours ago',
+      status: 'success',
+      icon: Check
+    },
+    {
+      id: 2,
+      title: 'Processing',
+      description: 'We are preparing your items',
+      time: '1 hour ago',
+      status: 'primary',
+      active: true,
+      icon: Package
+    },
+    {
+      id: 3,
+      title: 'Shipped',
+      description: 'Your order is on the way',
+      time: 'Pending',
+      status: 'default',
+      icon: Rocket
+    }
+  ]}
+/>
+
+// Project Development Timeline
+<Timeline
+  variant="gradient"
+  size="lg"
+  items={[
+    { id: 1, title: 'Sprint Planning', description: 'Q1 2024', icon: Rocket, status: 'success' },
+    { id: 2, title: 'Development', description: 'Q2 2024', icon: Code, status: 'primary', active: true },
+    { id: 3, title: 'Testing', description: 'Q3 2024', icon: Package, status: 'warning' },
+    { id: 4, title: 'Release', description: 'Q4 2024', icon: Check, status: 'default' }
+  ]}
+/>
+```
+
+**CVA Integration:**
+
+```tsx
+import {
+  timelineVariants,
+  timelineItemVariants,
+  timelineLineVariants,
+  timelineDotVariants,
+  timelineContentVariants,
+} from "saha-ui";
+
+// Use exported variants for custom styling
+const customTimelineClass = timelineVariants({
+  variant: "gradient",
+  className: "my-custom-class",
+});
+
+const customItemClass = timelineItemVariants({
+  position: "alternate",
+  size: "lg",
+  className: "hover:scale-105",
+});
+
+const customDotClass = timelineDotVariants({
+  status: "success",
+  size: "lg",
+  active: true,
+});
+```
+
+---
+
+### Tree
+
+Hierarchical data visualization with expand/collapse functionality.
+
+**Variants:** `default` `glass` `bordered` `minimal`  
+**Sizes:** `sm` `md` `lg`
+
+```tsx
+import { Tree } from "saha-ui";
+import { Folder, File } from "lucide-react";
+
+<Tree
+  variant="glass"
+  size="md"
+  showIcons={true}
+  showLines={true}
+  iconPosition="left"
+  onNodeClick={(id) => console.log("Clicked:", id)}
+  onNodeToggle={(id, expanded) => console.log("Toggled:", id, expanded)}
+  nodes={[
+    {
+      id: "src",
+      label: "src",
+      icon: <Folder size={16} />,
+      expanded: true,
+      children: [
+        {
+          id: "components",
+          label: "components",
+          icon: <Folder size={16} />,
+          children: [
+            { id: "button", label: "Button.tsx", icon: <File size={16} /> },
+            { id: "card", label: "Card.tsx", icon: <File size={16} /> },
+          ],
+        },
+        { id: "app", label: "App.tsx", icon: <File size={16} /> },
+      ],
+    },
+  ]}
+/>;
+```
+
+**Props:**
+
+**Tree Component:**
+
+- `nodes`: TreeNode[] - Array of tree nodes (required)
+- `variant`: 'default' | 'glass' | 'bordered' | 'minimal' (default: 'default')
+- `size`: 'sm' | 'md' | 'lg' (default: 'md')
+- `className`: string - Additional CSS classes
+- `nodeClassName`: string - Custom class for all nodes
+- `iconPosition`: 'left' | 'right' (default: 'left')
+- `showLines`: boolean - Show connecting lines (default: true)
+- `showIcons`: boolean - Show node icons (default: true)
+- `onNodeToggle`: (id, expanded) => void - Callback when node is expanded/collapsed
+- `onNodeClick`: (id) => void - Callback when node is clicked
+
+**TreeNode:**
+
+- `id`: string | number - Unique identifier (required)
+- `label`: string - Display text (required)
+- `icon`: ReactNode - Custom icon
+- `children`: TreeNode[] - Child nodes
+- `expanded`: boolean - Initial expanded state (default: false)
+- `disabled`: boolean - Disable interactions
+- `className`: string - Custom class for this node
+
+**Advanced Usage:**
+
+```tsx
+// File System Explorer
+<Tree
+  variant="bordered"
+  showIcons={true}
+  onNodeClick={(id) => console.log('Opened:', id)}
+  nodes={[
+    {
+      id: 1,
+      label: 'Documents',
+      icon: <FolderOpen size={16} />,
+      expanded: true,
+      children: [
+        {
+          id: 2,
+          label: 'Work',
+          icon: <Folder size={16} />,
+          children: [
+            { id: 3, label: 'Resume.pdf', icon: <FileText size={16} /> },
+            { id: 4, label: 'Cover.docx', icon: <FileText size={16} /> }
+          ]
+        },
+        { id: 5, label: 'Personal', icon: <Folder size={16} /> }
+      ]
+    },
+    {
+      id: 6,
+      label: 'Media',
+      icon: <Folder size={16} />,
+      children: [
+        { id: 7, label: 'photo.jpg', icon: <ImageIcon size={16} /> },
+        { id: 8, label: 'video.mp4', icon: <Video size={16} /> }
+      ]
+    }
+  ]}
+/>
+
+// Organization Chart
+<Tree
+  variant="glass"
+  size="lg"
+  nodes={[
+    {
+      id: 'ceo',
+      label: 'CEO',
+      icon: <User size={16} />,
+      expanded: true,
+      children: [
+        {
+          id: 'eng',
+          label: 'Engineering',
+          icon: <Settings size={16} />,
+          children: [
+            { id: 'fe', label: 'Frontend Team', icon: <Code size={16} /> },
+            { id: 'be', label: 'Backend Team', icon: <Package size={16} /> }
+          ]
+        },
+        {
+          id: 'mkt',
+          label: 'Marketing',
+          icon: <Rocket size={16} />,
+          children: [
+            { id: 'content', label: 'Content', icon: <FileText size={16} /> }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+// Without Icons or Lines
+<Tree
+  showIcons={false}
+  showLines={false}
+  variant="minimal"
+  nodes={[
+    {
+      id: 1,
+      label: 'Parent',
+      children: [
+        { id: 2, label: 'Child 1' },
+        { id: 3, label: 'Child 2' }
+      ]
+    }
+  ]}
+/>
+
+// Icon on Right Side
+<Tree
+  iconPosition="right"
+  nodes={[
+    {
+      id: 1,
+      label: 'Folder',
+      icon: <Folder size={16} />,
+      children: [
+        { id: 2, label: 'File', icon: <File size={16} /> }
+      ]
+    }
+  ]}
+/>
+
+// With Disabled Nodes
+<Tree
+  nodes={[
+    {
+      id: 1,
+      label: 'Active',
+      children: [
+        { id: 2, label: 'Enabled' },
+        { id: 3, label: 'Disabled', disabled: true }
+      ]
+    }
+  ]}
+/>
+```
+
+**CVA Integration:**
+
+```tsx
+import { treeVariants, treeNodeVariants } from "saha-ui";
+
+// Use exported variants for custom styling
+const customTreeClass = treeVariants({
+  variant: "glass",
+  size: "lg",
+  className: "my-custom-class",
+});
+
+const customNodeClass = treeNodeVariants({
+  size: "md",
+  expanded: true,
+  className: "hover:bg-accent/20",
+});
+```
+
+---
+
+### Image
+
+Advanced image component with loading states and effects.
+
+**Variants:** `default` `rounded` `circular` `bordered` `glass`  
+**Fit:** `cover` `contain` `fill` `none` `scale-down`  
+**Sizes:** `xs` `sm` `md` `lg` `xl` `2xl` `full`
+
+```tsx
+import { Image } from "saha-ui";
+
+<Image
+  src="/photo.jpg"
+  alt="Beautiful photo"
+  variant="rounded"
+  size="lg"
+  fit="cover"
+  zoomOnHover
+  aspectRatio="16/9"
+  lazy
+  showSkeleton
+  fallbackSrc="/fallback.jpg"
+/>;
+```
+
+**Features:**
+
+- ⚡ Lazy loading by default
+- 💀 Animated loading skeleton
+- 🔄 Smart error handling with fallback
+- 🔍 Zoom on hover effect
+- 📐 Aspect ratio control
 
 ---
 
@@ -1117,6 +2670,1420 @@ import { Carousel } from "saha-ui";
 
 ---
 
+### Steps
+
+Progress indicator for multi-step processes and wizards.
+
+**Variants:** `default` `bordered` `glass` `minimal`  
+**Orientation:** `horizontal` `vertical`  
+**Sizes:** `sm` `md` `lg`  
+**Status:** `completed` `current` `pending` `error`
+
+```tsx
+import { Steps } from "saha-ui";
+
+<Steps
+  steps={[
+    {
+      id: 1,
+      title: "Account",
+      description: "Create your account",
+      status: "completed",
+    },
+    {
+      id: 2,
+      title: "Profile",
+      description: "Fill in your details",
+      status: "current",
+    },
+    {
+      id: 3,
+      title: "Verification",
+      description: "Verify your email",
+      status: "pending",
+    },
+  ]}
+  current={1}
+  variant="glass"
+  size="md"
+  orientation="horizontal"
+  showNumbers
+  showConnector
+  clickable
+  onStepClick={(index) => console.log("Step clicked:", index)}
+/>;
+
+// Vertical with custom icons
+import { User, CreditCard, Check } from "lucide-react";
+
+<Steps
+  steps={[
+    {
+      id: 1,
+      title: "Personal Info",
+      description: "Your details",
+      icon: <User className="w-5 h-5" />,
+    },
+    {
+      id: 2,
+      title: "Payment",
+      description: "Billing info",
+      icon: <CreditCard className="w-5 h-5" />,
+    },
+    {
+      id: 3,
+      title: "Complete",
+      description: "All done",
+      icon: <Check className="w-5 h-5" />,
+    },
+  ]}
+  orientation="vertical"
+  variant="bordered"
+/>;
+```
+
+**Features:**
+
+- ✅ Horizontal and vertical layouts
+- 🎨 4 visual variants with glassmorphism
+- 📏 3 size options
+- 🔢 Auto-numbered or custom icons
+- 📍 Status indicators (completed, current, pending, error)
+- 🖱️ Clickable navigation
+- 📝 Optional descriptions
+- 🔗 Connector lines between steps
+- 🎭 Smooth transitions
+
+---
+
+### Table
+
+Data table component with sorting, selection, and responsive design.
+
+**Variants:** `default` `bordered` `striped` `glass` `minimal`  
+**Sizes:** `sm` `md` `lg`  
+**Density:** `compact` `normal` `comfortable`
+
+```tsx
+import { Table } from "saha-ui";
+import { Badge, Avatar } from "saha-ui";
+
+// Define columns
+const columns = [
+  {
+    id: "user",
+    header: "User",
+    cell: (row: any) => (
+      <div className="flex items-center gap-3">
+        <Avatar src={row.avatar} alt={row.name} size="sm" />
+        <div>
+          <div className="font-medium">{row.name}</div>
+          <div className="text-sm text-muted-foreground">{row.email}</div>
+        </div>
+      </div>
+    ),
+    sortable: true,
+    sortFn: (a, b) => a.name.localeCompare(b.name),
+  },
+  {
+    id: "role",
+    header: "Role",
+    accessor: "role",
+    sortable: true,
+  },
+  {
+    id: "status",
+    header: "Status",
+    cell: (row: any) => (
+      <Badge variant={row.status === "active" ? "success" : "warning"}>
+        {row.status}
+      </Badge>
+    ),
+    align: "center",
+  },
+];
+
+// Sample data
+const data = [
+  {
+    id: 1,
+    name: "Alice Johnson",
+    email: "alice@example.com",
+    role: "Admin",
+    status: "active",
+    avatar: "https://i.pravatar.cc/150?img=1",
+  },
+  {
+    id: 2,
+    name: "Bob Smith",
+    email: "bob@example.com",
+    role: "Developer",
+    status: "active",
+    avatar: "https://i.pravatar.cc/150?img=2",
+  },
+];
+
+// Basic sortable table
+<Table columns={columns} data={data} sortable hoverable />;
+
+// Glass variant with selection
+<Table
+  columns={columns}
+  data={data}
+  variant="glass"
+  selectable
+  selectedRows={[1]}
+  onRowSelect={(selected) => console.log("Selected:", selected)}
+/>;
+
+// Compact size with striped rows
+<Table
+  columns={columns}
+  data={data}
+  variant="striped"
+  size="sm"
+  density="compact"
+/>;
+
+// With sticky header and scroll
+<Table
+  columns={columns}
+  data={data}
+  stickyHeader
+  maxHeight="400px"
+  variant="bordered"
+/>;
+
+// With clickable rows
+<Table
+  columns={columns}
+  data={data}
+  onRowClick={(row) => console.log("Clicked:", row)}
+  hoverable
+/>;
+
+// Loading state
+<Table columns={columns} data={[]} loading />;
+
+// Empty state
+<Table
+  columns={columns}
+  data={[]}
+  emptyMessage={
+    <div className="text-center py-8">
+      <p>No data available</p>
+    </div>
+  }
+/>;
+```
+
+**Features:**
+
+- ✅ Sorting (controlled and uncontrolled)
+- ☑️ Row selection with callbacks
+- 🎨 5 visual variants with glassmorphism
+- 📏 3 size options and 3 density levels
+- 🎯 Custom cell renderers
+- 📍 Column alignment (left, center, right)
+- 📌 Sticky header support
+- 📱 Responsive with horizontal scroll
+- 🔄 Loading states (inline and overlay)
+- 📝 Empty state customization
+- 🖱️ Clickable rows
+- 🎭 Hoverable and striped row options
+- 📊 Footer support
+- 🎨 Custom row styling
+
+**Column Options:**
+
+- `id` - Unique column identifier
+- `header` - Column header text/component
+- `accessor` - Property key or accessor function
+- `cell` - Custom cell renderer function
+- `width`, `minWidth`, `maxWidth` - Column sizing
+- `align` - Text alignment (left, center, right)
+- `sortable` - Enable sorting for column
+- `sortFn` - Custom sort function
+- `footer` - Footer content/function
+- `sticky` - Make column sticky
+- `className` - Custom classes for header/cell
+
+---
+
+### Rating
+
+Interactive star rating component with multiple icons and variants.
+
+**Variants:** `default` `primary` `secondary` `gradient` `glass` `outline`  
+**Sizes:** `sm` `md` `lg` `xl`  
+**Icons:** `star` `heart` `circle` `diamond`  
+**Precision:** `full` `half`
+
+```tsx
+import { Rating } from "saha-ui";
+
+// Basic rating
+<Rating value={4} max={5} />;
+
+// With half stars and value display
+<Rating value={4.5} precision="half" showValue />;
+
+// Interactive rating
+<Rating
+  value={0}
+  onChange={(value) => console.log("Rating:", value)}
+  precision="half"
+  size="lg"
+/>;
+
+// Read-only with review count
+<Rating value={4.7} precision="half" readOnly showValue count={2541} />;
+
+// Different variants
+<Rating value={4} variant="gradient" size="lg" />;
+<Rating value={4} variant="glass" size="lg" />;
+
+// Different icons
+<Rating value={4} icon="heart" variant="primary" size="lg" />;
+<Rating value={4} icon="circle" variant="secondary" size="lg" />;
+
+// Custom colors
+<Rating value={4} color="#ef4444" size="lg" />;
+
+// Custom maximum
+<Rating value={7} max={10} showValue />;
+
+// With tooltips
+<Rating
+  value={0}
+  showTooltip
+  tooltipLabels={["Poor", "Fair", "Good", "Very Good", "Excellent"]}
+  onChange={(value) => console.log(value)}
+/>;
+```
+
+**Features:**
+
+- ✅ Interactive and read-only modes
+- ⭐ Full and half-star precision
+- 🎨 6 visual variants with glassmorphism
+- 📏 4 size options (sm, md, lg, xl)
+- 🎯 Multiple icon types (star, heart, circle, diamond)
+- 🎨 Custom colors and icons
+- 📊 Review count display
+- 🖱️ Hover preview
+- ⌨️ Keyboard navigation
+- 🎭 Animated transitions
+- 🔧 Custom formatting
+- 💬 Tooltip support
+- ♿ Fully accessible
+
+**Props:**
+
+- `value` - Current rating value (0 to max)
+- `max` - Maximum rating value (default: 5)
+- `variant` - Visual style variant
+- `size` - Icon size
+- `icon` - Icon type to display
+- `precision` - Full or half stars
+- `readOnly` - Disable interaction
+- `disabled` - Disabled state
+- `showValue` - Display numeric value
+- `count` - Review count
+- `countLabel` - Label for count (default: "reviews")
+- `color` - Custom color for filled icons
+- `hoverable` - Enable hover effect
+- `showTooltip` - Show tooltips on hover
+- `tooltipLabels` - Custom labels for each value
+- `onChange` - Callback when rating changes
+- `onHover` - Callback when hovering
+- `allowClear` - Allow clearing rating
+- `animated` - Enable animations
+
+---
+
+### Progress
+
+A flexible progress bar component with multiple variants, sizes, and animations for displaying progress and loading states.
+
+**Basic Usage:**
+
+```tsx
+import { Progress } from "saha-ui";
+
+// Basic progress
+<Progress value={75} />
+
+// With variant and size
+<Progress value={60} variant="primary" size="lg" />
+
+// With label
+<Progress value={45} showValue labelPosition="outside" />
+
+// Striped with animation
+<Progress value={80} variant="success" striped stripedAnimated />
+
+// Indeterminate loading
+<Progress indeterminate variant="gradient" />
+
+// With glow effect
+<Progress value={90} variant="gradient" glow />
+
+// Custom colors
+<Progress value={60} color="#9333ea" trackColor="#f3e8ff" />
+```
+
+**Variants:**
+
+- `default` - Standard gray progress bar
+- `primary` - Primary color with gradient
+- `secondary` - Secondary color with gradient
+- `success` - Green success indicator
+- `warning` - Yellow/orange warning
+- `error` - Red error indicator
+- `gradient` - Multi-color gradient (blue→purple→pink)
+- `striped` - Striped pattern effect
+- `glass` - Glassmorphism with backdrop blur
+
+**Features:**
+
+- 🎨 **9 Modern Variants** - Each with unique visual design
+- 📏 **5 Size Options** - xs, sm, md, lg, xl
+- 🎭 **3 Shape Styles** - rounded, pill, square
+- 🏷️ **Label Support** - Inside, outside, or top positioned
+- 🎬 **Animations** - Pulse, shimmer, striped, indeterminate
+- 🌈 **Custom Colors** - Both bar and track colors
+- ✨ **Glow Effect** - Enhanced shadow for emphasis
+- 📊 **Value Display** - Show percentage or custom labels
+- ⏳ **Loading States** - Indeterminate/infinite loading
+- 🎯 **Type-Safe** - Full TypeScript support
+- ♿ **Accessible** - ARIA progressbar role
+- 🎭 **CVA Powered** - Type-safe variant composition
+
+**Props:**
+
+```tsx
+interface ProgressProps {
+  variant?:
+    | "default"
+    | "primary"
+    | "secondary"
+    | "success"
+    | "warning"
+    | "error"
+    | "gradient"
+    | "striped"
+    | "glass";
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
+  shape?: "rounded" | "pill" | "square";
+  animation?: "none" | "pulse" | "shimmer" | "indeterminate";
+  value?: number; // 0-100
+  max?: number; // default: 100
+  showValue?: boolean;
+  label?: string;
+  labelPosition?: "inside" | "outside" | "top";
+  color?: string;
+  trackColor?: string;
+  striped?: boolean;
+  stripedAnimated?: boolean;
+  glow?: boolean;
+  indeterminate?: boolean;
+  valueFormat?: (value: number, max: number) => string;
+  barClassName?: string;
+  labelClassName?: string;
+  className?: string;
+}
+```
+
+**Real-World Examples:**
+
+```tsx
+// File upload progress
+<Progress
+  value={uploadProgress}
+  variant="primary"
+  size="lg"
+  striped
+  stripedAnimated
+  showValue
+  labelPosition="top"
+  label={`Uploading ${fileName}`}
+/>
+
+// Skill level indicator
+<div>
+  <div className="flex justify-between mb-1">
+    <span>React</span>
+    <span>90%</span>
+  </div>
+  <Progress value={90} variant="primary" />
+</div>
+
+// System resource usage
+<Progress
+  value={cpuUsage}
+  variant={cpuUsage > 80 ? "error" : "success"}
+  size="sm"
+  glow={cpuUsage > 80}
+/>
+
+// Loading state
+<Progress indeterminate variant="gradient" />
+```
+
+**Detailed Props:**
+
+- `variant` - Visual style of the progress bar
+- `size` - Height of the progress bar
+- `shape` - Border radius style
+- `animation` - Animation type (pulse, shimmer, indeterminate)
+- `value` - Current progress value (0-100)
+- `max` - Maximum value (default 100)
+- `showValue` - Display percentage/label
+- `label` - Custom label text
+- `labelPosition` - Where to display label
+- `color` - Custom bar color
+- `trackColor` - Custom background color
+- `striped` - Show striped pattern
+- `stripedAnimated` - Animate the stripes
+- `glow` - Add glow shadow effect
+- `indeterminate` - Loading/infinite state
+- `valueFormat` - Custom formatter function
+
+---
+
+### Popover
+
+A versatile popover component for displaying rich interactive content with multiple positioning options, variants, and trigger types.
+
+**Basic Usage:**
+
+```tsx
+import { Popover, Button } from "saha-ui";
+
+// Basic popover
+<Popover content="This is a simple popover">
+  <Button>Click me</Button>
+</Popover>
+
+// With title and footer
+<Popover
+  title="Confirm Action"
+  content="Are you sure?"
+  footer={
+    <div className="flex gap-2">
+      <Button size="sm">Cancel</Button>
+      <Button size="sm" variant="primary">Confirm</Button>
+    </div>
+  }
+>
+  <Button>Delete</Button>
+</Popover>
+
+// Glass variant
+<Popover variant="glass" position="right" content="Beautiful glassmorphic popover">
+  <Button>Click me</Button>
+</Popover>
+```
+
+**Variants:** `default` `primary` `secondary` `success` `warning` `danger` `info` `glass` `bordered` `elevated` `flat`  
+**Positions:** 12 options including `top`, `bottom`, `left`, `right` (with -start and -end variations)  
+**Sizes:** `sm` `md` `lg` `xl`
+
+**Features:**
+
+- 🎨 11 visual variants (7 colors + 4 styles)
+- 📐 12 position options
+- 🎯 4 trigger types (click, hover, focus, manual)
+- 🎭 Arrow indicator
+- 📋 Title & footer support
+- ✖️ Optional close button
+- 🔘 Auto-dismiss (click outside, Escape key)
+- 💬 Rich content support
+- 🎛️ Controlled mode
+- ♿ Fully accessible
+
+---
+
+### PlayButton
+
+An animated play/pause button with smooth transitions, multiple variants, and modern effects. Perfect for media players, video controls, and interactive applications.
+
+**Basic Usage:**
+
+```tsx
+import { PlayButton } from "saha-ui";
+
+// Basic play button
+<PlayButton />
+
+// With variant and size
+<PlayButton variant="primary" size="lg" />
+
+// Controlled state
+const [playing, setPlaying] = useState(false);
+<PlayButton
+  isPlaying={playing}
+  onToggle={setPlaying}
+/>
+
+// With effects
+<PlayButton variant="success" pulse glow />
+
+// In a media player
+<div className="flex items-center gap-4">
+  <PlayButton
+    variant="primary"
+    size="md"
+    isPlaying={playing}
+    onToggle={setPlaying}
+  />
+  <span>{playing ? "Playing..." : "Paused"}</span>
+</div>
+```
+
+**Variants:** `default` `primary` `secondary` `accent` `info` `success` `warning` `error` `glass`  
+**Sizes:** `sm` `md` `lg` `xl`
+
+**Features:**
+
+- 🎨 9 visual variants with theme support
+- 📐 4 size options (12px to 24px icons)
+- ▶️ Smooth play/pause icon transitions
+- 💫 Animated pulsing ring when playing
+- ✨ Glow effects on hover
+- 🎛️ Controlled or uncontrolled state
+- 🎯 Click ripple effect
+- 🔘 Rounded, modern design
+- ♿ Fully accessible with ARIA labels
+- 🎭 Hover scale animations
+
+---
+
+### Skeleton
+
+Loading placeholder component with smooth animations and multiple visual styles.
+
+**Basic Usage:**
+
+```tsx
+import { Skeleton } from "saha-ui";
+
+// Basic skeleton
+<Skeleton width="100%" height="20px" />
+
+// Multiple lines
+<Skeleton count={3} />
+
+// Circle skeleton (avatar placeholder)
+<Skeleton
+  shape="circle"
+  width="48px"
+  height="48px"
+  variant="pulse"
+/>
+```
+
+**Variants:**
+
+```tsx
+// Default pulse animation
+<Skeleton variant="default" height="60px" />
+
+// Wave effect
+<Skeleton variant="wave" height="60px" />
+
+// Shimmer effect
+<Skeleton variant="shimmer" height="60px" />
+
+// Gradient animation
+<Skeleton variant="gradient" height="60px" />
+```
+
+**Shapes:**
+
+```tsx
+// Rectangle (default)
+<Skeleton shape="rectangle" width="100%" height="80px" />
+
+// Circle (for avatars)
+<Skeleton shape="circle" width="64px" height="64px" />
+
+// Rounded corners
+<Skeleton shape="rounded" width="100%" height="80px" />
+
+// Text lines
+<Skeleton shape="text" count={4} />
+```
+
+**Animation Speed:**
+
+```tsx
+<Skeleton speed="slow" variant="shimmer" />
+<Skeleton speed="normal" variant="shimmer" />
+<Skeleton speed="fast" variant="shimmer" />
+
+// Disable animation
+<Skeleton noAnimation />
+```
+
+**Real-world Examples:**
+
+```tsx
+// Profile card loading
+<Card>
+  <div className="flex gap-4">
+    <Skeleton shape="circle" width="64px" height="64px" />
+    <div className="flex-1">
+      <Skeleton height="24px" width="60%" className="mb-2" />
+      <Skeleton count={2} height="16px" />
+    </div>
+  </div>
+</Card>
+
+// Blog post loading
+<Card>
+  <Skeleton height="200px" className="mb-4" />
+  <Skeleton height="32px" width="80%" className="mb-3" />
+  <Skeleton count={4} height="16px" />
+</Card>
+
+// List items loading
+{[1, 2, 3].map(i => (
+  <Card key={i} className="flex gap-4">
+    <Skeleton shape="circle" width="48px" height="48px" />
+    <div className="flex-1">
+      <Skeleton height="18px" width="70%" className="mb-2" />
+      <Skeleton height="14px" width="90%" />
+    </div>
+  </Card>
+))}
+```
+
+**Variants:** `default` `pulse` `wave` `shimmer` `gradient`  
+**Shapes:** `rectangle` `circle` `rounded` `text`  
+**Speeds:** `slow` `normal` `fast`
+
+**Features:**
+
+- 🎨 5 animation variants
+- 🔷 4 shape options
+- ⚡ 3 speed settings
+- 📊 Multiple line support with `count` prop
+- 🎯 Fully customizable width/height
+- 🎭 Smooth animations with CVA
+- 🌓 Theme-aware styling
+- 🔧 Custom border radius support
+- 📱 Responsive and flexible
+- 💫 No animation mode available
+
+---
+
+### Pagination
+
+Comprehensive pagination component for navigating through large datasets.
+
+**Basic Usage:**
+
+```tsx
+import { Pagination } from "saha-ui";
+
+// Basic pagination
+<Pagination
+  totalPages={10}
+  currentPage={currentPage}
+  onPageChange={(page) => setCurrentPage(page)}
+/>
+
+// Custom variant and size
+<Pagination
+  variant="primary"
+  size="lg"
+  totalPages={20}
+  currentPage={5}
+  onPageChange={handlePageChange}
+/>
+```
+
+**Variants:**
+
+```tsx
+// Default
+<Pagination variant="default" totalPages={10} currentPage={1} />
+
+// Primary
+<Pagination variant="primary" totalPages={10} currentPage={3} />
+
+// Secondary
+<Pagination variant="secondary" totalPages={10} currentPage={5} />
+
+// Outlined
+<Pagination variant="outlined" totalPages={10} currentPage={7} />
+
+// Minimal
+<Pagination variant="minimal" totalPages={10} currentPage={2} />
+```
+
+**Sizes:**
+
+```tsx
+<Pagination size="sm" totalPages={10} currentPage={3} />
+<Pagination size="md" totalPages={10} currentPage={5} />
+<Pagination size="lg" totalPages={10} currentPage={7} />
+```
+
+**Shapes:**
+
+```tsx
+<Pagination shape="rounded" totalPages={10} currentPage={3} />
+<Pagination shape="square" totalPages={10} currentPage={5} />
+<Pagination shape="pill" totalPages={10} currentPage={7} />
+```
+
+**Large Page Count (Ellipsis):**
+
+```tsx
+// Automatically shows ellipsis for many pages
+<Pagination
+  variant="primary"
+  totalPages={50}
+  currentPage={currentPage}
+  onPageChange={setCurrentPage}
+/>
+
+// Control sibling count
+<Pagination
+  totalPages={100}
+  currentPage={currentPage}
+  onPageChange={setCurrentPage}
+  siblingCount={2} // Show 2 pages on each side
+/>
+```
+
+**Custom Labels:**
+
+```tsx
+// Text labels
+<Pagination
+  totalPages={10}
+  currentPage={5}
+  previousLabel="← Prev"
+  nextLabel="Next →"
+  firstLabel="First"
+  lastLabel="Last"
+/>
+
+// Without first/last buttons
+<Pagination
+  variant="primary"
+  totalPages={10}
+  currentPage={5}
+  showFirstLast={false}
+/>
+
+// Only page numbers
+<Pagination
+  variant="outlined"
+  totalPages={10}
+  currentPage={5}
+  showFirstLast={false}
+  showPrevNext={false}
+/>
+```
+
+**Real-world Example:**
+
+```tsx
+// Data table pagination
+function DataTable() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const itemsPerPage = 10;
+  const totalItems = 100;
+  const totalPages = Math.ceil(totalItems / itemsPerPage);
+
+  return (
+    <div>
+      <p>
+        Showing {(currentPage - 1) * itemsPerPage + 1} -
+        {Math.min(currentPage * itemsPerPage, totalItems)} of {totalItems}
+      </p>
+
+      <Pagination
+        variant="primary"
+        size="sm"
+        totalPages={totalPages}
+        currentPage={currentPage}
+        onPageChange={setCurrentPage}
+      />
+    </div>
+  );
+}
+```
+
+**Variants:** `default` `primary` `secondary` `outlined` `minimal`  
+**Sizes:** `sm` `md` `lg`  
+**Shapes:** `rounded` `square` `pill`
+
+**Features:**
+
+- 🎨 5 visual variants with theme support
+- 📐 3 size options
+- 🔷 3 shape styles
+- 🔢 Automatic ellipsis for large page counts
+- 🎯 Customizable sibling count
+- 🏷️ Custom labels for all buttons
+- ⚡ Fast page navigation
+- ♿ Fully accessible with ARIA labels
+- 🎭 Smooth transitions
+- 🎛️ Show/hide first/last/prev/next buttons
+- 📱 Responsive design
+- 🌓 Theme-aware styling
+- ⌨️ Keyboard navigation support
+- 🚫 Disabled state support
+
+---
+
+### DatePicker
+
+Calendar-based date picker with multiple variants and date restrictions.
+
+**Basic Usage:**
+
+```tsx
+import { DatePicker } from "saha-ui";
+
+// Basic date picker
+<DatePicker
+  value={date}
+  onChange={(date) => setDate(date)}
+  placeholder="Select date"
+/>
+
+// Custom variant and size
+<DatePicker
+  variant="primary"
+  size="lg"
+  value={date}
+  onChange={setDate}
+/>
+```
+
+**Variants:**
+
+```tsx
+// Default
+<DatePicker variant="default" />
+
+// Primary
+<DatePicker variant="primary" />
+
+// Secondary
+<DatePicker variant="secondary" />
+
+// Outlined
+<DatePicker variant="outlined" />
+
+// Minimal
+<DatePicker variant="minimal" />
+```
+
+**Sizes:**
+
+```tsx
+<DatePicker size="sm" />
+<DatePicker size="md" />
+<DatePicker size="lg" />
+```
+
+**Date Restrictions:**
+
+```tsx
+// Min date (future dates only)
+<DatePicker
+  value={date}
+  onChange={setDate}
+  minDate={new Date()}
+  placeholder="Select future date"
+/>
+
+// Max date (past dates only)
+<DatePicker
+  value={date}
+  onChange={setDate}
+  maxDate={new Date()}
+  placeholder="Select past date"
+/>
+
+// Date range
+<DatePicker
+  value={date}
+  onChange={setDate}
+  minDate={startDate}
+  maxDate={endDate}
+  placeholder="Select date in range"
+/>
+```
+
+**Customization:**
+
+```tsx
+// Custom format
+<DatePicker
+  value={date}
+  onChange={setDate}
+  format="DD/MM/YYYY"
+  placeholder="DD/MM/YYYY"
+/>
+
+// Monday as first day of week
+<DatePicker
+  value={date}
+  onChange={setDate}
+  firstDayOfWeek={1}
+/>
+
+// Without clear/today buttons
+<DatePicker
+  value={date}
+  onChange={setDate}
+  showClear={false}
+  showToday={false}
+/>
+
+// Disabled state
+<DatePicker
+  value={date}
+  disabled
+/>
+```
+
+**Real-world Examples:**
+
+```tsx
+// Booking form
+<div className="grid grid-cols-2 gap-4">
+  <DatePicker
+    variant="primary"
+    minDate={new Date()}
+    placeholder="Check-in"
+  />
+  <DatePicker
+    variant="primary"
+    minDate={new Date()}
+    placeholder="Check-out"
+  />
+</div>
+
+// Date of birth picker
+<DatePicker
+  variant="outlined"
+  maxDate={new Date()}
+  format="MM/DD/YYYY"
+  placeholder="Date of birth"
+/>
+
+// Task due date
+<DatePicker
+  variant="primary"
+  size="sm"
+  minDate={new Date()}
+  placeholder="Due date"
+/>
+```
+
+**Variants:** `default` `primary` `secondary` `outlined` `minimal`  
+**Sizes:** `sm` `md` `lg`  
+**Formats:** Customizable (MM/DD/YYYY, DD/MM/YYYY, etc.)
+
+**Features:**
+
+- 🎨 5 visual variants with theme support
+- 📐 3 size options
+- 📅 Interactive calendar view
+- 🔒 Min/max date restrictions
+- 🎯 Custom date format display
+- 🌍 Configurable first day of week
+- ✨ Today quick select button
+- 🗑️ Clear button for easy reset
+- 📱 Click outside to close
+- ⌨️ Keyboard navigation in calendar
+- 🎭 Smooth animations
+- 🌓 Theme-aware styling
+- ♿ Fully accessible
+- 🚫 Disabled state support
+- 📆 Month/year navigation
+
+---
+
+### Tab
+
+Tab navigation component with comprehensive variant support and flexible content options.
+
+```tsx
+import { Tab } from "saha-ui";
+import type { TabItem } from "saha-ui";
+
+// Basic usage
+const tabs: TabItem[] = [
+  { label: "Profile", value: "profile" },
+  { label: "Settings", value: "settings" },
+  { label: "Notifications", value: "notifications" },
+];
+
+<Tab tabs={tabs} value={activeTab} onChange={setActiveTab} />;
+
+// With icons
+<Tab
+  tabs={[
+    { label: "Home", value: "home", icon: <HomeIcon /> },
+    { label: "Messages", value: "messages", icon: <MessageIcon /> },
+    { label: "Settings", value: "settings", icon: <SettingsIcon /> },
+  ]}
+  variant="primary"
+/>;
+
+// With badges
+<Tab
+  tabs={[
+    { label: "Inbox", value: "inbox", badge: "12" },
+    { label: "Unread", value: "unread", badge: "5" },
+    { label: "Archive", value: "archive" },
+  ]}
+  variant="secondary"
+/>;
+
+// Full width
+<Tab tabs={tabs} variant="outlined" fullWidth />;
+
+// Different sizes
+<Tab tabs={tabs} size="sm" />
+<Tab tabs={tabs} size="md" />
+<Tab tabs={tabs} size="lg" />
+
+// Disabled tabs
+<Tab
+  tabs={[
+    { label: "Active", value: "active" },
+    { label: "Disabled", value: "disabled", disabled: true },
+  ]}
+/>
+
+// All 14 variants
+<Tab tabs={tabs} variant="default" />
+<Tab tabs={tabs} variant="primary" />
+<Tab tabs={tabs} variant="secondary" />
+<Tab tabs={tabs} variant="accent" />
+<Tab tabs={tabs} variant="success" />
+<Tab tabs={tabs} variant="warning" />
+<Tab tabs={tabs} variant="danger" />
+<Tab tabs={tabs} variant="info" />
+<Tab tabs={tabs} variant="glass" />
+<Tab tabs={tabs} variant="bordered" />
+<Tab tabs={tabs} variant="elevated" />
+<Tab tabs={tabs} variant="flat" />
+<Tab tabs={tabs} variant="outlined" />
+<Tab tabs={tabs} variant="minimal" />
+
+// Style examples
+<div className="space-y-4">
+  {/* Boxed style */}
+  <Tab tabs={tabs} variant="primary" />
+
+  {/* Underlined style */}
+  <Tab tabs={tabs} variant="bordered" />
+
+  {/* Pill style */}
+  <Tab tabs={tabs} variant="glass" />
+</div>
+```
+
+**Variants:** `default` `primary` `secondary` `accent` `success` `warning` `danger` `info` `glass` `bordered` `elevated` `flat` `outlined` `minimal`  
+**Sizes:** `sm` `md` `lg`
+
+**Props:**
+
+| Prop                   | Type         | Default          | Description                        |
+| ---------------------- | ------------ | ---------------- | ---------------------------------- |
+| `items`                | `TabItem[]`  | Required         | Array of tab items                 |
+| `value`                | `string`     | `undefined`      | Controlled active tab value        |
+| `defaultValue`         | `string`     | `items[0].value` | Default active tab (uncontrolled)  |
+| `onChange`             | `function`   | `undefined`      | Callback when tab changes          |
+| `variant`              | `TabVariant` | `'default'`      | Visual variant                     |
+| `size`                 | `TabSize`    | `'md'`           | Size variant                       |
+| `fullWidth`            | `boolean`    | `false`          | Make tabs full width               |
+| `className`            | `string`     | `undefined`      | Custom className for container     |
+| `tabClassName`         | `string`     | `undefined`      | Custom className for all tab items |
+| `activeTabClassName`   | `string`     | `undefined`      | Custom className for active tab    |
+| `disabledTabClassName` | `string`     | `undefined`      | Custom className for disabled tabs |
+| `iconClassName`        | `string`     | `undefined`      | Custom className for icon wrapper  |
+| `badgeClassName`       | `string`     | `undefined`      | Custom className for badge         |
+| `activeBadgeClassName` | `string`     | `undefined`      | Custom className for active badge  |
+
+**TabItem Type:**
+
+```typescript
+interface TabItem {
+  label: string; // Tab label text
+  value: string; // Unique tab identifier
+  icon?: ReactNode; // Optional icon element
+  disabled?: boolean; // Disable the tab
+  badge?: string | number; // Optional badge content
+  className?: string; // Custom className for this tab
+  iconClassName?: string; // Custom className for this tab's icon
+  badgeClassName?: string; // Custom className for this tab's badge
+}
+```
+
+**Customization Examples:**
+
+```tsx
+// Custom container with rounded-full
+<Tab items={tabs} className="rounded-full p-2 shadow-xl" />
+
+// Underline style tabs
+<Tab
+  items={tabs}
+  variant="minimal"
+  className="gap-4 p-0 bg-transparent border-b-2 border-base-300"
+  tabClassName="rounded-none border-b-2 border-transparent pb-3"
+  activeTabClassName="!border-primary !text-primary !bg-transparent"
+/>
+
+// Per-item custom styling
+<Tab
+  items={[
+    {
+      label: "Red Tab",
+      value: "red",
+      className: "data-[active=true]:bg-red-500 data-[active=true]:text-white"
+    },
+    // ... more tabs
+  ]}
+/>
+
+// Custom gradient badges
+<Tab
+  items={[{ label: "Inbox", value: "inbox", badge: 12 }]}
+  badgeClassName="bg-gradient-to-r from-pink-500 to-purple-500"
+  activeBadgeClassName="!bg-gradient-to-r !from-yellow-400 !to-orange-500"
+/>
+
+// Vertical tabs (mobile)
+<Tab
+  items={tabs}
+  className="flex-col sm:flex-row"
+  tabClassName="w-full sm:w-auto justify-start"
+/>
+
+// Pill style
+<Tab
+  items={tabs}
+  className="gap-3 p-0 bg-transparent"
+  tabClassName="rounded-full px-6 py-3 shadow-md"
+  activeTabClassName="scale-105 shadow-lg"
+/>
+```
+
+**Features:**
+
+- 🎨 14 visual variants matching design system
+- 📐 3 size options (sm, md, lg)
+- 🎯 Controlled and uncontrolled modes
+- 🖼️ Icon support in tabs
+- 🔔 Badge indicators for notifications
+- 🚫 Disabled tab states
+- 📱 Full width responsive layout
+- ⌨️ Keyboard navigation (arrow keys)
+- 🎭 Smooth transitions
+- 🌓 Theme-aware styling
+- ♿ ARIA-compliant accessibility
+- 🎪 Active state indicators
+- ✨ Hover effects
+- 🔄 Flexible content with icons/badges
+- 🎨 **Fully customizable with Tailwind classes**
+- 💅 **Per-item styling support**
+- 🔧 **No SCSS required - pure Tailwind**
+
+---
+
+### Input
+
+Flexible and customizable input field component with comprehensive variant support and validation states.
+
+```tsx
+import { Input } from "saha-ui";
+import { Mail, Lock, Search, User } from "lucide-react";
+
+// Basic input
+<Input placeholder="Enter text..." />
+
+// With label and helper text
+<Input
+  label="Email"
+  type="email"
+  placeholder="you@example.com"
+  helperText="We'll never share your email"
+/>
+
+// Different variants
+<Input variant="primary" placeholder="Primary input" />
+<Input variant="secondary" placeholder="Secondary input" />
+<Input variant="accent" placeholder="Accent input" />
+<Input variant="success" placeholder="Success input" />
+<Input variant="warning" placeholder="Warning input" />
+<Input variant="error" placeholder="Error input" />
+<Input variant="outline" placeholder="Outline input (default)" />
+<Input variant="ghost" placeholder="Ghost input" />
+<Input variant="glass" placeholder="Glass morphism input" />
+
+// With icons
+<Input
+  label="Search"
+  startIcon={<Search size={18} />}
+  placeholder="Search..."
+/>
+
+<Input
+  label="Email"
+  type="email"
+  startIcon={<Mail size={18} />}
+  placeholder="you@example.com"
+/>
+
+// With validation
+<Input
+  label="Password"
+  type="password"
+  variant="error"
+  error="Password must be at least 8 characters"
+  startIcon={<Lock size={18} />}
+/>
+
+<Input
+  label="Username"
+  variant="success"
+  defaultValue="johndoe"
+  helperText="Username is available!"
+  startIcon={<User size={18} />}
+/>
+
+// Character counter
+<Input
+  label="Bio"
+  placeholder="Tell us about yourself..."
+  maxLength={100}
+  showCounter
+  helperText="Maximum 100 characters"
+/>
+
+// Different sizes
+<Input size="sm" placeholder="Small input" />
+<Input size="md" placeholder="Medium input (default)" />
+<Input size="lg" placeholder="Large input" />
+<Input size="xl" placeholder="Extra large input" />
+
+// Full width
+<Input
+  fullWidth
+  label="Full Name"
+  placeholder="Enter your full name"
+/>
+
+// All input types (except file)
+<Input type="text" placeholder="Text input" />
+<Input type="email" placeholder="Email input" />
+<Input type="password" placeholder="Password input" />
+<Input type="number" placeholder="Number input" />
+<Input type="tel" placeholder="Phone input" />
+<Input type="url" placeholder="URL input" />
+<Input type="search" placeholder="Search input" />
+<Input type="date" />
+<Input type="time" />
+<Input type="color" />
+
+// Required field
+<Input
+  label="Username"
+  placeholder="Enter username"
+  required
+/>
+
+// Disabled
+<Input
+  label="Disabled Input"
+  placeholder="Cannot edit"
+  disabled
+/>
+
+// Login form example
+<div className="space-y-4">
+  <Input
+    fullWidth
+    label="Email"
+    type="email"
+    variant="glass"
+    startIcon={<Mail size={18} />}
+    placeholder="you@example.com"
+    required
+  />
+  <Input
+    fullWidth
+    label="Password"
+    type="password"
+    variant="glass"
+    startIcon={<Lock size={18} />}
+    placeholder="Enter your password"
+    required
+  />
+</div>
+```
+
+**Variants:** `primary` `secondary` `accent` `info` `success` `warning` `error` `outline` `ghost` `glass`  
+**Sizes:** `sm` `md` `lg` `xl`  
+**Input Types:** All HTML input types except `file`
+
+**Props:**
+
+| Prop                  | Type          | Default     | Description                              |
+| --------------------- | ------------- | ----------- | ---------------------------------------- |
+| `variant`             | `InputVariant`| `'outline'` | Visual variant                           |
+| `size`                | `InputSize`   | `'md'`      | Size variant                             |
+| `type`                | `InputType`   | `'text'`    | HTML input type (excludes file)          |
+| `label`               | `string`      | `undefined` | Label text for the input                 |
+| `helperText`          | `string`      | `undefined` | Helper text below input                  |
+| `error`               | `string`      | `undefined` | Error message (overrides helperText)     |
+| `startIcon`           | `ReactNode`   | `undefined` | Icon on the left side                    |
+| `endIcon`             | `ReactNode`   | `undefined` | Icon on the right side                   |
+| `showCounter`         | `boolean`     | `false`     | Show character counter (needs maxLength) |
+| `required`            | `boolean`     | `false`     | Mark field as required                   |
+| `fullWidth`           | `boolean`     | `false`     | Full width styling                       |
+| `containerClassName`  | `string`      | `undefined` | Custom className for container           |
+| `labelClassName`      | `string`      | `undefined` | Custom className for label               |
+| `disabled`            | `boolean`     | `false`     | Disable the input                        |
+| `maxLength`           | `number`      | `undefined` | Maximum character length                 |
+| `...props`            | `InputHTMLAttributes` | - | All standard input attributes            |
+
+**Features:**
+
+- 🎨 10 visual variants matching design system
+- 📐 4 size options (sm, md, lg, xl)
+- 🔤 Supports all HTML input types except file
+- 🖼️ Icon support (start and end positions)
+- ✅ Built-in validation states
+- 📝 Character counter with maxLength
+- 💬 Helper text and error messaging
+- ⚠️ Required field indicators
+- 📱 Full width responsive option
+- ⌨️ Standard input attributes support
+- 🎭 Smooth transitions and focus states
+- 🌓 Theme-aware styling
+- ♿ Accessible with proper labels
+- 🔒 Type-safe with TypeScript
+- 🎪 Hover and focus effects
+- 🔧 **No SCSS required - pure Tailwind**
+
+---
+
 ## 🎨 Theming
 
 ### Theme Provider