@alkimi.org/ui-kit 0.12.5 → 0.12.7

package/dist/COMPONENTS.md

@@ -0,0 +1,1922 @@
+# @alkimi.org/ui-kit v0.12.7
+
+AI-readable component documentation for the Alkimi UI Kit.
+
+## Installation
+
+```bash
+pnpm add @alkimi.org/ui-kit
+```
+
+```tsx
+import { Button } from "@alkimi.org/ui-kit"
+import "@alkimi.org/ui-kit/styles.css"
+```
+
+---
+
+## Button
+
+```tsx
+import { Button, buttonVariants, type ButtonProps } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Button`, `buttonVariants`
+
+A versatile button component with multiple variants, sizes, and states.
+
+### Usage
+
+```tsx
+<Button>Click me</Button>
+<Button variant="outline" size="sm">Small outline</Button>
+<Button loading>Loading...</Button>
+```
+
+### Variants
+
+- **default**: Primary action button with accent color
+- **destructive**: For dangerous actions (delete, remove)
+- **outline**: Secondary actions with border
+- **secondary**: Alternative secondary style
+- **ghost**: Minimal style for subtle actions
+- **link**: Text-only button styled as a link
+
+### Sizes
+
+- **default**: Standard button size
+- **sm**: Smaller button for compact layouts
+- **lg**: Larger button for emphasis
+- **icon**: Square button for icons only
+- **none**: No padding or text size — useful for fully custom sizing
+
+### States
+
+- **loading**: Shows a loading spinner, automatically disables interaction
+- **disabled**: Disables the button and reduces opacity
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| asChild? | `boolean` | `false` | - |
+| loading? | `boolean` | `false` | - |
+| icon? | `React.ReactNode` | - | - |
+| variant? | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"default"` | - |
+| size? | `"default" \| "sm" \| "lg" \| "icon" \| "none"` | `"default"` | - |
+
+---
+
+## Tabs
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+
+A tabs component for organizing content into separate views that users can switch between.
+
+### Component Structure
+
+- **Tabs**: Root container that manages tab state
+- **TabsList**: Container for tab triggers (usually styled as a button group)
+- **TabsTrigger**: Individual tab button to switch between content
+- **TabsContent**: Content panel for each tab
+
+### Usage
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">Account content</TabsContent>
+  <TabsContent value="password">Password content</TabsContent>
+</Tabs>
+```
+
+### Key Props
+
+- **defaultValue**: Initial active tab (uncontrolled)
+- **value**: Controlled active tab state
+- **onValueChange**: Callback when active tab changes
+- **disabled**: Can be added to individual TabsTrigger components
+
+---
+
+## TextDecoder
+
+```tsx
+import { TextDecoder, type TextDecoderProps } from "@alkimi.org/ui-kit"
+```
+
+An animated text component that reveals content through a decoding/decryption effect. Characters scramble through random symbols before settling into the final text. Supports a continuous glitch mode for loading states.
+
+### Usage
+
+```tsx
+<TextDecoder delay={0}>Hello World</TextDecoder>
+<TextDecoder delay={1000} symbols="01">Binary decode</TextDecoder>
+<TextDecoder isLoading={isLoading}>Data loaded</TextDecoder>
+```
+
+### Props
+
+- **children**: The text content to decode (can be string or nested elements)
+- **delay**: Delay before starting animation in milliseconds (default: 0)
+- **duration**: Controls the animation speed in frames (default: 40)
+- **symbols**: Custom symbols for scrambling (default: `!<>-_\\\\/[]{}—=+*^?#________`)
+- **isLoading**: When true, runs a continuous glitch animation. When set to false, the text decodes and reveals the children content
+- **speed**: Controls how fast characters change during animation (0.01 = slow, 1 = instant, default: 0.28)
+- **hoverContent**: When provided, enables tooltip-like hover behavior. Text animates to hoverContent on mouse enter, animates back to children on mouse leave
+- **className**: Additional CSS classes for styling
+
+### Use Cases
+
+- Animated headers and titles
+- Loading states with continuous glitch effect
+- Sequential text reveals with `delay` prop
+- Tooltip-like hover reveals with `hoverContent` prop
+- Cyberpunk/tech aesthetic interfaces
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | - |
+| className? | `string` | `"absolute inset-0 flex items-center justify-center opacity-50 font-mono leading-none"` | - |
+| duration? | `number` | `40` | - |
+| symbols? | `string` | - | - |
+| delay? | `number` | `0` | - |
+| isLoading? | `boolean` | `false` | - |
+| speed? | `number` | `0.28` | - |
+| hoverContent? | `ReactNode` | - | - |
+
+---
+
+## GlitchLink
+
+```tsx
+import { GlitchLink } from "@alkimi.org/ui-kit"
+```
+
+An interactive link component with a cyberpunk-style glitch effect on hover. Characters randomly cycle through symbols before settling back to the original text.
+
+### Usage
+
+```tsx
+<GlitchLink href="/about">About Us</GlitchLink>
+```
+
+### Props
+
+- **href**: The URL the link points to
+- **children**: The text content of the link
+- **symbols**: Array of symbols for the glitch effect (default: numbers, letters, special characters)
+- **className**: Additional CSS classes for styling
+- **asChild**: When true, passes props to child element instead of rendering a Link
+
+### Use Cases
+
+- Navigation links with futuristic aesthetic
+- Call-to-action links that need attention
+- In-text links that need visual interest
+- Can wrap buttons using `asChild` prop
+
+---
+
+## PixelLoad
+
+```tsx
+import { PixelLoad, type PixelLoadProps } from "@alkimi.org/ui-kit"
+```
+
+An animated image component that reveals content through a pixelated depixelation effect. The image starts heavily pixelated and gradually becomes clear.
+
+### Usage
+
+```tsx
+<PixelLoad
+  src="/image.jpg"
+  alt="Description"
+  duration={600}
+  steps={15}
+/>
+```
+
+### Key Props
+
+- **src**: Image source URL or Next.js StaticImageData
+- **alt**: Alternative text for accessibility
+- **duration**: Animation duration in milliseconds (default: 600)
+- **steps**: Number of pixelation steps (default: 15)
+- **objectFit**: How image fits container (cover, contain, etc.)
+- **onAnimationComplete**: Callback when animation finishes
+
+### Animation Control
+
+- Lower `duration` = faster animation
+- More `steps` = smoother transition (but slower)
+- Fewer `steps` = chunkier effect (but faster)
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `ImageSrc` | - | - |
+| alt | `string` | - | - |
+| duration? | `number` | `600` | - |
+| steps? | `number` | `15` | - |
+| className? | `string` | `"sr-only"` | - |
+| onAnimationComplete? | `() =\> void` | - | - |
+| objectFit? | `"contain" \| "cover" \| "fill" \| "none" \| "scale-down"` | `"cover"` | - |
+
+---
+
+## GeometricFluidGrid
+
+```tsx
+import { GeometricFluidGrid } from "@alkimi.org/ui-kit"
+```
+
+An animated background component featuring a fluid grid with glowing orbs and optional glitch effects.
+
+### Usage
+
+```tsx
+<GeometricFluidGrid variant="animated" />
+<GeometricFluidGrid variant="static" />
+```
+
+### Variants
+
+- **animated** (default): Full animations with glowing orbs, glitch effects, and mouse trail interactions
+- **static**: Static dots only, no animations or interactions (better performance)
+
+The component uses fixed positioning with z-index: -999, making it perfect for background usage.
+
+---
+
+## Sidebar
+
+```tsx
+import { Sidebar, SidebarBanner, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, useSidebar } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Sidebar`, `SidebarBanner`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarGroupLabel`, `SidebarHeader`, `SidebarInput`, `SidebarInset`, `SidebarMenu`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuButton`, `SidebarMenuItem`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubButton`, `SidebarMenuSubItem`, `SidebarProvider`, `SidebarRail`, `SidebarSeparator`, `SidebarTrigger`, `useSidebar`
+
+---
+
+## Drawer
+
+```tsx
+import { Drawer, DrawerHeader, DrawerTitle, DrawerBody, DrawerFooter, useDrawer } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Drawer`, `DrawerHeader`, `DrawerTitle`, `DrawerBody`, `DrawerFooter`, `useDrawer`
+
+A fully responsive drawer component that automatically adapts to screen size.
+
+### Features
+
+- **Responsive by Default**: Automatically switches between mobile and desktop modes at the `md` breakpoint
+- **Mobile Behavior**: Slides from left with overlay backdrop and swipe-to-close gestures
+- **Desktop Behavior**: Slides from right and pushes layout content (no overlay)
+- **Single Component**: No need to manually handle `variant` or screen size detection
+- **Customizable Width**: Desktop width is configurable (default: 24rem)
+
+### Usage
+
+```tsx
+import {
+  Drawer,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerBody,
+  DrawerFooter
+} from '@alkimi/ui-kit'
+
+function MyComponent() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Open Drawer</button>
+
+      <Drawer isOpen={isOpen} onClose={() => setIsOpen(false)} width="28rem">
+        <DrawerHeader>
+          <DrawerTitle>Settings</DrawerTitle>
+        </DrawerHeader>
+
+        <DrawerBody>
+          <p>Drawer content goes here...</p>
+        </DrawerBody>
+
+        <DrawerFooter>
+          <button onClick={() => setIsOpen(false)}>Close</button>
+        </DrawerFooter>
+      </Drawer>
+    </>
+  )
+}
+```
+
+### Components
+
+- **Drawer**: Main container component
+- **DrawerHeader**: Header with optional close button (`showCloseButton` prop)
+- **DrawerTitle**: Styled title for the header
+- **DrawerBody**: Scrollable content area
+- **DrawerFooter**: Footer for actions/buttons
+
+### Responsive Behavior
+
+- **Mobile (< md)**: Slides from left, full overlay, swipe gestures
+- **Desktop (≥ md)**: Slides from right, pushes content, no overlay
+
+---
+
+## Input
+
+```tsx
+import { Input, type InputProps } from "@alkimi.org/ui-kit"
+```
+
+A versatile input component for text, email, password, and other input types.
+
+### Usage
+
+```tsx
+<Input type="text" placeholder="Enter your name" />
+```
+
+### Features
+
+- Supports all standard HTML input types
+- Accessible with proper focus states
+- Disabled state support
+- File input support
+- Customizable with className prop
+- Works with Field component for labels and descriptions
+
+### Input Types
+
+- **text**: Standard text input
+- **email**: Email input with validation
+- **password**: Password input (masked)
+- **number**: Numeric input
+- **search**: Search input
+- **tel**: Telephone number input
+- **url**: URL input
+- **file**: File upload input
+
+### Field Component
+
+Use the Field component pattern for consistent form layouts with labels and descriptions:
+
+```tsx
+<Field>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input type="email" id="email" placeholder="name@example.com" />
+  <FieldDescription>We'll never share your email.</FieldDescription>
+</Field>
+```
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| error? | `boolean` | - | - |
+
+---
+
+## Textarea
+
+```tsx
+import { Textarea, type TextareaProps } from "@alkimi.org/ui-kit"
+```
+
+A multi-line text input component for longer text content.
+
+### Usage
+
+```tsx
+<Textarea placeholder="Enter your message" />
+```
+
+### Features
+
+- Multi-line text input
+- Accessible with proper focus states
+- Disabled state support
+- Error state support
+- Customizable with className prop
+- Works with Field component for labels and descriptions
+
+### Field Component
+
+Use the Field component pattern for consistent form layouts with labels and descriptions:
+
+```tsx
+<Field>
+  <FieldLabel htmlFor="message">Message</FieldLabel>
+  <Textarea id="message" placeholder="Enter your message" />
+  <FieldDescription>Maximum 500 characters.</FieldDescription>
+</Field>
+```
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| error? | `boolean` | - | - |
+
+---
+
+## FileUpload
+
+```tsx
+import { FileUpload, type FileUploadProps } from "@alkimi.org/ui-kit"
+```
+
+A drag-and-drop file upload component with format validation and file size limits.
+
+### Usage
+
+```tsx
+<FileUpload
+  accept=".png,.jpg,.pdf"
+  maxSize={10 * 1024 * 1024}
+  onFilesChange={(files) => console.log(files)}
+/>
+```
+
+### Features
+
+- Drag and drop support
+- Click to browse files
+- File format filtering with `accept` prop (automatically displayed)
+- Maximum file size validation with `maxSize` prop (automatically displayed)
+- Multiple file upload support
+- File list with remove option
+- Error state support
+- Disabled state support
+- Accessible keyboard navigation
+
+### Props
+
+- **accept**: Accepted file formats (e.g., ".png,.jpg,.pdf" or "image/*") - automatically displayed below the upload text
+- **maxSize**: Maximum file size in bytes - automatically displayed as "up to X MB/KB"
+- **multiple**: Allow multiple files (default: false)
+- **onFilesChange**: Callback when files are selected
+- **error**: Show error state
+- **disabled**: Disable the component
+- **description**: Additional description text
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| accept? | `string` | - | Accepted file formats (e.g., ".png,.jpg,.pdf" or "image/*") |
+| maxSize? | `number` | - | Maximum file size in bytes |
+| multiple? | `boolean` | `false` | Allow multiple files |
+| onFilesChange? | `(files: File[]) =\> void` | - | Callback when files are selected |
+| error? | `boolean` | - | Error state |
+| disabled? | `boolean` | - | Disabled state |
+| className? | `string` | `"h-4 w-4 text-secondary-text"` | Custom class name |
+| placeholder? | `string` | - | Placeholder text |
+| description? | `string` | - | Description text (e.g., "PNG, JPG up to 10MB") |
+
+---
+
+## Label
+
+```tsx
+import { Label } from "@alkimi.org/ui-kit"
+```
+
+---
+
+## Calendar
+
+```tsx
+import { Calendar } from "@alkimi.org/ui-kit"
+```
+
+---
+
+## DatePicker
+
+```tsx
+import { DatePicker, type DatePickerProps } from "@alkimi.org/ui-kit"
+```
+
+A date picker component built with react-day-picker and date-fns, following the Shadcn pattern.
+
+### Usage
+
+```tsx
+import { DatePicker } from "@alkimi.org/ui-kit"
+import { useState } from "react"
+
+function MyComponent() {
+  const [date, setDate] = useState<Date>()
+
+  return (
+    <DatePicker
+      date={date}
+      onDateChange={setDate}
+      placeholder="Pick a date"
+    />
+  )
+}
+```
+
+### Features
+
+- Beautiful calendar UI with month/year navigation
+- Date selection with visual feedback
+- Modal popover that closes when a date is selected
+- Keyboard navigation support
+- Accessible (ARIA compliant)
+- Customizable date format
+- Disabled state support
+- Min/max date restrictions
+- Integrates with Field component for labels and descriptions
+
+### Date Formatting
+
+Uses date-fns for formatting. Default format is "PPP" (e.g., "April 29, 2023").
+Common formats:
+- "PPP": Long format (April 29, 2023)
+- "PP": Medium format (Apr 29, 2023)
+- "P": Short format (04/29/2023)
+- "yyyy-MM-dd": ISO format (2023-04-29)
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| date? | `Date` | - | - |
+| onDateChange? | `(date: Date \| undefined) =\> void` | - | - |
+| placeholder? | `string` | `"Pick a date"` | - |
+| disabled? | `boolean` | `false` | - |
+| className? | `string` | `"w-auto p-0 rounded-3xl"` | - |
+| calendarProps? | `Omit\<` | - | - |
+| formatStr? | `string` | `"PPP"` | - |
+
+---
+
+## DateRangePicker
+
+```tsx
+import { DateRangePicker, type DateRangePickerProps } from "@alkimi.org/ui-kit"
+```
+
+A date range picker component built with react-day-picker and date-fns, following the Shadcn pattern.
+
+### Usage
+
+```tsx
+import { DateRangePicker } from "@alkimi.org/ui-kit"
+import { useState } from "react"
+import type { DateRange } from "react-day-picker"
+
+function MyComponent() {
+  const [dateRange, setDateRange] = useState<DateRange>()
+
+  return (
+    <DateRangePicker
+      dateRange={dateRange}
+      onDateRangeChange={setDateRange}
+      placeholder="Select date range"
+    />
+  )
+}
+```
+
+### Features
+
+- Beautiful calendar UI with month/year navigation
+- Date range selection with visual feedback
+- Modal popover that stays open until both dates are selected
+- Keyboard navigation support
+- Accessible (ARIA compliant)
+- Customizable date format
+- Disabled state support
+- Min/max date restrictions
+- Configurable number of months to display
+- Integrates with Field component for labels and descriptions
+
+### Date Formatting
+
+Uses date-fns for formatting. Default format is "LLL dd, y" (e.g., "Apr 29, 2023").
+Common formats:
+- "LLL dd, y": Medium format (Apr 29, 2023)
+- "PP": Medium format (Apr 29, 2023)
+- "P": Short format (04/29/2023)
+- "yyyy-MM-dd": ISO format (2023-04-29)
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dateRange? | `DateRange` | - | - |
+| onDateRangeChange? | `(dateRange: DateRange \| undefined) =\> void` | - | - |
+| placeholder? | `string` | `"Pick a date range"` | - |
+| disabled? | `boolean` | `false` | - |
+| className? | `string` | `"w-auto p-0"` | - |
+| calendarProps? | `Omit\<` | - | - |
+| formatStr? | `string` | `"LLL dd, y"` | - |
+| numberOfMonths? | `number` | `2` | - |
+
+---
+
+## Field
+
+```tsx
+import { Field, FieldLabel, FieldDescription, type FieldProps, type FieldLabelProps, type FieldDescriptionProps } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Field`, `FieldLabel`, `FieldDescription`
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| error? | `boolean` | - | - |
+
+---
+
+## Separator
+
+```tsx
+import { Separator } from "@alkimi.org/ui-kit"
+```
+
+---
+
+## Skeleton
+
+```tsx
+import { Skeleton } from "@alkimi.org/ui-kit"
+```
+
+---
+
+## ScrollArea
+
+```tsx
+import { ScrollArea, ScrollBar } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `ScrollArea`, `ScrollBar`
+
+---
+
+## Sheet
+
+```tsx
+import { Sheet, SheetPortal, SheetOverlay, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Sheet`, `SheetPortal`, `SheetOverlay`, `SheetTrigger`, `SheetClose`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`
+
+---
+
+## Tooltip
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
+
+A popup tooltip component that displays additional information on hover.
+
+### Usage
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button>Hover me</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Tooltip message</p>
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+### Component Structure
+
+- **TooltipProvider**: Must wrap app root or parent component (controls delay)
+- **Tooltip**: Individual tooltip wrapper
+- **TooltipTrigger**: Element that triggers the tooltip (use `asChild` to pass props)
+- **TooltipContent**: The tooltip message (supports `asChild` to render custom components)
+
+### Props
+
+- **side**: Position (top, bottom, left, right)
+- **delayDuration**: Hover delay in ms (set on TooltipProvider)
+- **asChild**: Use on TooltipContent to render a Button or custom component as the tooltip content
+
+---
+
+## DropdownMenu
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuRadioGroup } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuGroup`, `DropdownMenuPortal`, `DropdownMenuSub`, `DropdownMenuSubContent`, `DropdownMenuSubTrigger`, `DropdownMenuRadioGroup`
+
+A dropdown menu component that displays a list of actions or options when triggered.
+
+### Usage
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button>Open Menu</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuItem>Settings</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### Component Structure
+
+- **DropdownMenu**: Root container
+- **DropdownMenuTrigger**: Button or element that opens the menu
+- **DropdownMenuContent**: Container for menu items
+- **DropdownMenuItem**: Individual menu action
+- **DropdownMenuLabel**: Section label
+- **DropdownMenuSeparator**: Visual divider
+- **DropdownMenuCheckboxItem**: Checkbox menu item
+- **DropdownMenuRadioGroup**: Radio button group
+- **DropdownMenuRadioItem**: Radio menu item
+- **DropdownMenuShortcut**: Keyboard shortcut display
+- **DropdownMenuSub**: Submenu container
+- **DropdownMenuSubTrigger**: Opens a submenu
+- **DropdownMenuSubContent**: Submenu content
+
+### Features
+
+- Keyboard navigation support
+- Checkbox and radio button items
+- Nested submenus
+- Keyboard shortcuts display
+- Separator and label support
+
+---
+
+## Table
+
+```tsx
+import { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCellAction, TableCaption } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCellAction`, `TableCaption`
+
+A flexible table component with multiple sub-components for structured data display.
+
+### Usage
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+      <TableHead>Role</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John Doe</TableCell>
+      <TableCell>Active</TableCell>
+      <TableCell>Admin</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Component Structure
+
+- **Table**: Root container with overflow handling
+- **TableHeader**: Header section containing column headers
+- **TableBody**: Main content area with table rows
+- **TableFooter**: Footer section for summary data
+- **TableRow**: Individual table row
+- **TableHead**: Header cell (used in TableHeader)
+- **TableCell**: Data cell (used in TableBody and TableFooter)
+- **TableCaption**: Caption text below the table
+
+### Features
+
+- Responsive overflow handling
+- Hover states on rows
+- Clickable rows with isClickable prop
+- Action icons in first column (eye or more menu)
+- Selected state support
+- Flexible styling with className props
+- Sticky first column for horizontal scrolling tables
+### Props
+
+- **stickyFirstColumn**: When true, keeps the first column fixed while scrolling horizontally
+- **rounded**: Controls border-radius size — `"default"` (20px) or `"sm"` (16px)
+
+### Clickable Rows
+
+Set isClickable={true} on TableRow to enable enhanced hover effects and cursor pointer styling. Clickable rows automatically get:
+- Cursor pointer styling
+- Enhanced hover effects (hover:bg-secondary/50)
+
+### Action Icons
+
+Add action icons to table rows using the actionIcon prop. Set actionIcon="eye" for an eye icon or actionIcon="more" for three vertical dots. The icon appears in the first column.
+
+To maintain alignment when some rows have icons and others don't, set actionIcon={null} for rows without icons. This ensures all rows have the first column space reserved. Remember to add an empty TableHead in the header row to align the action column.
+
+### Cell Actions
+
+Use `TableCellAction` to add clickable action buttons inside table cells that work independently from row clicks. The component automatically stops event propagation, so clicking an action won't trigger the row's onClick handler.
+
+```tsx
+<TableRow isClickable onClick={() => selectRow(id)}>
+  <TableCell>Name</TableCell>
+  <TableCell>
+    <TableCellAction onClick={() => openLink(url)}>
+      <ExternalLink className="h-4 w-4" />
+    </TableCellAction>
+  </TableCell>
+  <TableCell className="text-right">
+    <div className="flex justify-end gap-1">
+      <TableCellAction onClick={() => handleEdit(id)}>
+        <Pencil className="h-4 w-4" />
+      </TableCellAction>
+      <TableCellAction onClick={() => handleDelete(id)}>
+        <Trash2 className="h-4 w-4" />
+      </TableCellAction>
+    </div>
+  </TableCell>
+</TableRow>
+```
+
+TableCellAction features:
+- Stops event propagation (won't trigger row click)
+- Hover styles with background and text color change
+- Focus-visible ring for keyboard navigation
+- Works with all row types (hoverable, with icons, plain)
+- Supports `asChild` prop for custom elements (like anchor tags)
+
+### Sticky First Column
+
+For tables with many columns that require horizontal scrolling, you can keep the first column fixed in place using the `stickyFirstColumn` prop on the Table component. This ensures the first column remains visible while scrolling through other columns.
+
+```tsx
+<Table stickyFirstColumn>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Column 2</TableHead>
+      <TableHead>Column 3</TableHead>
+      {/* ... more columns */}
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Row 1</TableCell>
+      <TableCell>Data</TableCell>
+      <TableCell>Data</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+The `stickyFirstColumn` prop automatically makes the first column sticky - no additional props needed on individual cells.
+
+For more granular control, you can use the `isSticky` prop on individual `TableHead` or `TableCell` components.
+
+### Sticky Column with Action Icons
+
+When combining `stickyFirstColumn` with `actionIcon`, the table automatically makes both the action icon column and the first data column sticky. The action icon column stays at the left edge, and the data column is pinned right next to it.
+
+To align the header row correctly, set `actionIcon={null}` on the header `TableRow`. This reserves the space for the icon column without rendering an icon, keeping all columns properly aligned.
+
+```tsx
+<Table stickyFirstColumn>
+  <TableHeader>
+    <TableRow actionIcon={null}>
+      <TableHead>Name</TableHead>
+      <TableHead>Column 2</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow actionIcon="eye" isClickable>
+      <TableCell>Row 1</TableCell>
+      <TableCell>Data</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+Sticky columns with action icons feature:
+- Both the icon and first data column stay fixed while scrolling
+- Hover highlights apply to both sticky columns with an opaque background to prevent content bleeding through
+- The header row is excluded from hover effects
+- A vertical divider separates the sticky columns from the scrollable area
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| stickyFirstColumn? | `boolean` | - | - |
+| rounded? | `"default" \| "sm"` | `"default"` | - |
+| isClickable? | `boolean` | - | - |
+| actionIcon? | `"eye" \| "more" \| null` | - | - |
+| isSticky? | `boolean` | - | - |
+| isSticky? | `boolean` | - | - |
+| asChild? | `boolean` | `false` | - |
+
+---
+
+## Popover
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Popover`, `PopoverTrigger`, `PopoverContent`
+
+---
+
+## Dialog
+
+```tsx
+import { Dialog, DialogPortal, DialogOverlay, DialogClose, DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Dialog`, `DialogPortal`, `DialogOverlay`, `DialogClose`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`
+
+A modal dialog component built on Radix UI Dialog primitive.
+
+### Features
+
+- **Accessible**: Built with Radix UI primitives for full keyboard navigation and screen reader support
+- **Responsive**: Automatically renders as a centered dialog on desktop and a bottom drawer on mobile
+- **Customizable**: Style with Tailwind CSS classes
+- **Animated**: Smooth enter/exit animations with backdrop blur
+- **Focus Management**: Automatically traps focus within the dialog
+- **Escape to Close**: Press Escape key to close the dialog
+- **Click Outside**: Click the backdrop to close the dialog
+
+### Usage
+
+```tsx
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter
+} from '@alkimi.org/ui-kit/dialog'
+
+function MyComponent() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <button>Open Dialog</button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Dialog Title</DialogTitle>
+          <DialogDescription>
+            Dialog description goes here
+          </DialogDescription>
+        </DialogHeader>
+
+        <div>Dialog content...</div>
+
+        <DialogFooter>
+          <button>Cancel</button>
+          <button>Confirm</button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+### Components
+
+- **Dialog**: Root component that manages open/close state
+- **DialogTrigger**: Button that opens the dialog (use `asChild` to pass custom trigger)
+- **DialogContent**: The modal content container
+  - Props:
+    - `showCloseButton?: boolean` - Show/hide the X close button (default: `true`)
+    - `closeOnOverlayClick?: boolean` - Allow closing via clicking outside or Escape key (default: `true`)
+- **DialogHeader**: Header section for title and description
+- **DialogTitle**: Accessible title for the dialog
+- **DialogDescription**: Optional description text
+- **DialogFooter**: Footer section for action buttons
+- **DialogClose**: Wrapper for buttons that should close the dialog
+
+---
+
+## Command
+
+```tsx
+import { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`
+
+---
+
+## Combobox
+
+```tsx
+import { Combobox, type ComboboxOption, type ComboboxGroup, type ComboboxProps } from "@alkimi.org/ui-kit"
+```
+
+A searchable select component that combines a button trigger with a command palette for filtering options. Supports both single and multiple selection modes.
+
+### Usage
+
+### Single Selection
+
+```tsx
+const frameworks = [
+  { value: "next.js", label: "Next.js" },
+  { value: "react", label: "React" },
+  { value: "vue", label: "Vue" },
+]
+
+const [value, setValue] = React.useState("")
+
+<Combobox
+  options={frameworks}
+  value={value}
+  onValueChange={setValue}
+  placeholder="Select framework..."
+/>
+```
+
+### Multiple Selection
+
+```tsx
+const [values, setValues] = React.useState<string[]>([])
+
+<Combobox
+  options={frameworks}
+  multiple
+  values={values}
+  onValuesChange={setValues}
+  placeholder="Select frameworks..."
+/>
+```
+
+### With Error State
+
+```tsx
+<Combobox
+  options={frameworks}
+  value={value}
+  onValueChange={setValue}
+  error={!value}
+  placeholder="Select framework..."
+/>
+```
+
+### Grouped Options
+
+```tsx
+const groups = [
+  {
+    label: "Frontend",
+    options: [
+      { value: "react", label: "React" },
+      { value: "vue", label: "Vue" },
+    ],
+  },
+  {
+    label: "Backend",
+    options: [
+      { value: "node", label: "Node.js" },
+      { value: "django", label: "Django" },
+    ],
+  },
+]
+
+<Combobox
+  groups={groups}
+  value={value}
+  onValueChange={setValue}
+  placeholder="Select framework..."
+/>
+```
+
+### Metrics Variant
+
+```tsx
+const metrics = [
+  { value: "revenue", label: "Revenue", color: "#4ade80" },
+  { value: "buyback", label: "Buyback", color: "#facc15" },
+  { value: "mcap", label: "Mcap", color: "#f87171" },
+]
+
+const [values, setValues] = React.useState<string[]>([])
+
+<Combobox
+  options={metrics}
+  variant="metrics"
+  values={values}
+  onValuesChange={setValues}
+  placeholder="Add Metrics"
+/>
+```
+
+### Features
+
+- **Single & Multiple Selection**: Choose between single or multi-select mode
+- **Grouped Options**: Organize items under labeled headings with the `groups` prop
+- **Searchable Dropdown**: Filter options with keyboard navigation
+- **Error State**: Built-in validation styling for forms
+- **Badge Display**: Multiple selections shown as removable badges
+- **Smart Display**: Shows count badge when multiple items selected (e.g., "3 selected")
+- **Customizable Messages**: Customize placeholder, search, and empty state text
+- **Controlled State**: Full control over selected value(s)
+- **Accessible**: Proper ARIA attributes and keyboard support
+- **Disabled State**: Disable interaction when needed
+- **Auto-width**: Dropdown matches trigger button width
+- **Metrics Variant**: External colored chips with custom colors per option
+
+### Props
+
+- `options`: Array of `{ value: string, label: string, color?: string }` objects
+- `groups`: Array of `{ label: string, options: ComboboxOption[] }` objects for grouped display
+- `value`: Current selected value (single mode)
+- `onValueChange`: Callback when value changes (single mode)
+- `values`: Array of selected values (multiple mode)
+- `onValuesChange`: Callback when values change (multiple mode)
+- `multiple`: Enable multiple selection mode
+- `variant`: Visual variant - `"default"` or `"metrics"` (external colored chips)
+- `error`: Show error state styling
+- `disabled`: Disable the combobox
+- `placeholder`: Button placeholder text
+- `searchPlaceholder`: Search input placeholder
+- `emptyMessage`: Message shown when no results found
+- `searchable`: Enable/disable search input (default: `true`)
+- `showChipRemoveIcon`: Show/hide remove icon on metric chips (default: `true`)
+- `className`: Additional CSS classes
+
+### When to Use
+
+Use a Combobox when:
+- You have a list of options that users need to search through
+- The list is too long for a standard select dropdown
+- You want to provide keyboard-driven navigation
+- You need both search and selection capabilities
+- You need single or multiple selection with validation
+
+### Anatomy
+
+The Combobox is composed of:
+- **Button**: The trigger that opens the popover
+- **Popover**: The container for the command palette
+- **Command**: The searchable list component
+- **CommandInput**: The search input field
+- **CommandList**: The scrollable list of options
+- **CommandItem**: Individual selectable items
+- **Badge Display**: Selected items shown as removable badges (multiple mode)
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| options? | `ComboboxOption[]` | `[]` | - |
+| groups? | `ComboboxGroup[]` | - | - |
+| value? | `string` | - | - |
+| onValueChange? | `(value: string) =\> void` | - | - |
+| placeholder? | `string` | `"Select option..."` | - |
+| searchPlaceholder? | `string` | `"Search..."` | - |
+| emptyMessage? | `string` | `"No option found."` | - |
+| disabled? | `boolean` | `false` | - |
+| disableLabelControls? | `boolean` | `false` | - |
+| className? | `string` | `"flex flex-wrap items-center gap-2"` | - |
+| error? | `boolean` | `false` | - |
+| multiple? | `boolean` | `false` | - |
+| values? | `string[]` | `[]` | - |
+| onValuesChange? | `(values: string[]) =\> void` | - | - |
+| variant? | `"default" \| "metrics"` | `"default"` | - |
+| searchable? | `boolean` | `true` | - |
+| onTriggerClick? | `() =\> void` | - | - |
+| showChipRemoveIcon? | `boolean` | `true` | - |
+| triggerProps? | `React.ButtonHTMLAttributes\<HTMLButtonElement\>` | - | - |
+
+### ComboboxOption
+
+```typescript
+interface ComboboxOption {
+  value: string
+  label: string
+  color?: string
+}
+```
+
+### ComboboxGroup
+
+```typescript
+interface ComboboxGroup {
+  label: string
+  options: ComboboxOption[]
+}
+```
+
+---
+
+## Checkbox
+
+```tsx
+import { Checkbox } from "@alkimi.org/ui-kit"
+```
+
+A checkbox component for selecting one or multiple options from a list.
+
+### Usage
+
+```tsx
+<div className="flex items-center space-x-2">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">Accept terms and conditions</Label>
+</div>
+```
+
+### Modes
+
+- **Uncontrolled**: Use `defaultChecked` prop
+- **Controlled**: Use `checked` and `onCheckedChange` props
+
+### Props
+
+- **checked**: Controlled state (can be `true`, `false`, or `'indeterminate'`)
+- **defaultChecked**: Default state for uncontrolled mode
+- **onCheckedChange**: Callback when state changes
+- **disabled**: Prevents user interaction
+
+Fully accessible with proper labeling support.
+
+---
+
+## TreeSelect
+
+```tsx
+import { TreeSelect, type TreeSelectNode, type TreeSelectProps } from "@alkimi.org/ui-kit"
+```
+
+A hierarchical tree select component that supports arbitrary nesting depth, searchable options, and both single and multiple selection modes. Ideal for selecting from categorized data like IAB content taxonomies.
+
+### Usage
+
+### Single Selection
+
+```tsx
+const categories: TreeSelectNode[] = [
+  {
+    value: "tech",
+    label: "Technology",
+    children: [
+      { value: "web", label: "Web Development" },
+      { value: "mobile", label: "Mobile Development" },
+    ],
+  },
+]
+
+const [value, setValue] = React.useState("")
+
+<TreeSelect
+  nodes={categories}
+  value={value}
+  onValueChange={setValue}
+  placeholder="Select category..."
+/>
+```
+
+### Multiple Selection
+
+```tsx
+const [values, setValues] = React.useState<string[]>([])
+
+<TreeSelect
+  nodes={categories}
+  multiple
+  values={values}
+  onValuesChange={setValues}
+  placeholder="Select categories..."
+/>
+```
+
+### Features
+
+- **Arbitrary Nesting Depth**: Supports any number of levels in the tree hierarchy
+- **Single & Multiple Selection**: Toggle between single and multi-select modes
+- **Cascading Selection**: Selecting a parent automatically selects/deselects all children
+- **Indeterminate State**: Parent checkboxes show indeterminate state when partially selected
+- **Smart Chips**: Multi-select shows minimal chip set (parent chip replaces individual children when all selected)
+- **Searchable**: Filter nodes by typing with automatic ancestor path preservation
+- **Keyboard Navigation**: Full arrow key, Enter, Space, Home, End support
+- **Expand/Collapse**: Individually toggle node expansion or expand all by default
+- **Error State**: Built-in validation styling for forms
+- **Accessible**: WAI-ARIA treeview pattern with proper roles and attributes
+
+### Props
+
+- `nodes`: Array of `TreeSelectNode` objects (recursive: `{ value, label, children? }`)
+- `value`: Current selected value (single-select mode)
+- `onValueChange`: Callback when value changes (single-select mode)
+- `values`: Array of selected values (multi-select mode)
+- `onValuesChange`: Callback when values change (multi-select mode)
+- `multiple`: Enable multiple selection mode with checkboxes
+- `error`: Show error state styling
+- `disabled`: Disable the tree select
+- `placeholder`: Button placeholder text
+- `searchPlaceholder`: Search input placeholder
+- `emptyMessage`: Message shown when no results found
+- `className`: Additional CSS classes
+- `defaultExpandedValues`: Array of node values to expand initially
+- `expandAll`: Expand all nodes initially
+
+### Keyboard Navigation
+
+- **Arrow Down/Up**: Move focus between visible nodes
+- **Arrow Right**: Expand a collapsed node, or move to first child
+- **Arrow Left**: Collapse an expanded node
+- **Enter/Space**: Toggle selection of focused node
+- **Home/End**: Move to first/last visible node
+
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| nodes | `TreeSelectNode[]` | - | - |
+| value? | `string` | - | - |
+| onValueChange? | `(value: string) =\> void` | - | - |
+| multiple? | `boolean` | `false` | - |
+| values? | `string[]` | `[]` | - |
+| onValuesChange? | `(values: string[]) =\> void` | - | - |
+| placeholder? | `string` | `"Select..."` | - |
+| searchPlaceholder? | `string` | `"Search..."` | - |
+| emptyMessage? | `string` | `"No results found."` | - |
+| disabled? | `boolean` | `false` | - |
+| className? | `string` | `"py-6 text-center text-sm text-muted-foreground"` | - |
+| error? | `boolean` | `false` | - |
+| defaultExpandedValues? | `string[]` | - | - |
+| expandAll? | `boolean` | `false` | - |
+
+### TreeSelectNode
+
+```typescript
+interface TreeSelectNode {
+  value: string
+  label: string
+  children?: TreeSelectNode[]
+}
+```
+
+---
+
+## RadioGroup
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `RadioGroup`, `RadioGroupItem`
+
+A radio group component for selecting a single option from a list.
+
+### Usage
+
+```tsx
+<RadioGroup defaultValue="option-1">
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-1" id="option-1" />
+    <label htmlFor="option-1">Option 1</label>
+  </div>
+  <div className="flex items-center space-x-2">
+    <RadioGroupItem value="option-2" id="option-2" />
+    <label htmlFor="option-2">Option 2</label>
+  </div>
+</RadioGroup>
+```
+
+### Modes
+
+- **Uncontrolled**: Use `defaultValue` prop
+- **Controlled**: Use `value` and `onValueChange` props
+
+### Props
+
+- **value**: Controlled selected value
+- **defaultValue**: Default selected value for uncontrolled mode
+- **onValueChange**: Callback when selection changes
+- **disabled**: Prevents user interaction on all items
+
+Fully accessible with keyboard navigation and proper ARIA roles.
+
+---
+
+## Accordion
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
+
+A vertically stacked set of interactive headings that each reveal an associated section of content, built on Radix UI Accordion primitive.
+
+### Features
+
+- **Accessible**: Full keyboard navigation and screen reader support via Radix UI
+- **Single or Multiple**: Supports opening one item at a time or multiple simultaneously
+- **Animated**: Smooth expand/collapse animations
+- **Collapsible**: In single mode, the open item can be collapsed by clicking it again
+- **Customizable**: Style with Tailwind CSS classes
+
+### Usage
+
+```tsx
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from '@alkimi/ui-kit'
+
+function MyComponent() {
+  return (
+    <Accordion type="single" collapsible>
+      <AccordionItem value="item-1">
+        <AccordionTrigger>Section 1</AccordionTrigger>
+        <AccordionContent>
+          Content for section 1
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+### Components
+
+- **Accordion**: Root component. Props:
+  - `type: "single" | "multiple"` - Whether one or multiple items can be open
+  - `collapsible?: boolean` - When `type="single"`, allows closing the open item
+  - `defaultValue?: string | string[]` - Default open item(s)
+- **AccordionItem**: Wraps a trigger and content pair. Requires a unique `value` prop
+- **AccordionTrigger**: The clickable heading that toggles the content
+- **AccordionContent**: The collapsible content section
+
+---
+
+## Toaster
+
+```tsx
+import { Toaster, toast } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Toaster`, `toast`
+
+A toast notification component built on top of [Sileo](https://sileo.aaryan.design). Provides physics-based, animated notifications for user feedback.
+
+### Usage
+
+First, import the library's CSS in your app entry point (e.g. `layout.tsx` or `globals.css`):
+
+```tsx
+// layout.tsx or _app.tsx
+import "@alkimi.org/ui-kit/styles.css"
+```
+
+Or via CSS:
+
+```css
+/* globals.css */
+@import "@alkimi.org/ui-kit/styles.css";
+```
+
+Then add the `Toaster` component to your app's root layout:
+
+```tsx
+import { Toaster } from "@alkimi.org/ui-kit"
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  )
+}
+```
+
+Then use the `toast` function anywhere in your app:
+
+```tsx
+import { toast } from "@alkimi.org/ui-kit"
+
+function MyComponent() {
+  return (
+    <button onClick={() => toast.success({ title: "Hello!" })}>
+      Show Toast
+    </button>
+  )
+}
+```
+
+### Toast Types
+
+```tsx
+toast.success({ title: "Changes saved" })
+
+toast.error({
+  title: "Something went wrong",
+  description: "Please try again later.",
+})
+
+toast.warning({ title: "Storage almost full" })
+
+toast.info({ title: "New update available" })
+```
+
+### Action Toast
+
+Use `toast.action()` to include an interactive button:
+
+```tsx
+toast.action({
+  title: "File uploaded",
+  description: "Share it with your team?",
+  button: {
+    title: "Share",
+    onClick: () => console.log("Shared!"),
+  },
+})
+```
+
+### Promise Toast
+
+Chain loading, success, and error states from a single promise:
+
+```tsx
+toast.promise(fetchData(), {
+  loading: { title: "Loading..." },
+  success: { title: "Done!" },
+  error: { title: "Failed" },
+})
+```
+
+The `promise` method returns the original promise, so you can chain further.
+
+You can also pass functions to `success` and `error` to access the resolved/rejected value:
+
+```tsx
+toast.promise(createUser(data), {
+  loading: { title: "Creating account..." },
+  success: (user) => ({ title: `Welcome, ${user.name}!` }),
+  error: (err) => ({ title: "Signup failed", description: err.message }),
+})
+```
+
+### Custom Icons
+
+```tsx
+// Default state icon is shown automatically
+toast.success({ title: "Saved" })
+
+// Override with a custom React node
+toast.success({ title: "Saved", icon: <YourIcon /> })
+```
+
+### Options
+
+```tsx
+toast.success({
+  title: "Message",             // required
+  description: "Optional",
+  duration: 5000,               // ms — default 6000, null = persistent
+  icon: <YourIcon />,           // custom React node
+  position: "bottom-center",   // overrides Toaster default
+  fill: "var(--toast-bg, #27272a)",  // falls back to #27272a if CSS not imported
+  styles: {                     // Tailwind classes per element
+    title: "text-white!",
+    description: "text-white/75!",
+    badge: "bg-white/20!",
+    button: "bg-white/10!",
+  },
+  button: {
+    title: "Undo",
+    onClick: () => console.log("Undo clicked"),
+  },
+})
+```
+
+### Theming
+
+The toast badge/icon fill color is controlled by a single CSS variable:
+
+```css
+:root {
+  --toast-bg: #27272a;  /* SVG badge/icon fill color */
+}
+```
+
+This variable is set by the library after importing `@alkimi.org/ui-kit/styles.css`.
+If the CSS is **not** imported, `var(--toast-bg)` falls back to `#27272a` automatically — so the toast still renders correctly.
+
+Override it globally in your own CSS:
+
+```css
+:root {
+  --toast-bg: #1a1a2e;
+}
+```
+
+Or scope it to a specific page or component:
+
+```css
+.my-page {
+  --toast-bg: #1a1a2e;
+}
+```
+
+To override on a single toast call, pass the value directly via `fill`:
+
+```tsx
+toast.success({
+  title: "Custom color",
+  fill: "#1a1a2e",
+})
+```
+
+### Position
+
+Set the default position on `Toaster`, or override per toast:
+
+```tsx
+<Toaster position="top-right" />
+
+toast.success({ title: "Saved", position: "bottom-center" })
+```
+
+Available positions: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`
+
+---
+
+## Card
+
+```tsx
+import { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Card`, `CardHeader`, `CardFooter`, `CardTitle`, `CardDescription`, `CardContent`
+
+A flexible card container component with multiple sub-components for structured content.
+
+### Usage
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card Content</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+### Component Structure
+
+- **Card**: Root container
+- **CardHeader**: Header section for title and description
+- **CardTitle**: Title text
+- **CardDescription**: Subtitle or description text
+- **CardContent**: Main content area
+- **CardFooter**: Footer section for actions
+
+### Props
+
+- **hoverable**: When true, adds hover effect with bg-secondary and cursor-pointer
+- **rounded**: Controls border-radius size — `"default"` (20px) or `"sm"` (16px)
+- **isAnimated**: When true, shows animated blurred blobs behind the card content
+
+All sub-components are optional and can be used in any combination.
+
+---
+
+## Progress
+
+```tsx
+import { Progress } from "@alkimi.org/ui-kit"
+```
+
+A progress bar component for visualizing task completion or loading states.
+
+### Usage
+
+```tsx
+<Progress value={60} />
+<Progress value={100} className="h-4" />
+```
+
+### Props
+
+- **value**: Progress percentage (0-100)
+- **className**: Customize height using Tailwind (e.g., `h-1`, `h-4`)
+
+### Use Cases
+
+- File uploads
+- Form completion tracking
+- Skill level indicators
+- Any percentage-based metric visualization
+
+---
+
+## Slider
+
+```tsx
+import { Slider } from "@alkimi.org/ui-kit"
+```
+
+A slider component for selecting a value or range of values from a continuous range.
+
+### Component Structure
+
+The Slider component is built on top of Radix UI's Slider primitive and supports both single-value and range selections.
+
+### Key Features
+
+- **Single Value**: Select a single value from a range
+- **Range Selection**: Select a range with two thumbs (min and max)
+- **Vertical Orientation**: Display slider vertically
+- **Customizable Range**: Set custom min and max values
+- **Controlled/Uncontrolled**: Works with both controlled and uncontrolled patterns
+- **Accessible**: Full keyboard navigation and screen reader support
+
+### Usage Example
+
+```tsx
+// Single value (uncontrolled)
+<Slider defaultValue={[50]} min={0} max={100} />
+
+// Single value (controlled)
+const [value, setValue] = React.useState([50])
+<Slider value={value} onValueChange={setValue} />
+
+// Range selection
+<Slider defaultValue={[20, 80]} min={0} max={100} />
+
+// Vertical slider
+<Slider defaultValue={[50]} orientation="vertical" className="h-64" />
+```
+
+### Props
+
+- **defaultValue**: Initial value(s) as an array (e.g., `[50]` or `[20, 80]`)
+- **value**: Controlled value(s) as an array
+- **onValueChange**: Callback when value changes
+- **min**: Minimum value (default: 0)
+- **max**: Maximum value (default: 100)
+- **step**: Step size for increments (default: 1)
+- **orientation**: `"horizontal"` or `"vertical"` (default: horizontal)
+- **disabled**: Disable the slider
+- **className**: Custom CSS classes
+
+### Use Cases
+
+- Volume controls
+- Price range filters
+- Time range selectors
+- Brightness/contrast adjustments
+- Any numeric input with visual feedback
+
+---
+
+## Switch
+
+```tsx
+import { Switch } from "@alkimi.org/ui-kit"
+```
+
+A toggle switch component for binary on/off states.
+
+### Usage
+
+```tsx
+<div className="flex items-center space-x-2">
+  <Switch id="airplane" />
+  <label htmlFor="airplane">Airplane mode</label>
+</div>
+```
+
+### Modes
+
+- **Uncontrolled**: Use `defaultChecked` prop
+- **Controlled**: Use `checked` and `onCheckedChange` props
+
+### Props
+
+- **checked**: Controlled state
+- **defaultChecked**: Default state for uncontrolled mode
+- **onCheckedChange**: Callback when state changes
+- **disabled**: Prevents user interaction
+
+Perfect for settings, preferences, and feature toggles. Fully accessible.
+
+---
+
+## Breadcrumb
+
+```tsx
+import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis } from "@alkimi.org/ui-kit"
+```
+
+**Components:** `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
+
+A breadcrumb navigation component that displays the user's location within the application hierarchy.
+
+### Component Structure
+
+- **Breadcrumb**: Root container
+- **BreadcrumbList**: Wrapper for breadcrumb items
+- **BreadcrumbItem**: Individual item in the breadcrumb trail
+- **BreadcrumbLink**: Clickable link for navigable items
+- **BreadcrumbPage**: Current page (non-clickable, end of trail)
+- **BreadcrumbSeparator**: Visual separator between items (defaults to chevron)
+- **BreadcrumbEllipsis**: Collapsed items indicator for long paths
+
+### Usage
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Current</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+### Customization
+
+- Use custom separators by passing children to BreadcrumbSeparator (e.g., icons, text)
+- Use BreadcrumbEllipsis for collapsed middle sections in long paths
+
+---
+
+## Utilities
+
+```tsx
+import { cn } from "@alkimi.org/ui-kit"
+import { getSphericalGradient, getSeedColor } from "@alkimi.org/ui-kit"
+```
+
+- `cn(...classes)` — Tailwind class merging utility (clsx + tailwind-merge)
+- `getSphericalGradient(seed)` — Generate a spherical gradient for avatars
+- `getSeedColor(seed)` — Generate a deterministic color from a seed string