@zvoove/unity-ui 2.20.1 → 2.21.0

package/dist/llms.txt

@@ -0,0 +1,1185 @@
+# Unity UI (@zvoove/unity-ui) - AI Component Reference
+
+> This file describes all available components in the Unity UI design system.
+> When building UIs, use ONLY these components. Do NOT create custom components for functionality already provided here.
+
+## Setup
+
+Install:
+```bash
+npm install @zvoove/unity-ui
+```
+
+Import styles (required, add to your app entry point):
+```css
+@import '@zvoove/unity-ui/theme.css';
+@import '@zvoove/unity-ui/unity-ui.css';
+```
+
+Import components:
+```tsx
+import { Button, Card, TextField, Typography } from '@zvoove/unity-ui';
+```
+
+Font (add to HTML head):
+```html
+<link href="https://fonts.googleapis.com/css2?family=Source+Sans+3:ital,wght@0,200..900;1,200..900&display=swap" rel="stylesheet" />
+```
+
+Dark mode: add `data-theme="dark"` to a parent element.
+
+## Responsive Props
+
+Many props accept `ResponsiveType<T>`, meaning either a direct value OR a breakpoint object.
+Breakpoints (from smallest to largest): `minimum` (0px), `mobile` (320px), `tablet` (768px), `laptop` (1024px), `desktop` (1440px).
+Values cascade upward — setting `mobile` applies to all larger breakpoints until overridden.
+
+```tsx
+// Direct value — applies to all screen sizes
+<Button size="md" />
+
+// Responsive object — values cascade up from smallest to largest
+<Button size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }} />
+// mobile: sm → tablet: md → laptop: md (inherited) → desktop: lg
+
+// Common patterns:
+<Stack direction={{ mobile: 'column', tablet: 'row' }} />           // Stack vertically on mobile, horizontally on tablet+
+<Grid columns={{ mobile: 1, tablet: 2, desktop: 3 }} />             // Responsive grid columns
+<Card padding={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }} />    // Responsive padding
+<Button hideLabel={{ mobile: true, tablet: false }} icon="Plus" />   // Icon-only on mobile, label on tablet+
+<Dialog size={{ mobile: 'fullscreen', tablet: 'md' }} />             // Fullscreen on mobile, modal on tablet+
+```
+
+---
+
+## LAYOUT COMPONENTS
+
+### Stack
+**Primary layout component.** Use Stack for ALL layout needs — arranging children in rows or columns with consistent spacing. Do NOT use Card or raw divs for layout.
+```tsx
+import { Stack } from '@zvoove/unity-ui';
+
+<Stack
+  direction="column"           // ResponsiveType<'row' | 'row-reverse' | 'column' | 'column-reverse'>
+  gap="md"                     // ResponsiveType<SpacingKeys> - none|xs2|xs|sm|md|lg|xl|xl2|xl3|xl4|xl5|xl6|xl7
+  align="center"               // ResponsiveType<AlignItems> - default: 'baseline'
+  justify="space-between"      // ResponsiveType<JustifyContent>
+  wrap="wrap"                  // ResponsiveType<FlexWrap>
+  padding="md"                 // ResponsiveType<Padding>
+  margin="none"                // ResponsiveType<Margin>
+  width="100%"                 // ResponsiveType<number | string>
+  height="auto"                // ResponsiveType<number | string>
+  minWidth, maxWidth, minHeight, maxHeight  // ResponsiveType<number | string>
+>
+  {children}
+</Stack>
+```
+
+Common patterns:
+```tsx
+// Page layout — stacks vertically on mobile, horizontally on tablet+
+<Stack direction={{ mobile: 'column', tablet: 'row' }} gap="lg">
+  <Sidebar />
+  <MainContent />
+</Stack>
+
+// Form fields in a row
+<Stack direction="row" gap="md" align="flex-end">
+  <TextField label="First name" name="first" />
+  <TextField label="Last name" name="last" />
+</Stack>
+
+// Action bar — right-aligned buttons
+<Stack direction="row" gap="sm" justify="flex-end">
+  <Button variant="outlined">Cancel</Button>
+  <Button variant="filled">Save</Button>
+</Stack>
+
+// Centered content
+<Stack direction="column" align="center" justify="center" gap="md" height="100%">
+  <Icon name="check-circle" size="2xl" />
+  <Typography variant="headline" size="medium">Success!</Typography>
+</Stack>
+```
+
+### Grid
+CSS Grid container with Grid.Item children. Use Grid when you need multi-column layouts. Use Stack for simpler row/column arrangements.
+```tsx
+import { Grid } from '@zvoove/unity-ui';
+
+<Grid
+  columns={3}                  // ResponsiveType<number | string> - default: 1
+  rows={1}                     // ResponsiveType<number | string> - default: 1
+  gap="md"                     // ResponsiveType<SpacingKeys>
+  padding="none"               // ResponsiveType<Padding>
+  margin="none"                // ResponsiveType<Margin>
+  width="100%"                 // ResponsiveType<number | string>
+  height="auto"                // ResponsiveType<number | string>
+>
+  <Grid.Item colSpan={2} rowSpan={1}>Content</Grid.Item>
+  <Grid.Item colSpan={1}>Content</Grid.Item>
+</Grid>
+```
+
+Common patterns:
+```tsx
+// Responsive card grid — 1 col on mobile, 2 on tablet, 3 on desktop
+<Grid columns={{ mobile: 1, tablet: 2, desktop: 3 }} gap="lg">
+  <Grid.Item><Card>Item 1</Card></Grid.Item>
+  <Grid.Item><Card>Item 2</Card></Grid.Item>
+  <Grid.Item><Card>Item 3</Card></Grid.Item>
+</Grid>
+
+// Form layout — 2 fields side by side on tablet+, stacked on mobile
+<Grid columns={{ mobile: 1, tablet: 2 }} gap="md">
+  <Grid.Item><TextField label="First name" name="first" /></Grid.Item>
+  <Grid.Item><TextField label="Last name" name="last" /></Grid.Item>
+</Grid>
+
+// Wide + narrow column layout
+<Grid columns={3} gap="md">
+  <Grid.Item colSpan={2}><Card>Main content</Card></Grid.Item>
+  <Grid.Item colSpan={1}><Card>Sidebar</Card></Grid.Item>
+</Grid>
+```
+
+### Card
+**Visual container** with background, elevation, and border. Use Card to group content visually (e.g., a profile card, a settings panel, a content section). Do NOT use Card for layout — use Stack or Grid instead. Card is a surface, not a layout tool.
+```tsx
+import { Card } from '@zvoove/unity-ui';
+
+<Card
+  variant="filled"             // 'outlined' | 'filled' (default: 'filled')
+  padding="md"                 // ResponsiveType<Padding> - default: 'md'. Use "none" for edge-to-edge content
+  margin="none"                // ResponsiveType<Margin>
+  elevation={1}                // 0 | 1 | 2 | 3 | 4 | 5 (default: 0)
+  borderRadius="md"            // 'none' | 'sm' | 'md' | 'lg' | 'xl'
+  bgColor="surface"            // BackgroundColors (default: 'surface')
+  overflow="visible"           // ResponsiveType<Overflow>
+  width, height, minWidth, maxWidth, minHeight, maxHeight  // ResponsiveType
+>
+  {children}
+</Card>
+```
+
+Common patterns:
+```tsx
+// Content card with internal layout using Stack (NOT Card for layout)
+<Card variant="outlined" padding="lg" elevation={1}>
+  <Stack direction="column" gap="md">
+    <Typography variant="title" size="large">Profile</Typography>
+    <Typography variant="body" size="medium">User details here.</Typography>
+  </Stack>
+</Card>
+
+// Card with no padding — useful for full-width content like images or tables
+<Card variant="outlined" padding="none">
+  <img src="/banner.jpg" style={{ width: '100%' }} />
+  <Stack padding="md" gap="sm">
+    <Typography variant="title" size="medium">Article title</Typography>
+    <Typography variant="body" size="medium">Article excerpt...</Typography>
+  </Stack>
+</Card>
+
+// Responsive padding — tighter on mobile, more spacious on desktop
+<Card padding={{ mobile: 'sm', tablet: 'md', desktop: 'xl' }} elevation={2}>
+  {children}
+</Card>
+
+// WRONG: Do NOT use Card for layout. Use Stack instead.
+// Bad:  <Card><TextField /><TextField /></Card>
+// Good: <Stack direction="column" gap="md"><TextField /><TextField /></Stack>
+```
+
+### Divider
+Horizontal separator line.
+```tsx
+import { Divider } from '@zvoove/unity-ui';
+
+<Divider variant="fullWidth" />  // 'fullWidth' | 'inset' | 'middle'
+```
+
+### Expandable
+Animated collapsible container.
+```tsx
+import { Expandable } from '@zvoove/unity-ui';
+
+<Expandable isOpen={true} as="div">
+  {children}
+</Expandable>
+```
+
+### ContentBlock
+Simple content wrapper.
+```tsx
+import { ContentBlock } from '@zvoove/unity-ui';
+
+<ContentBlock>{children}</ContentBlock>
+```
+
+---
+
+## TYPOGRAPHY
+
+### Typography
+Text rendering component with variants. Use Typography for ALL text — never use raw `<p>`, `<h1>`, `<span>` tags.
+```tsx
+import { Typography } from '@zvoove/unity-ui';
+
+<Typography
+  variant="body"               // 'display' | 'headline' | 'title' | 'body' | 'label'
+  size="medium"                // 'small' | 'medium' | 'large'
+  as="p"                       // 'p' | 'span' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+  color="on-surface"           // ForegroundColors
+  textAlign="left"             // 'left' | 'center' | 'right'
+  textTransform="uppercase"    // 'uppercase' | 'lowercase' | 'capitalize'
+  truncate={2}                 // number - max lines before truncation
+  hyphenate={true}             // boolean (default: true)
+  wrap={true}                  // boolean
+>
+  Text content
+</Typography>
+```
+
+Variant guide:
+```tsx
+// Page heading
+<Typography variant="display" size="large" as="h1">Page Title</Typography>
+
+// Section heading
+<Typography variant="headline" size="medium" as="h2">Section Title</Typography>
+
+// Card/dialog title
+<Typography variant="title" size="large">Card Title</Typography>
+
+// Body text (default)
+<Typography variant="body" size="medium">Paragraph text goes here.</Typography>
+
+// Small labels, captions
+<Typography variant="label" size="small" color="on-surface-variant">Updated 2 hours ago</Typography>
+
+// Truncate long text to 2 lines
+<Typography variant="body" size="medium" truncate={2}>Very long text that will be cut off...</Typography>
+```
+
+---
+
+## FORM COMPONENTS
+
+### TextField
+Text input with label, validation, and icon support.
+```tsx
+import { TextField } from '@zvoove/unity-ui';
+
+<TextField
+  label="Email"                // string (required)
+  name="email"                 // string
+  value={value}                // string
+  onChange={handleChange}       // (event: ChangeEvent<HTMLInputElement>) => void
+  placeholder="Enter email"    // string
+  error={false}                // boolean
+  errorMessage="Invalid email" // string
+  disabled={false}             // boolean
+  hideLabel={false}            // boolean
+  clearable={false}            // boolean
+  icon="MagnifyingGlass"       // CommonIconNames
+  iconPosition="right"         // 'left' | 'right'
+  onIconClick={handleClick}    // () => void
+  density="default"            // ResponsiveType<'default' | '-2' | '-4'>
+  type="text"                  // standard HTML input types
+  required={false}             // boolean
+/>
+```
+
+### Textarea
+Multi-line text input.
+```tsx
+import { Textarea } from '@zvoove/unity-ui';
+
+<Textarea
+  value={value}                // string
+  onChange={handleChange}       // ChangeEventHandler<HTMLTextAreaElement>
+  error={false}                // boolean
+  errorMessage="Too long"      // string
+  maxLength={500}              // number
+  actions={<Button>Save</Button>}  // ReactNode
+  rows={4}                     // number (standard HTML)
+  placeholder="Enter text"     // string
+  disabled={false}             // boolean
+/>
+```
+
+### Select
+Dropdown select with search and multi-select support.
+```tsx
+import { Select } from '@zvoove/unity-ui';
+
+<Select
+  name="country"               // string (required)
+  label="Country"              // string
+  options={[                   // SelectOption[] (required)
+    { value: 'de', label: 'Germany', icon: 'Flag' },
+    { value: 'us', label: 'United States' },
+  ]}
+  value="de"                   // string | string[]
+  onChange={handleChange}       // ChangeEventHandler<HTMLSelectElement>
+  multiple={false}             // boolean
+  searchable={false}           // boolean
+  error={false}                // boolean
+  errorMessage="Required"      // string
+  disabled={false}             // boolean
+  hideLabel={false}            // boolean
+/>
+```
+
+Common patterns:
+```tsx
+// Searchable select — for long option lists
+<Select name="country" label="Country" searchable={true} options={countries} />
+
+// Multi-select
+<Select
+  name="tags"
+  label="Tags"
+  multiple={true}
+  value={['react', 'typescript']}
+  options={[
+    { value: 'react', label: 'React' },
+    { value: 'typescript', label: 'TypeScript' },
+    { value: 'node', label: 'Node.js' },
+  ]}
+/>
+
+// With icons
+<Select
+  name="priority"
+  label="Priority"
+  options={[
+    { value: 'high', label: 'High', icon: 'arrow-up' },
+    { value: 'medium', label: 'Medium', icon: 'minus' },
+    { value: 'low', label: 'Low', icon: 'arrow-down' },
+  ]}
+/>
+```
+
+### Checkbox
+Checkbox input with label.
+```tsx
+import { Checkbox } from '@zvoove/unity-ui';
+
+<Checkbox
+  label="Accept terms"         // ReactNode (required)
+  name="terms"                 // string
+  checked={false}              // boolean
+  onChange={handleChange}       // ChangeEventHandler<HTMLInputElement>
+  disabled={false}             // boolean
+  error={false}                // boolean
+  indeterminate={false}        // boolean
+  value="accepted"             // string
+/>
+```
+
+### Radio (RadioGroup + RadioButton)
+Radio button group for single selection.
+```tsx
+import { RadioGroup, RadioButton } from '@zvoove/unity-ui';
+
+<RadioGroup
+  name="size"                  // string (required)
+  value={selectedValue}        // string
+  onChange={handleChange}       // (e: ChangeEvent<HTMLInputElement>) => void
+  row={false}                  // boolean - horizontal layout
+  disabled={false}             // boolean
+>
+  <RadioButton label="Small" value="sm" />
+  <RadioButton label="Medium" value="md" />
+  <RadioButton label="Large" value="lg" />
+</RadioGroup>
+```
+
+### Switch
+Toggle switch input.
+```tsx
+import { Switch } from '@zvoove/unity-ui';
+
+<Switch
+  checked={false}              // boolean
+  onChange={handleChange}       // ChangeEventHandler<HTMLInputElement>
+  label="Enable notifications" // string | { on: string; off: string }
+  labelPlacement="left"        // 'left' | 'right' (default: 'left')
+  justify="space-between"      // JustifyContent
+  disabled={false}             // boolean
+  withIcons={false}            // boolean | { on: IconName; off: IconName }
+  name="notifications"         // string
+  value="enabled"              // string
+/>
+```
+
+### DatePicker
+Date input with calendar popup.
+```tsx
+import { DatePicker } from '@zvoove/unity-ui';
+
+<DatePicker
+  label="Start date"           // string (required)
+  name="startDate"             // string (required)
+  value="2024-01-15"           // string (YYYY-MM-DD)
+  onChange={handleChange}       // (e: ChangeEvent<HTMLInputElement>, date?: Date) => void
+  locale="en-US"               // string (default: 'de-DE')
+  minDate="2024-01-01"         // string (YYYY-MM-DD)
+  maxDate="2024-12-31"         // string (YYYY-MM-DD)
+  openOnFocus={false}          // boolean
+  closeOnSelect={false}        // boolean
+  placeholder="Select date"    // string
+  error={false}                // boolean
+  errorMessage="Invalid date"  // string
+  disabled={false}             // boolean
+  buttonsTranslations={{ cancel: 'Cancel', clear: 'Clear', ok: 'OK' }}
+/>
+```
+
+### Uploader
+File upload component with drag-and-drop.
+```tsx
+import { Uploader } from '@zvoove/unity-ui';
+
+<Uploader
+  accept="image/*,.pdf"        // string
+  multiple={true}              // boolean (default: true)
+  maxFileSize={5000000}        // number (bytes)
+  maxTotalSize={20000000}      // number (bytes)
+  maxCount={10}                // number
+  value={files}                // FileItem[]
+  onChange={handleChange}       // (event: ChangeEvent) => void
+  onValidation={handleError}   // (event: ValidationEvent) => void
+  disabled={false}             // boolean
+  canDeleteFile={true}         // boolean
+  selectionMode="append"       // 'append' | 'replace' (default: 'append')
+  showFileList={true}          // boolean (default: true)
+  name="files"                 // string
+  required={false}             // boolean
+/>
+```
+
+### FormLabel
+Label for form fields.
+```tsx
+import { FormLabel } from '@zvoove/unity-ui';
+
+<FormLabel value="Email address" htmlFor="email" required={true} />
+```
+
+---
+
+## ACTION COMPONENTS
+
+### Button
+Primary action component with multiple variants.
+```tsx
+import { Button } from '@zvoove/unity-ui';
+
+<Button
+  variant="filled"             // ResponsiveType<'filled' | 'outlined' | 'text' | 'textSecondary' | 'elevated' | 'tonal' | 'linkPrimary' | 'linkSecondary' | 'positive' | 'negative'>
+  size="lg"                    // ResponsiveType<'sm' | 'md' | 'lg'> (default: 'lg')
+  icon="Plus"                  // CommonIconNames | Omit<IconProps, 'size' | 'color'>
+  hideLabel={false}            // ResponsiveType<boolean>
+  onClick={handleClick}        // (event: MouseEvent) => void
+  isLoading={false}            // boolean
+  disabled={false}             // boolean
+  as="button"                  // 'a' | 'button' | 'span' (default: 'button')
+  linkComponent={Link}         // React.ElementType (for router links)
+>
+  Click me
+</Button>
+```
+
+Variant guide:
+```tsx
+// Primary action → filled
+<Button variant="filled">Save</Button>
+
+// Secondary action → outlined
+<Button variant="outlined">Cancel</Button>
+
+// Destructive action → negative
+<Button variant="negative" icon="delete">Delete</Button>
+
+// Success action → positive
+<Button variant="positive" icon="check">Confirm</Button>
+
+// Subtle/tertiary action → text
+<Button variant="text">Learn more</Button>
+
+// Link-style button → linkPrimary / linkSecondary
+<Button variant="linkPrimary">View details</Button>
+
+// Icon-only button (must have aria-label)
+<Button variant="outlined" icon="edit" aria-label="Edit item" />
+
+// Responsive: icon-only on mobile, full label on tablet+
+<Button variant="filled" icon="add" hideLabel={{ mobile: true, tablet: false }}>
+  Add item
+</Button>
+
+// Loading state
+<Button variant="filled" isLoading={true}>Saving...</Button>
+
+// As a router link
+<Button variant="filled" linkComponent={Link} href="/settings">Settings</Button>
+```
+
+### Segment (SegmentGroup + SegmentButton)
+Segmented control for toggling between options.
+```tsx
+import { SegmentGroup, SegmentButton } from '@zvoove/unity-ui';
+
+<SegmentGroup
+  activeButton="list"          // V | V[]
+  onChange={handleChange}       // (value: V | V[]) => void
+  stretch={false}              // boolean
+  multiSelect={false}          // boolean
+  disabled={false}             // boolean
+>
+  <SegmentButton value="list" label="List" icon="List" />
+  <SegmentButton value="grid" label="Grid" icon="GridFour" />
+</SegmentGroup>
+```
+
+### PopUpMenu
+Context menu / dropdown menu.
+```tsx
+import { PopUpMenu } from '@zvoove/unity-ui';
+
+<PopUpMenu
+  items={[                     // PopUpMenuItem[] (required)
+    { id: '1', label: 'Edit', icon: 'Pencil' },
+    { id: '2', label: 'Delete', icon: 'Trash', variant: 'error' },
+    { id: 'divider', isDivider: true },
+    { id: '3', label: 'Settings' },
+  ]}
+  trigger="click"              // 'hover' | 'click' | 'right-click' (default: 'click')
+  placement="bottom-left"      // PopUpMenuPlacement (default: 'bottom-left')
+  selectable="none"            // 'single' | 'multiple' | 'none' (default: 'none')
+  selectedItem={selected}      // string | string[]
+  onItemClick={handleClick}    // (item, selectedItem?) => void
+  density="default"            // 'default' | '-2' | '-4'
+  showSearch={false}           // boolean
+  searchPlaceholder="Search"   // string
+  disabled={false}             // boolean
+>
+  <Button>Actions</Button>
+</PopUpMenu>
+```
+
+---
+
+## DATA DISPLAY COMPONENTS
+
+### Table
+Data table with sorting, expandable rows, and actions.
+```tsx
+import { Table } from '@zvoove/unity-ui';
+
+const columns = [
+  { id: 'name', label: 'Name', orderable: true },
+  { id: 'email', label: 'Email' },
+  { id: 'role', label: 'Role', align: 'right' as const },
+] as const;
+
+<Table
+  columns={columns}            // TableColumnProps[] (required)
+  data={[                      // TableRowData[] (required)
+    { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin' },
+  ]}
+  title="Users"                // string
+  subtitle="All active users"  // string
+  actions={<Button>Add user</Button>}  // ReactNode
+  filters={filterComponent}    // ReactNode
+  loading={false}              // boolean
+  orderBy={{ column: 'name', direction: 'asc' }}
+  onOrderByChange={handleSort} // ({ columnId, direction }) => void
+  hiddenColumns={['email']}    // ColumnId[]
+  expandedRows={['1']}         // string[]
+  emptyState="No data found"   // ReactNode
+  footer={footerContent}       // ReactNode
+/>
+```
+
+### Tag
+Colored label/badge for categorization.
+```tsx
+import { Tag } from '@zvoove/unity-ui';
+
+<Tag
+  label="Active"               // string (required)
+  variant="solid"              // 'solid' | 'outlined' | 'ghost'
+  color="green"                // 'green' | 'yellow' | 'pink' | 'steel-blue' | 'error' | 'primary' | 'neutral'
+  tone="dark"                  // 'dark' | 'light' (only with variant='solid')
+  size="medium"                // 'large' | 'medium' | 'small'
+  icon="Check"                 // CommonIconNames
+/>
+```
+
+### Chip
+Interactive chip for filters, selections, and suggestions.
+```tsx
+import { Chip } from '@zvoove/unity-ui';
+
+<Chip
+  label="React"                // string (required)
+  type="filter"                // 'input' | 'filter' | 'assistive' | 'suggestion' | 'choice'
+  icon="Code"                  // CommonIconNames
+  variant="primary"            // 'primary' | 'secondary' | 'pending' | 'confirmed' | 'rejected' | 'skipped'
+  elevated={false}             // boolean
+  readonly={false}             // boolean
+  disabled={false}             // boolean
+  size="medium"                // 'medium' | 'large'
+  onDelete={handleDelete}      // () => void
+  showDropdownIcon={true}      // boolean
+  onToggleOpen={handleToggle}  // () => void
+/>
+```
+
+### Avatar & AvatarGroup
+User avatar display.
+```tsx
+import { Avatar, AvatarGroup } from '@zvoove/unity-ui';
+
+<Avatar
+  size="large"                 // ResponsiveType<'small' | 'medium' | 'large'>
+  type="initials"              // 'initials' | 'check' | 'avatar' | 'image'
+  name="John Doe"              // string
+  image="/path/to/photo.jpg"   // string (for type='image')
+  initialsAmount={2}           // 1 | 2
+  variant="round"              // 'round' | 'square'
+/>
+
+<AvatarGroup maxLength={3} total={10}>
+  <Avatar name="Alice" type="initials" />
+  <Avatar name="Bob" type="initials" />
+  <Avatar name="Charlie" type="initials" />
+</AvatarGroup>
+```
+
+### Badge
+Notification badge wrapper.
+```tsx
+import { Badge } from '@zvoove/unity-ui';
+
+<Badge
+  variant="primary"            // 'primary' | 'secondary'
+  content={5}                  // ReactNode
+  dot={false}                  // boolean
+>
+  <Icon name="Bell" />
+</Badge>
+```
+
+### Icon
+Phosphor icon renderer.
+```tsx
+import { Icon } from '@zvoove/unity-ui';
+
+<Icon
+  name="MagnifyingGlass"       // IconNames (Phosphor icon names)
+  size="lg"                    // '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default: 'lg')
+  color="on-surface"           // ForegroundColors
+  weight="regular"             // IconWeight
+  featured={false}             // boolean
+/>
+```
+
+### Skeleton
+Loading placeholder.
+```tsx
+import { Skeleton } from '@zvoove/unity-ui';
+
+<Skeleton
+  width={200}                  // number | string
+  height={20}                  // number | string
+  animation="pulse"            // 'pulse' | 'wave' | false (default: 'pulse')
+  borderRadius="xs"            // 'xs' | 'sm' | 'md' | 'lg' | 'full' (default: 'xs')
+/>
+```
+
+### ProgressIndicator
+Linear or circular progress indicator.
+```tsx
+import { ProgressIndicator } from '@zvoove/unity-ui';
+
+<ProgressIndicator
+  value={75}                   // number (0-100, default: 0)
+  variant="linear"             // 'linear' | 'circular' (default: 'linear')
+  indeterminate={false}        // boolean
+/>
+```
+
+### CodeBlock
+Code display with syntax highlighting.
+```tsx
+import { CodeBlock } from '@zvoove/unity-ui';
+
+<CodeBlock
+  code="const x = 42;"         // string (required)
+  filename="example.ts"        // string
+/>
+```
+
+---
+
+## NAVIGATION COMPONENTS
+
+### Tabs
+Tab navigation with optional panels.
+```tsx
+import { Tabs } from '@zvoove/unity-ui';
+
+<Tabs
+  items={[                     // TabItem[] (required)
+    { id: 'tab1', label: 'Overview', icon: 'House' },
+    { id: 'tab2', label: 'Details', hasActivity: true },
+    { id: 'tab3', label: 'Settings', icon: 'Gear', iconPosition: 'top' },
+  ]}
+  activeItem="tab1"            // string (required)
+  onChange={handleChange}       // (item: TabItem) => void
+  panels={[                    // Panel[]
+    { id: 'tab1', children: <div>Overview content</div> },
+    { id: 'tab2', children: <div>Details content</div> },
+  ]}
+  isSticky={false}             // boolean
+  hideBorder={false}           // boolean
+  itemsAlignment="left"        // 'left' | 'center' | 'right' | 'between' | 'around' | 'evenly'
+  linkComponent={Link}         // React.ElementType
+/>
+```
+
+### Breadcrumbs
+Navigation breadcrumb trail.
+```tsx
+import { Breadcrumbs } from '@zvoove/unity-ui';
+
+<Breadcrumbs
+  items={[                     // BreadcrumbItem[]
+    { label: 'Home', href: '/' },
+    { label: 'Products', href: '/products' },
+    { label: 'Details' },
+  ]}
+  linkComponent={Link}         // React.ElementType
+/>
+```
+
+### SideNavigation
+Collapsible sidebar navigation.
+```tsx
+import { SideNavigation } from '@zvoove/unity-ui';
+
+<SideNavigation
+  menuItems={[                 // MenuItem[] (required)
+    { id: 'home', label: 'Home', icon: 'House' },
+    { id: 'users', label: 'Users', icon: 'Users' },
+  ]}
+  utilityItems={[              // MenuItem[]
+    { id: 'settings', label: 'Settings', icon: 'Gear' },
+  ]}
+  activeItem="home"            // string
+  open={true}                  // boolean
+  onToggleOpen={handleToggle}  // (open: boolean) => void
+  onItemClick={handleClick}    // (item: MenuItem) => void
+  linkComponent={Link}         // React.ElementType
+/>
+```
+
+### Pagination
+Page navigation control.
+```tsx
+import { Pagination } from '@zvoove/unity-ui';
+
+<Pagination
+  currentPage={1}              // number (required)
+  totalPages={10}              // number (required)
+  onPageChange={handlePage}    // (page: number) => void (required)
+  rowsPerPage={20}             // 10 | 20 | 50 | 100 | 200
+  onRowsPerPageChange={handleRows}  // (rowsPerPage: RowsPerPage) => void
+  rowsPerPageLabel="Rows per page"   // string
+  pageOfPagesLabel="of"        // string
+  disabled={false}             // boolean
+/>
+```
+
+### TopBar
+Application top bar/header.
+```tsx
+import { TopBar } from '@zvoove/unity-ui';
+
+<TopBar
+  leftTopContent={<Logo />}     // ReactNode
+  rightTopContent={<Avatar />}  // ReactNode
+  leftBottomContent="Dashboard" // string | ReactNode
+  rightBottomContent={actions}  // ReactNode
+  subtitle="Overview"           // string
+  density="default"             // 'default' | '-2' | '-4'
+/>
+```
+
+---
+
+## FEEDBACK COMPONENTS
+
+### Dialog
+Modal dialog overlay. Use Dialog for modals — never create custom overlays.
+```tsx
+import { Dialog } from '@zvoove/unity-ui';
+
+<Dialog
+  open={isOpen}                // boolean (required)
+  onClose={handleClose}        // () => void (required)
+  size="md"                    // ResponsiveType<'sm' | 'md' | 'lg' | 'none' | 'fullscreen'>
+  closeOnBackdropClick={true}  // boolean
+  closeOnEsc={true}            // boolean
+  padding="md"                 // CardProps['padding'] — use "none" for edge-to-edge content
+  zIndex={20}                  // number
+>
+  <Typography variant="title" size="large">Dialog Title</Typography>
+  <Typography>Dialog content goes here.</Typography>
+  <Stack direction="row" gap="sm" justify="flex-end">
+    <Button variant="outlined" onClick={handleClose}>Cancel</Button>
+    <Button onClick={handleConfirm}>Confirm</Button>
+  </Stack>
+</Dialog>
+```
+
+Common patterns:
+```tsx
+// Responsive: fullscreen on mobile, centered modal on tablet+
+<Dialog
+  open={isOpen}
+  onClose={handleClose}
+  size={{ mobile: 'fullscreen', tablet: 'md' }}
+>
+  <Stack direction="column" gap="lg">
+    <Typography variant="title" size="large">Edit Profile</Typography>
+    <TextField label="Name" name="name" value={name} onChange={setName} />
+    <TextField label="Email" name="email" value={email} onChange={setEmail} />
+    <Stack direction="row" gap="sm" justify="flex-end">
+      <Button variant="outlined" onClick={handleClose}>Cancel</Button>
+      <Button variant="filled" onClick={handleSave}>Save</Button>
+    </Stack>
+  </Stack>
+</Dialog>
+
+// Confirmation dialog (small)
+<Dialog open={showConfirm} onClose={() => setShowConfirm(false)} size="sm">
+  <Stack direction="column" gap="md">
+    <Typography variant="title" size="medium">Delete item?</Typography>
+    <Typography variant="body" size="medium">This action cannot be undone.</Typography>
+    <Stack direction="row" gap="sm" justify="flex-end">
+      <Button variant="outlined" onClick={() => setShowConfirm(false)}>Cancel</Button>
+      <Button variant="negative" icon="delete" onClick={handleDelete}>Delete</Button>
+    </Stack>
+  </Stack>
+</Dialog>
+
+// Dialog with no padding (for full-width content like tables/images)
+<Dialog open={isOpen} onClose={handleClose} size="lg" padding="none">
+  <Table columns={columns} data={data} />
+</Dialog>
+```
+
+### Sheet
+Bottom or side sheet overlay. Use Sheet for slide-in panels — never create custom side panels.
+```tsx
+import { Sheet } from '@zvoove/unity-ui';
+
+<Sheet
+  open={isOpen}                // boolean (required)
+  onClose={handleClose}        // () => void (required)
+  title="Sheet Title"          // string
+  subTitle="Optional subtitle" // string
+  placement="bottom"           // 'bottom' | 'right' (default: 'bottom')
+  size="md"                    // 'sm' | 'md' | 'lg'
+  padding="lg"                 // SpacingKeys (default: 'lg'). Use "none" for edge-to-edge content
+  closeOnBackdropClick={true}  // boolean
+  closeOnEsc={false}           // boolean
+  showHandle={true}            // boolean
+  showCloseButton={false}      // boolean
+  showBackArrow={false}        // boolean
+  stickyHeader={true}          // boolean
+  stickyFooter={true}          // boolean
+  headerActions={actions}      // ReactNode
+  footerActions={buttons}      // ReactNode
+  // Right placement extras:
+  resizable={false}            // boolean
+  width={600}                  // number | string
+  minWidth={570}               // number | string
+  maxWidth={900}               // number | string
+  onResizeEnd={handleResize}   // (width: number) => void
+>
+  {children}
+</Sheet>
+```
+
+Common patterns:
+```tsx
+// Detail panel from the right
+<Sheet
+  open={isOpen}
+  onClose={handleClose}
+  title="User Details"
+  placement="right"
+  showCloseButton={true}
+  footerActions={
+    <Stack direction="row" gap="sm" justify="flex-end">
+      <Button variant="outlined" onClick={handleClose}>Cancel</Button>
+      <Button variant="filled" onClick={handleSave}>Save</Button>
+    </Stack>
+  }
+>
+  <Stack direction="column" gap="md">
+    <TextField label="Name" name="name" />
+    <TextField label="Email" name="email" />
+  </Stack>
+</Sheet>
+
+// Mobile bottom sheet for actions
+<Sheet
+  open={isOpen}
+  onClose={handleClose}
+  title="Sort by"
+  placement="bottom"
+  size="sm"
+  showHandle={true}
+>
+  <Stack direction="column" gap="xs">
+    <Button variant="text" onClick={() => sort('name')}>Name</Button>
+    <Button variant="text" onClick={() => sort('date')}>Date</Button>
+    <Button variant="text" onClick={() => sort('status')}>Status</Button>
+  </Stack>
+</Sheet>
+```
+
+### Snackbar
+Toast notification system. Requires `<Snackbar />` provider in your app tree.
+```tsx
+import { Snackbar, useSnackbar } from '@zvoove/unity-ui';
+
+// In your app root:
+<Snackbar />
+
+// In any component:
+const { addSnackbar } = useSnackbar();
+
+addSnackbar('Operation successful', {
+  variant: 'positive',          // 'default' | 'positive' | 'warning' | 'error' | 'subtle'
+  placement: 'top-right',       // 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  icon: 'Check',                // CommonIconNames
+  showCloseButton: true,        // boolean
+  actionLabel: 'Undo',          // string
+  onAction: handleUndo,         // (id: string) => void
+  onClose: handleClose,         // (id: string) => void
+  duration: 5000,               // number (ms)
+});
+```
+
+### InfoBox
+Inline informational message.
+```tsx
+import { InfoBox } from '@zvoove/unity-ui';
+
+<InfoBox
+  message="Your changes have been saved."  // string (required)
+  variant="positive"           // 'default' | 'positive' | 'warning' | 'error' | 'subtle' | 'neutral' | 'outlined'
+  icon="CheckCircle"           // CommonIconNames
+  elevated={true}              // boolean (default: true)
+/>
+```
+
+### ConfirmationCard
+Status card with actions.
+```tsx
+import { ConfirmationCard } from '@zvoove/unity-ui';
+
+<ConfirmationCard
+  title="Delete item?"          // string (required)
+  variant="warning"             // 'info' | 'success' | 'warning' | 'error'
+  icon="Warning"                // CommonIconNames
+  status="confirmed"            // 'confirmed' | 'rejected' | 'skipped'
+  statusLabel="Approved"        // string
+  actions={[                    // ConfirmationCardAction[]
+    { label: 'Cancel', variant: 'outlined', onClick: handleCancel },
+    { label: 'Delete', variant: 'negative', icon: 'Trash', onClick: handleDelete },
+  ]}
+>
+  This action cannot be undone.
+</ConfirmationCard>
+```
+
+### Tooltip
+Hover tooltip.
+```tsx
+import { Tooltip } from '@zvoove/unity-ui';
+
+<Tooltip
+  content="Helpful description"  // ReactNode (required)
+  placement="top"               // 'top' | 'bottom' | 'left' | 'right'
+  disabled={false}              // boolean
+  isOpen={undefined}            // boolean (controlled mode)
+>
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+---
+
+## COMPOUND COMPONENTS
+
+### Accordion
+Expandable accordion panels.
+```tsx
+import { Accordion } from '@zvoove/unity-ui';
+
+<Accordion
+  items={[                     // AccordionItem[] (required)
+    { id: '1', title: 'Section 1', supportingText: 'Details', children: <div>Content</div> },
+    { id: '2', title: 'Section 2', children: <div>Content</div>, disabled: true },
+  ]}
+  openItems={['1']}            // string | string[]
+  onToggle={handleToggle}      // (item: AccordionItem) => void
+  allowMultipleOpenItems={false}  // boolean
+/>
+```
+
+---
+
+## HOOKS
+
+### useBreakpoint
+Responsive breakpoint detection.
+```tsx
+import { useBreakpoint } from '@zvoove/unity-ui';
+
+const { currentBreakpoint, isBiggerThan, isSmallerThan, isBetween } = useBreakpoint();
+
+if (isBiggerThan('tablet')) { /* tablet and above */ }
+if (isSmallerThan('laptop')) { /* below laptop */ }
+if (isBetween('tablet', 'desktop')) { /* between tablet and desktop */ }
+```
+
+### useClickOutside
+Detect clicks outside a referenced element.
+```tsx
+import { useClickOutside } from '@zvoove/unity-ui';
+
+const ref = useRef(null);
+useClickOutside(ref, () => setOpen(false), isOpen);
+```
+
+---
+
+## SPACING SCALE
+
+Use these values for gap, padding, and margin props:
+- `none` = 0px
+- `xs2` = 4px
+- `xs` = 8px
+- `sm` = 12px
+- `md` = 16px
+- `lg` = 20px
+- `xl` = 24px
+- `xl2` = 32px
+- `xl3` = 40px
+- `xl4` = 48px
+- `xl5` = 64px
+- `xl6` = 80px
+- `xl7` = 96px
+
+---
+
+## ICON NAMES
+
+Unity UI uses its own semantic icon names (not raw Phosphor icon names). Pass them via `<Icon name="icon-name" />`.
+
+### Common Icons
+
+add, add-circle, add-file, agent, airplane, archive, arrow-back, arrow-bend, arrow-down, arrow-forward, arrow-left-right, arrow-up, article, attachment, automate, backspace, bank, bicycle, billing, binoculars, break, bus, calendar, calendar-blank, calendar-check, calendar-dot, calendar-x, camera, car, cart, cash-money, certificate, chat-bubble, chats, check, check-circle, checkbox, checkbox-empty, checkbox-indefinitely, checks, chevron-down, chevron-left, chevron-right, chevron-up, circle-notch, close, close-circle, clock-countdown, clock-person, cloud-download, cloud-upload, columns, copy, dark-mode, deactivate, delete, diagram-view, download, drag, edit, error, exclamation-mark, expand, expenses, face-id, file, filter, filters, first-page, folder, grid-view, hard-hat, help, hide, home, images, info, invoice, job, keyboard, knowledge, language, last-page, light-mode, list-view, location, location-pin, lock, menu, metadata, microphone, minus, more-horizontal, more-vertical, moped, navigation-arrow, note, notches, notifications, numpad, open-in-new-tab, order, organization, pause, phone, piggy-bank, plant, printer, privacy, qr-code, refresh, remark, save, search, send-message, settings, setup-time, shapes, show, sick, sidebar, sign-out, signature, skip-forward, smartphone, sparkle, star, start, stop, table, taxi, text-align-center, text-align-justify, text-align-left, text-align-right, text-t, time, time-sheet-download, time-sheet-upload, timer, train, translate, travel, unfold, upload, user, user-account, users, vacation, wallet, warning, wrench.
+
+### File Type Icons
+
+file-empty, file-pdf, file-folder, file-image, file-video, file-video-2, file-audio, file-code, file-document, file-spreadsheet, file-image-img, file-image-jpg, file-image-jpeg, file-image-png, file-image-webp, file-image-tiff, file-image-gif, file-image-svg, file-image-eps, file-document-pdf, file-document-doc, file-document-docx, file-document-txt, file-document-csv, file-document-xls, file-document-xlsx, file-document-ppt, file-document-pptx, file-design-fig, file-design-ai, file-design-psd, file-design-indd, file-design-aep, file-media-mp3, file-media-wav, file-media-mp4, file-media-mpeg, file-media-avi, file-media-mkv, file-development-html, file-development-css, file-development-rss, file-development-sql, file-development-js, file-development-json, file-development-java, file-development-xml, file-development-exe, file-development-dmg, file-archive-zip, file-archive-rar.
+
+Use `getIconForFileExtension(extension)` to resolve a file extension (e.g., "pdf") to its icon name automatically.
+
+---
+
+## EXAMPLE: Contact Form
+
+```tsx
+import {
+  Card,
+  Stack,
+  Typography,
+  TextField,
+  Textarea,
+  Select,
+  Checkbox,
+  Button,
+} from '@zvoove/unity-ui';
+
+function ContactForm() {
+  return (
+    <Card padding="xl" elevation={1} variant="outlined" maxWidth={600}>
+      <Stack direction="column" gap="lg">
+        <Typography variant="headline" size="medium" as="h2">
+          Contact Us
+        </Typography>
+
+        <Grid columns={{ mobile: 1, tablet: 2 }} gap="md">
+          <Grid.Item>
+            <TextField label="First name" name="firstName" required />
+          </Grid.Item>
+          <Grid.Item>
+            <TextField label="Last name" name="lastName" required />
+          </Grid.Item>
+        </Grid>
+
+        <TextField label="Email" name="email" type="email" icon="Envelope" required />
+
+        <Select
+          name="subject"
+          label="Subject"
+          options={[
+            { value: 'general', label: 'General inquiry' },
+            { value: 'support', label: 'Technical support' },
+            { value: 'billing', label: 'Billing' },
+          ]}
+        />
+
+        <Textarea placeholder="Your message..." maxLength={1000} rows={5} />
+
+        <Checkbox label="I agree to the privacy policy" name="privacy" />
+
+        <Stack direction="row" gap="sm" justify="flex-end">
+          <Button variant="outlined">Cancel</Button>
+          <Button variant="filled" icon="PaperPlaneRight">Send</Button>
+        </Stack>
+      </Stack>
+    </Card>
+  );
+}
+```
+
+---
+
+## RULES FOR AI AGENTS
+
+1. **Always import from `@zvoove/unity-ui`** - never recreate components that exist in this library
+2. **Use Stack and Grid for layout** - do not use Card, div, or CSS for layout. Stack is for rows/columns, Grid is for multi-column layouts
+3. **Card is a visual container, NOT a layout tool** - Card provides background, elevation, and border. Wrap layout content in Stack/Grid INSIDE a Card. Never use Card to arrange items
+4. **Use Typography for all text** - never use raw `<p>`, `<h1>`, `<span>` etc.
+5. **Use the spacing scale** for gap/padding/margin - never use arbitrary pixel values
+6. **Use Button variants** appropriately - primary actions: `filled`, secondary: `outlined`, destructive: `negative`, success: `positive`
+7. **Use TextField/Select/Checkbox/Radio for forms** - never create custom form inputs
+8. **Use Dialog for modals, Sheet for panels** - never create custom overlays
+9. **Use Snackbar for notifications** - never create custom toast systems
+10. **Use responsive props** when the UI should adapt to screen sizes. Values cascade up from smallest breakpoint. Common pattern: `{{ mobile: 'column', tablet: 'row' }}`
+11. **Card, Dialog, Sheet padding can be "none"** - use `padding="none"` for edge-to-edge content like images, tables, or dividers inside these components
+12. **Icons use semantic names** as strings (e.g., `"search"`, `"delete"`, `"edit"`) - never import Phosphor icon components directly