@l3mpire/ui 2.5.1

package/USAGE.md

@@ -0,0 +1,1025 @@
+# lemDS — Usage Guide
+
+Reference for developers and AI agents consuming the `@l3mpire/ui` and `@l3mpire/icons` packages.
+
+---
+
+## Setup
+
+```tsx
+// 1. Import global styles (once, at app entry)
+import "@l3mpire/ui/globals.css";
+
+// 2. Import components
+import { Button, Badge, TextInput } from "@l3mpire/ui";
+
+// 3. Import icons (always both variants)
+import { faHomeSolid, faHomeOutline } from "@l3mpire/icons";
+```
+
+---
+
+## Icons
+
+### Naming convention
+
+Every icon has **two variants**, always suffixed:
+
+| Variant | Suffix | Source package |
+|---|---|---|
+| Outline (regular) | `faXxxOutline` | `@fortawesome/pro-regular-svg-icons` v7 |
+| Solid (filled) | `faXxxSolid` | `@fortawesome/pro-solid-svg-icons` v7 |
+
+**No unsuffixed icon names.** Always import both when you need switching.
+
+```tsx
+import { Icon, faHomeOutline, faHomeSolid } from "@l3mpire/icons";
+
+// Simple usage — pick one variant
+<Icon icon={faHomeSolid} size="md" />
+
+// Switchable usage — pass both, toggle with `solid`
+<Icon icon={faHomeOutline} solidIcon={faHomeSolid} solid={isActive} size="sm" />
+```
+
+### Icon sizes
+
+| `size` prop | Rendered size |
+|---|---|
+| `"xs"` | 12px |
+| `"sm"` | 14px |
+| `"md"` | 16px |
+| `"lg"` | 20px |
+| `"xl"` | 24px |
+
+### Available icons
+
+All icons come in `Outline` + `Solid` pairs:
+
+`faCheck`, `faXmark`, `faPlus`, `faMinus`, `faPen`, `faTrash`, `faTrashCan`, `faMagnifyingGlass`, `faChevronDown`, `faChevronUp`, `faChevronLeft`, `faChevronRight`, `faArrowLeft`, `faArrowRight`, `faArrowUp`, `faArrowDown`, `faEllipsis`, `faEllipsisVertical`, `faSpinner`, `faCircleNotch`, `faTriangleExclamation`, `faCircleExclamation`, `faCircleCheck`, `faCircleInfo`, `faCircleXmark`, `faBell`, `faGear`, `faUser`, `faUsers`, `faEnvelope`, `faPaperPlane`, `faLink`, `faCopy`, `faDownload`, `faUpload`, `faFilter`, `faSort`, `faStar`, `faHeart`, `faEye`, `faEyeSlash`, `faLock`, `faUnlock`, `faCalendar`, `faClock`, `faHome`, `faFolder`, `faFile`, `faBookmark`, `faComment`, `faMessage`, `faSquarePlus`, `faSquareCheck`, `faPenToSquare`, `faPaperPlaneTop`, `faAddressBook`, `faBuildings`, `faChartLineUp`, `faInbox`, `faPhone`, `faVideo`, `faCoin`, `faStars`, `faArrowLeftFromLine`, `faGripDotsVertical`
+
+---
+
+## Spacing
+
+Use design token spacing classes — never arbitrary pixel values.
+
+| Class | Value |
+|---|---|
+| `p-2xs` / `gap-2xs` | 2px |
+| `p-xs` / `gap-xs` | 4px |
+| `p-sm` / `gap-sm` | 6px |
+| `p-base` / `gap-base` | 8px |
+| `p-md` / `gap-md` | 12px |
+| `p-lg` / `gap-lg` | 16px |
+| `p-xl` / `gap-xl` | 20px |
+| `p-2xl` / `gap-2xl` | 24px |
+| `p-3xl` / `gap-3xl` | 32px |
+| `p-4xl` / `gap-4xl` | 40px |
+| `p-5xl` / `gap-5xl` | 48px |
+
+Works with all Tailwind spacing prefixes: `p-`, `px-`, `py-`, `m-`, `mx-`, `my-`, `gap-`, `space-x-`, `space-y-`, `w-`, `h-`, `top-`, `left-`, etc.
+
+---
+
+## Border Radius
+
+| Class | Value |
+|---|---|
+| `rounded-none` | 0 |
+| `rounded-2xs` | 2px |
+| `rounded-xs` | 4px |
+| `rounded-sm` | 6px |
+| `rounded-base` | 8px |
+| `rounded-md` | 12px |
+| `rounded-lg` | 16px |
+| `rounded-xl` | 20px |
+| `rounded-full` | 9999px |
+
+---
+
+## Typography
+
+### Tailwind classes
+
+| Class | Size |
+|---|---|
+| `text-xxs` | 10px |
+| `text-xs` | 12px |
+| `text-sm` | 14px |
+| `text-base` | 16px |
+| `text-md` | 18px |
+| `text-lg` | 20px |
+| `text-xl` | 24px |
+
+**Line heights:** `leading-2xs` (14px), `leading-xs` (16px), `leading-sm` (20px), `leading-base` (24px), `leading-md` (28px), `leading-lg` (32px)
+
+**Font weights:** `font-regular` (400), `font-medium` (500), `font-bold` (700)
+
+### Typography component
+
+```tsx
+import { Typography } from "@l3mpire/ui";
+
+<Typography variant="h1">Heading 1</Typography>
+<Typography variant="md" weight="medium">Body text</Typography>
+<Typography variant="sm" weight="regular">Small text</Typography>
+```
+
+**Variants:** `h1`, `h2`, `h3`, `lg`, `md`, `sm`, `xs`
+**Weights:** `regular`, `medium`, `bold`
+
+---
+
+## Shadows
+
+| Class | Usage |
+|---|---|
+| `shadow-sm` | Subtle elevation |
+| `shadow-md` | Cards, dropdowns |
+| `shadow-lg` | Modals, popovers |
+| `shadow-focus-ring` | Focus state ring (3px blue) |
+
+---
+
+## Dark Mode
+
+Activate with `data-theme="dark"` on any ancestor:
+
+```html
+<div data-theme="dark">
+  <!-- All descendants render in dark mode -->
+</div>
+```
+
+All component tokens automatically switch between light and dark values.
+
+---
+
+## Components
+
+### Button
+
+```tsx
+import { Button } from "@l3mpire/ui";
+import { faPaperPlaneOutline } from "@l3mpire/icons";
+
+<Button appearance="solid" intent="brand" size="md">
+  Send
+</Button>
+
+<Button appearance="outlined" intent="neutral" size="sm" leftIcon={faPaperPlaneOutline}>
+  Send
+</Button>
+
+<Button appearance="ghost" intent="alert" size="lg" loading>
+  Deleting...
+</Button>
+
+<Button appearance="solid" intent="brand" size="md" iconOnly leftIcon={faPaperPlaneOutline} />
+```
+
+| Prop | Values |
+|---|---|
+| `appearance` | `"solid"`, `"outlined"`, `"ghost"` |
+| `intent` | `"brand"`, `"neutral"`, `"alert"` |
+| `size` | `"sm"`, `"md"`, `"lg"` |
+| `leftIcon` | `IconDefinition` |
+| `rightIcon` | `IconDefinition` |
+| `iconOnly` | `boolean` |
+| `loading` | `boolean` |
+| `disabled` | `boolean` |
+| `asChild` | `boolean` (render as child element) |
+
+---
+
+### Badge
+
+```tsx
+import { Badge } from "@l3mpire/ui";
+import { faStarOutline } from "@l3mpire/icons";
+
+<Badge variant="solid" type="primary">New</Badge>
+<Badge variant="light" type="success" size="sm">Active</Badge>
+<Badge variant="outlined" type="critical" icon={faStarOutline}>99</Badge>
+```
+
+| Prop | Values |
+|---|---|
+| `variant` | `"solid"`, `"light"`, `"outlined"` |
+| `type` | `"primary"`, `"success"`, `"critical"`, `"warning"`, `"neutral"` |
+| `size` | `"sm"`, `"md"`, `"lg"` |
+| `icon` | `IconDefinition` (optional) |
+
+---
+
+### Tag
+
+```tsx
+import { Tag } from "@l3mpire/ui";
+import { faPaperPlaneOutline } from "@l3mpire/icons";
+
+<Tag variant="brand">Label</Tag>
+<Tag variant="neutral" icon={faPaperPlaneOutline} onClose={() => {}}>
+  Campaign
+</Tag>
+```
+
+| Prop | Values |
+|---|---|
+| `variant` | `"brand"`, `"neutral"` |
+| `size` | `"sm"`, `"md"` |
+| `icon` | `IconDefinition` |
+| `onClose` | `() => void` (shows remove button when provided) |
+
+---
+
+### Link
+
+```tsx
+import { Link } from "@l3mpire/ui";
+import { faArrowRightSolid } from "@l3mpire/icons";
+
+<Link intent="brand" rightIcon={faArrowRightSolid}>Learn more</Link>
+<Link intent="neutral" size="sm">Settings</Link>
+<Link intent="alert">Delete account</Link>
+<Link intent="success">Confirmed</Link>
+```
+
+| Prop | Values |
+|---|---|
+| `intent` | `"neutral"`, `"brand"`, `"alert"`, `"success"`, `"warning"` |
+| `size` | `"sm"`, `"md"` |
+| `leftIcon` | `IconDefinition` |
+| `rightIcon` | `IconDefinition` |
+| `disabled` | `boolean` |
+| `asChild` | `boolean` |
+
+---
+
+### TextInput
+
+```tsx
+import { TextInput } from "@l3mpire/ui";
+import { faMagnifyingGlassSolid, faEnvelopeSolid } from "@l3mpire/icons";
+
+<TextInput label="Email" placeholder="you@example.com" iconLeft={faEnvelopeSolid} />
+<TextInput label="Search" iconLeft={faMagnifyingGlassSolid} onClear={() => {}} />
+<TextInput label="Name" error errorMessage="This field is required" />
+<TextInput label="Add item" hasButton onButtonClick={() => {}} />
+```
+
+| Prop | Values |
+|---|---|
+| `size` | `"sm"`, `"md"` |
+| `label` | `string` |
+| `error` | `boolean` |
+| `errorMessage` | `string` (shown below input when `error` is true) |
+| `success` | `boolean` |
+| `iconLeft` | `IconDefinition` |
+| `iconRight` | `IconDefinition` |
+| `onClear` | `() => void` (shows clear button when provided) |
+| `hasButton` | `boolean` |
+| `buttonIcon` | `IconDefinition` |
+| `onButtonClick` | `() => void` |
+| `disabled` | `boolean` |
+
+---
+
+### TextArea
+
+```tsx
+import { TextArea } from "@l3mpire/ui";
+
+<TextArea label="Message" placeholder="Type here..." />
+<TextArea label="Bio" error errorMessage="Too long" characterLimit="200" />
+```
+
+| Prop | Values |
+|---|---|
+| `label` | `string` |
+| `error` | `boolean` |
+| `errorMessage` | `string` |
+| `success` | `boolean` |
+| `characterLimit` | `string` (shows counter) |
+| `disabled` | `boolean` |
+
+---
+
+### Checkbox
+
+```tsx
+import { Checkbox } from "@l3mpire/ui";
+
+<Checkbox label="Accept terms" />
+<Checkbox label="Disabled" disabled />
+<Checkbox label="Pre-checked" defaultChecked />
+```
+
+| Prop | Values |
+|---|---|
+| `label` | `string` |
+| `checked` | `boolean` (controlled) |
+| `defaultChecked` | `boolean` (uncontrolled) |
+| `onCheckedChange` | `(checked: boolean) => void` |
+| `disabled` | `boolean` |
+
+---
+
+### Switch
+
+```tsx
+import { Switch } from "@l3mpire/ui";
+
+<Switch label="Notifications" />
+<Switch label="Disabled" disabled />
+```
+
+| Prop | Values |
+|---|---|
+| `label` | `string` |
+| `checked` | `boolean` (controlled) |
+| `defaultChecked` | `boolean` (uncontrolled) |
+| `onCheckedChange` | `(checked: boolean) => void` |
+| `disabled` | `boolean` |
+
+---
+
+### Select
+
+```tsx
+import { Select } from "@l3mpire/ui";
+
+<Select
+  label="Country"
+  placeholder="Choose..."
+  size="md"
+>
+  {/* DropdownMenu content inside */}
+</Select>
+```
+
+| Prop | Values |
+|---|---|
+| `size` | `"sm"`, `"md"` |
+| `label` | `string` |
+| `placeholder` | `string` |
+| `value` | `string` |
+| `error` | `boolean` |
+| `errorMessage` | `string` |
+| `icon` | `IconDefinition` |
+| `isOpen` | `boolean` (controlled) |
+| `onOpenChange` | `(open: boolean) => void` |
+| `disabled` | `boolean` |
+
+---
+
+### DropdownMenu
+
+Static/presentational dropdown list:
+
+```tsx
+import {
+  DropdownMenu,
+  DropdownMenuList,
+  DropdownMenuItem,
+  DropdownMenuHeading,
+  DropdownMenuClear,
+} from "@l3mpire/ui";
+
+<DropdownMenu>
+  <DropdownMenuList>
+    <DropdownMenuHeading>Section</DropdownMenuHeading>
+    <DropdownMenuItem icon={faGearSolid} label="Settings" />
+    <DropdownMenuItem label="Profile" selected />
+    <DropdownMenuClear label="Clear all" />
+  </DropdownMenuList>
+</DropdownMenu>
+```
+
+Interactive Radix-powered dropdown:
+
+```tsx
+import {
+  DropdownMenuRoot,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuRadixItem,
+} from "@l3mpire/ui";
+
+<DropdownMenuRoot>
+  <DropdownMenuTrigger asChild>
+    <Button>Open</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuRadixItem label="Option 1" />
+    <DropdownMenuRadixItem label="Option 2" />
+  </DropdownMenuContent>
+</DropdownMenuRoot>
+```
+
+---
+
+### Tooltip
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@l3mpire/ui";
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button>Hover me</Button>
+    </TooltipTrigger>
+    <TooltipContent type="default" side="top">
+      Tooltip text
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+| Prop (TooltipContent) | Values |
+|---|---|
+| `type` | `"default"`, `"invert"` |
+| `side` | `"top"`, `"right"`, `"bottom"`, `"left"` |
+| `hasArrow` | `boolean` (default: true) |
+
+---
+
+### Toast
+
+```tsx
+import { Toast } from "@l3mpire/ui";
+
+<Toast type="success" title="Saved!" subtitle="Your changes have been saved." />
+<Toast type="alert" title="Error" subtitle="Something went wrong." onClose={() => {}} />
+```
+
+| Prop | Values |
+|---|---|
+| `type` | `"info"`, `"success"`, `"alert"`, `"warning"` |
+| `title` | `React.ReactNode` (required) |
+| `subtitle` | `React.ReactNode` |
+| `onClose` | `() => void` (shows close button when provided) |
+| `actions` | `React.ReactNode` (action buttons) |
+
+---
+
+### InfoMessage
+
+```tsx
+import { InfoMessage } from "@l3mpire/ui";
+
+<InfoMessage type="info" title="Heads up" description="This is informational." />
+<InfoMessage type="warning" title="Warning" description="Check your settings." onClose={() => {}} />
+<InfoMessage
+  type="success"
+  title="Done!"
+  description="Your account was created."
+  linkLabel="View dashboard"
+  linkHref="/dashboard"
+/>
+```
+
+| Prop | Values |
+|---|---|
+| `type` | `"info"`, `"success"`, `"alert"`, `"warning"`, `"empty"` |
+| `title` | `React.ReactNode` (required) |
+| `description` | `React.ReactNode` |
+| `onClose` | `() => void` (shows close button when provided) |
+| `action` | `React.ReactNode` (e.g., a Button) |
+| `linkLabel` | `string` (shows a semantically-colored link) |
+| `linkHref` | `string` |
+| `onLinkClick` | `() => void` |
+
+---
+
+### Avatar
+
+```tsx
+import { Avatar } from "@l3mpire/ui";
+
+<Avatar size="md" src="https://example.com/photo.jpg" initials="AD" />
+<Avatar size="sm" initials="PY" />
+```
+
+| Prop | Values |
+|---|---|
+| `size` | `"sm"`, `"md"`, `"lg"`, `"xl"` |
+| `shape` | `"rounded"`, `"squared"` |
+| `src` | `string` (image URL) |
+| `alt` | `string` |
+| `initials` | `string` (fallback when no image, default: "??") |
+| `badge` | `React.ReactNode` (only visible at `xl` size) |
+
+---
+
+### SearchBar
+
+```tsx
+import { SearchBar } from "@l3mpire/ui";
+
+<SearchBar placeholder="Search for anything" hasShortcut />
+<SearchBar variant="grey" size="sm" onClear={() => {}} />
+```
+
+| Prop | Values |
+|---|---|
+| `variant` | `"white"`, `"grey"` |
+| `size` | `"sm"`, `"md"` |
+| `hasShortcut` | `boolean` (shows ⌘K badge) |
+| `placeholder` | `string` |
+| `onClear` | `() => void` (shows clear button when provided) |
+
+---
+
+### InputLabel
+
+```tsx
+import { InputLabel } from "@l3mpire/ui";
+
+<InputLabel label="Email" />
+<InputLabel label="Bio" type="optional" />
+<InputLabel label="Name" type="info" infoTooltip="Your full name" />
+```
+
+| Prop | Values |
+|---|---|
+| `type` | `"default"`, `"optional"`, `"mandatory"`, `"info"` |
+| `disabled` | `boolean` |
+| `infoIcon` | `IconDefinition` |
+
+---
+
+### Sidebar
+
+```tsx
+import {
+  Sidebar,
+  SidebarSection,
+  SidebarFooter,
+  SidebarHeadingItem,
+  SidebarItem,
+} from "@l3mpire/ui";
+import { faHomeOutline, faHomeSolid } from "@l3mpire/icons";
+
+<Sidebar isCollapsed={false}>
+  <SidebarItem icon={faHomeOutline} solidIcon={faHomeSolid} label="Home" />
+
+  <SidebarSection>
+    <SidebarHeadingItem label="Section Title" />
+    <SidebarItem icon={faGearOutline} solidIcon={faGearSolid} label="Settings" />
+  </SidebarSection>
+
+  <SidebarFooter>
+    <SidebarItem icon={faUserOutline} solidIcon={faUserSolid} label="Profile" />
+  </SidebarFooter>
+</Sidebar>
+```
+
+`SidebarItem` auto-detects collapsed state from `Sidebar` context. Icons switch from outline to solid on hover and when `state="active"`.
+
+| Prop (SidebarItem) | Values |
+|---|---|
+| `icon` | `IconDefinition` (outline variant) |
+| `solidIcon` | `IconDefinition` (solid variant) |
+| `label` | `string` |
+| `state` | `"default"`, `"hover"`, `"active"` |
+| `hasBadge` | `boolean` |
+| `badgeCount` | `string` |
+| `hasSubItems` | `boolean` |
+| `isNew` | `boolean` |
+
+---
+
+### Tabs
+
+```tsx
+import { Tabs, TabList, TabTrigger, TabContent } from "@l3mpire/ui";
+
+<Tabs defaultValue="tab1">
+  <TabList>
+    <TabTrigger value="tab1">Tab 1</TabTrigger>
+    <TabTrigger value="tab2" badge="3">Tab 2</TabTrigger>
+  </TabList>
+  <TabContent value="tab1">Content 1</TabContent>
+  <TabContent value="tab2">Content 2</TabContent>
+</Tabs>
+```
+
+| Prop (TabTrigger) | Values |
+|---|---|
+| `value` | `string` (required) |
+| `badge` | `string` (count badge) |
+| `disabled` | `boolean` |
+
+| Prop (TabList) | Values |
+|---|---|
+| `hasOffset` | `boolean` (adds left padding) |
+
+---
+
+### BrowserTab
+
+```tsx
+import { BrowserTab, BrowserTabItem } from "@l3mpire/ui";
+
+<BrowserTab activeTabId="1" onTabSelect={(id) => {}}>
+  <BrowserTabItem id="1" label="Page 1" onClose={(id) => {}} />
+  <BrowserTabItem id="2" label="Page 2" onClose={(id) => {}} />
+</BrowserTab>
+```
+
+| Prop (BrowserTab) | Values |
+|---|---|
+| `activeTabId` | `string` |
+| `onTabSelect` | `(id: string) => void` |
+| `onNewTab` | `() => void` (shows + button) |
+| `onReorder` | `(ids: string[]) => void` |
+
+| Prop (BrowserTabItem) | Values |
+|---|---|
+| `id` | `string` (required) |
+| `label` | `string` |
+| `icon` | `IconDefinition` |
+| `onClose` | `(id: string) => void` |
+
+---
+
+### Modal
+
+```tsx
+import {
+  Modal, ModalTrigger, ModalContent,
+  ModalHeader, ModalTitle, ModalDescription,
+  ModalBody, ModalFooter, ModalClose,
+  Button,
+} from "@l3mpire/ui";
+
+<Modal>
+  <ModalTrigger asChild>
+    <Button appearance="solid" intent="brand" size="md">Open</Button>
+  </ModalTrigger>
+  <ModalContent size="md">
+    <ModalHeader onClose={() => {}}>
+      <ModalTitle>Title</ModalTitle>
+      <ModalDescription>Optional description</ModalDescription>
+    </ModalHeader>
+    <ModalBody>Content goes here</ModalBody>
+    <ModalFooter>
+      <ModalClose asChild>
+        <Button appearance="ghost" intent="brand" size="md">Cancel</Button>
+      </ModalClose>
+      <Button appearance="solid" intent="brand" size="md">Confirm</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+| Prop (ModalContent) | Values |
+|---|---|
+| `size` | `"sm"` (500px), `"md"` (800px), `"lg"` (1100px), `"full"` (100% − 32px) |
+
+| Prop (ModalHeader) | Values |
+|---|---|
+| `showBorder` | `boolean` (default: true) |
+| `onClose` | `() => void` (shows close button when provided) |
+
+| Prop (ModalFooter) | Values |
+|---|---|
+| `showBorder` | `boolean` (default: true) |
+| `infoMessage` | `string` (shows info icon + text on the left) |
+
+**Sub-components:** `Modal`, `ModalTrigger`, `ModalContent`, `ModalHeader`, `ModalTitle`, `ModalDescription`, `ModalBody`, `ModalFooter`, `ModalClose`
+
+---
+
+### Dialog
+
+Pre-composed confirmation dialog (Modal SM without header border). Supports `brand` and `alert` intents.
+
+```tsx
+import { Dialog, Button } from "@l3mpire/ui";
+
+const [open, setOpen] = React.useState(false);
+
+<Button onClick={() => setOpen(true)}>Delete</Button>
+
+<Dialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete Item"
+  description="This action cannot be undone."
+  intent="alert"
+  primaryLabel="Delete"
+  cancelLabel="Cancel"
+  onPrimaryAction={() => { deleteItem(); setOpen(false); }}
+/>
+```
+
+| Prop | Values |
+|---|---|
+| `open` | `boolean` (controlled) |
+| `onOpenChange` | `(open: boolean) => void` |
+| `title` | `string` (required) |
+| `description` | `string` |
+| `intent` | `"brand"`, `"alert"` |
+| `primaryLabel` | `string` (default: "Confirm") |
+| `onPrimaryAction` | `() => void` |
+| `primaryDisabled` | `boolean` |
+| `cancelLabel` | `string` (default: "Cancel") |
+| `onCancel` | `() => void` |
+| `secondaryLabel` | `string` (shows third button) |
+| `onSecondaryAction` | `() => void` |
+
+---
+
+### SidePanel
+
+Full-height panel that slides in from the right. Reuses `ModalHeader`, `ModalBody`, `ModalFooter` for composition.
+
+```tsx
+import {
+  SidePanel, SidePanelTrigger, SidePanelContent,
+  ModalHeader, ModalTitle, ModalDescription,
+  ModalBody, ModalFooter, ModalClose,
+  Button,
+} from "@l3mpire/ui";
+
+<SidePanel>
+  <SidePanelTrigger asChild>
+    <Button appearance="solid" intent="brand" size="md">Open</Button>
+  </SidePanelTrigger>
+  <SidePanelContent>
+    <ModalHeader onClose={() => {}}>
+      <ModalTitle>Title</ModalTitle>
+      <ModalDescription>Description</ModalDescription>
+    </ModalHeader>
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>
+      <ModalClose asChild>
+        <Button appearance="ghost" intent="brand" size="md">Cancel</Button>
+      </ModalClose>
+      <Button appearance="solid" intent="brand" size="md">Save</Button>
+    </ModalFooter>
+  </SidePanelContent>
+</SidePanel>
+```
+
+| Prop (SidePanelContent) | Values |
+|---|---|
+| `overlay` | `boolean` (default: true — shows dimmed overlay) |
+| `className` | Override positioning (e.g., `"absolute inset-y-0 right-0"` for container-relative) |
+
+Header and footer are optional — compose with `ModalHeader`, `ModalBody`, `ModalFooter` as needed.
+
+---
+
+### UserMenu
+
+```tsx
+import { UserMenu, UserMenuInfoRow, UserMenuSection } from "@l3mpire/ui";
+
+<UserMenu>
+  <UserMenuInfoRow
+    name="John Doe"
+    email="john@example.com"
+    avatarSrc="https://..."
+  />
+  <UserMenuSection>
+    <DropdownMenuItem icon={faGearSolid} label="Settings" />
+    <DropdownMenuItem icon={faArrowRightSolid} label="Sign out" />
+  </UserMenuSection>
+</UserMenu>
+```
+
+---
+
+### ProductLogo
+
+Renders product logos for lemlist, lemwarm, and lemcal. Supports icon-only or full logotype (icon + text) modes. Automatically switches between light and dark SVGs based on `data-theme`.
+
+```tsx
+import { ProductLogo } from "@l3mpire/ui";
+
+// Full logotype (icon + text)
+<ProductLogo product="lemlist" size="lg" hasText />
+
+// Icon only
+<ProductLogo product="lemcal" size="md" hasText={false} />
+```
+
+| Prop | Values |
+|---|---|
+| `product` | `"lemlist"`, `"lemwarm"`, `"lemcal"` |
+| `size` | `"sm"` (20px), `"md"` (28px), `"lg"` (32px), `"xl"` (40px, icon-only) |
+| `hasText` | `boolean` — `true` = logotype, `false` = icon only |
+
+**Notes:**
+- `xl` size is icon-only regardless of `hasText`
+- Automatically detects dark mode via `data-theme="dark"` attribute
+
+---
+
+### Table (Low-Level)
+
+```tsx
+import {
+  Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+} from "@l3mpire/ui";
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>John</TableCell>
+      <TableCell>john@example.com</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+### DataTable
+
+Data-driven table powered by TanStack Table. Wraps the low-level `Table` primitives with opt-in features.
+
+```tsx
+import { DataTable, DataTablePagination, type ColumnDef } from "@l3mpire/ui";
+
+const columns: ColumnDef<Person>[] = [
+  { accessorKey: "name", header: "Name" },
+  { accessorKey: "email", header: "Email" },
+];
+
+<DataTable
+  columns={columns}
+  data={people}
+  enableSorting
+  enablePagination
+  enableColumnResizing
+  bordered
+>
+  {(table) => <DataTablePagination table={table} />}
+</DataTable>
+```
+
+| Prop | Default | Description |
+|---|---|---|
+| `columns` | *required* | TanStack Table column definitions |
+| `data` | *required* | Array of row data |
+| `enableSorting` | `false` | Client-side column sorting |
+| `enableFiltering` | `false` | Client-side column filtering with popover |
+| `enablePagination` | `false` | Client-side pagination |
+| `enableRowSelection` | `false` | Row selection via checkbox |
+| `enableColumnVisibility` | `false` | Toggle column visibility |
+| `enableColumnPinning` | `false` | Pin columns left/right |
+| `enableColumnResizing` | `false` | Drag to resize columns |
+| `enableColumnDrag` | `false` | Drag to reorder columns |
+| `bordered` | `false` | Border-top on header (full-width layouts) |
+| `emptyState` | — | `ReactNode` shown when `data` is empty |
+| `sorting` | — | Controlled sorting state |
+| `onSortingChange` | — | Controlled sorting callback |
+| `columnFilters` | — | Controlled filter state |
+| `onColumnFiltersChange` | — | Controlled filter callback |
+| `rowSelection` | — | Controlled selection state |
+| `onRowSelectionChange` | — | Controlled selection callback |
+| `children` | — | Render prop `(table) => ReactNode` for pagination |
+
+#### Column Meta
+
+Use `meta` on column definitions for extended features:
+
+```tsx
+const columns: ColumnDef<Item>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+    meta: {
+      icon: faUserOutline,        // Leading icon in header
+      enableDrag: true,           // Draggable (requires enableColumnDrag)
+      filterType: "string",       // Filter popover type: "string" | "number" | "date" | "select"
+      filterOptions: ["A", "B"], // Options for "select" filter type
+    },
+  },
+];
+```
+
+#### Cell Renderers
+
+Pre-built cell components for common patterns:
+
+```tsx
+import {
+  AvatarCell, StatusCell, NumberCell, DateCell,
+  EmailCell, LinkCell, ButtonCell, EditableCell, RowActions,
+} from "@l3mpire/ui";
+
+// In column definitions:
+{ cell: ({ row }) => <AvatarCell name={row.original.name} src={row.original.avatar} /> }
+{ cell: ({ row }) => <StatusCell status="active" /> }
+{ cell: ({ row }) => <NumberCell value={row.original.amount} /> }
+{ cell: ({ row }) => <DateCell value={row.original.date} /> }
+{ cell: ({ row }) => <EmailCell value={row.original.email} /> }
+{ cell: ({ row }) => <EditableCell value={row.original.name} onSave={(v) => {}} /> }
+{ cell: ({ row }) => <RowActions actions={[{ label: "Edit", onClick: () => {} }]} /> }
+```
+
+---
+
+### EmptyState
+
+```tsx
+import { EmptyState } from "@l3mpire/ui";
+import { faUsersSolid } from "@l3mpire/icons";
+
+<EmptyState
+  icon={faUsersSolid}
+  title="No results"
+  description="Try a different search query."
+  size="md"
+/>
+
+<EmptyState
+  icon={faUsersSolid}
+  title="No contacts yet"
+  size="lg"
+  action={<Button appearance="solid" intent="brand" size="md">Add contact</Button>}
+/>
+```
+
+| Prop | Values |
+|---|---|
+| `icon` | `IconDefinition` |
+| `title` | `string` (required) |
+| `description` | `string` |
+| `size` | `"sm"`, `"md"`, `"lg"` |
+| `action` | `ReactNode` (e.g., a Button) |
+
+---
+
+## Size Availability
+
+| Component | sm | md | lg | xl |
+|---|---|---|---|---|
+| Button | x | x | x | |
+| Badge | x | x | x | |
+| Tag | x | x | | |
+| Link | x | x | | |
+| TextInput | x | x | | |
+| Select | x | x | | |
+| SearchBar | x | x | | |
+| Avatar | x | x | x | x |
+| Modal | x | x | x | full |
+| EmptyState | x | x | x | |
+
+---
+
+## Color Token Patterns
+
+Component colors follow this convention:
+
+```
+Token CSS var:   --comp-{component}-{variant}-{property}
+Theme class:     {component}-{variant}-{property}  (comp- prefix dropped)
+Tailwind usage:  bg-{component}-{variant}-{property}
+                 text-{component}-{variant}-{property}
+                 border-{component}-{variant}-{property}
+```
+
+Examples:
+- `bg-badge-solid-primary-bg` → badge solid primary background
+- `text-toast-title` → toast title text color
+- `border-text-input-border-default` → text input default border
+
+---
+
+## Utility: `cn()`
+
+Merge Tailwind classes safely (handles conflicts):
+
+```tsx
+import { cn } from "@l3mpire/ui";
+
+<div className={cn("p-base text-sm", isActive && "bg-primary", className)} />
+```
+
+---
+
+## Build Order
+
+```
+tokens → icons → ui → storybook
+```
+
+```bash
+pnpm --filter @l3mpire/tokens build
+pnpm --filter @l3mpire/icons build
+pnpm --filter @l3mpire/ui build
+pnpm --filter @l3mpire/storybook dev   # launches Storybook
+```