@mdigital_ui/ui 0.3.0 → 0.3.2

package/README.md

@@ -1,1050 +1,426 @@
 # @mdigital_ui/ui
 
-Modern React component library built with Tailwind CSS v4, designed for multi-brand support and maximum customization.
+Modern React component library built with Tailwind CSS v4, CVA, and Radix UI primitives.
 
 ## Features
 
-- **57 Components** - Comprehensive UI component library
-- **Tailwind CSS v4** - Modern utility-first CSS with OKLCH colors
-- **TypeScript** - Full type safety and IntelliSense
-- **Dark Mode** - Built-in dark mode support via `.dark` class
-- **Theme Presets** - Pre-built color schemes (Corporate, Vibrant, Minimal)
-- **CSS Variables** - Override any design token without rebuilding
-- **Tree-Shakeable** - Optimal bundle size with ESM
-- **Accessible** - WCAG 2.1 AA compliant
-- **React 19** - Modern React patterns (no forwardRef)
+- **Tailwind CSS v4** with OKLCH color system and CSS-first configuration
+- **Full TypeScript** support with exported types for every component
+- **Dark Mode** built-in via `.dark` class toggle
+- **Theme Presets** (Corporate, Vibrant, Minimal) with CSS variable overrides
+- **Tree-Shakeable** ESM with subpath imports
+- **Accessible** keyboard navigation, ARIA attributes, focus management, reduced-motion support
+- **ClassNames API** for granular styling of every component part
 
 ## Installation
 
 ```bash
-npm install @mdigital_ui/ui
-# or
 pnpm add @mdigital_ui/ui
+# or
+npm install @mdigital_ui/ui
 ```
 
 ### Peer Dependencies
 
-Required:
-```bash
-npm install react react-dom
-```
-
-Optional (for specific components):
 ```bash
-# For Carousel component
-npm install swiper
-
-# For Table component (advanced features)
-npm install @tanstack/react-table
-
-# For Chart components
-npm install recharts
-
-# For DatePicker component
-npm install react-datepicker
+pnpm add react react-dom tailwindcss
 ```
 
 ## Quick Start
 
 ### 1. Import Styles
 
-In your main entry point (e.g., `app/layout.tsx` or `src/main.tsx`):
-
 ```tsx
-// Required: Global styles and light theme
+// Required
 import '@mdigital_ui/ui/styles/global.css'
 import '@mdigital_ui/ui/styles/themes/light.css'
 
-// Optional: Dark mode support
+// Optional: dark mode
 import '@mdigital_ui/ui/styles/themes/dark.css'
-
-// Optional: Theme presets
-import '@mdigital_ui/ui/styles/themes/presets/corporate.css'
-import '@mdigital_ui/ui/styles/themes/presets/vibrant.css'
-import '@mdigital_ui/ui/styles/themes/presets/minimal.css'
 ```
 
 ### 2. Use Components
 
 ```tsx
-import { Button, Input, Card } from '@mdigital_ui/ui'
+import Button from '@mdigital_ui/ui/button'
+import Input from '@mdigital_ui/ui/input'
+import { Card, CardHeader, CardTitle, CardContent } from '@mdigital_ui/ui/card'
 
 function App() {
   return (
     <Card>
-      <Input label="Email" placeholder="Enter your email" />
-      <Button variant="solid" color="primary">
-        Submit
-      </Button>
+      <CardHeader>
+        <CardTitle>Sign In</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Input label="Email" placeholder="you@example.com" />
+        <Button color="primary" className="mt-4">Submit</Button>
+      </CardContent>
     </Card>
   )
 }
 ```
 
-## Customization with ClassNames
+### Import Patterns
 
-Every component in the UI kit supports fine-grained styling through the `classNames` prop. This allows you to override styles for individual component parts without modifying the entire component.
-
-### How ClassNames Work
+```tsx
+// Subpath imports (recommended, best tree-shaking)
+import Button from '@mdigital_ui/ui/button'
+import Select from '@mdigital_ui/ui/select'
+
+// Barrel import
+import { Button, Select, Input } from '@mdigital_ui/ui'
+
+// Type imports
+import type { ButtonProps, SelectProps } from '@mdigital_ui/ui'
+```
+
+---
+
+## Components
+
+### Form Inputs
+
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Input** | `input` | Text input with validation states, icons, clearable |
+| **FloatInput** | `float-input` | Floating label input |
+| **InputPassword** | `input-password` | Password input with visibility toggle |
+| **InputOTP** | `input-otp` | One-time password code input |
+| **InputGroup** | `input-group` | Input with prefix/suffix addons |
+| **NumberInput** | `number-input` | Numeric input with increment/decrement buttons |
+| **Textarea** | `textarea` | Multi-line text input with auto-resize |
+| **Select** | `select` | Searchable dropdown with virtualization |
+| **MultiSelect** | `multi-select` | Multiple selection with tags |
+| **Cascader** | `cascader` | Cascading multi-level selection |
+| **TreeSelect** | `tree-select` | Tree-based dropdown selection |
+| **DatePicker** | `date-picker` | Date, range, and time pickers |
+| **Upload** | `upload` | File upload (drag-drop, button, avatar variants) |
+| **Checkbox** | `checkbox` | Single checkbox |
+| **CheckboxGroup** | `checkbox-group` | Grouped checkboxes |
+| **Radio** | `radio` | Single radio button |
+| **RadioGroup** | `radio-group` | Grouped radio buttons |
+| **Switch** | `switch` | Toggle switch |
+| **Slider** | `slider` | Range slider |
+| **Rating** | `rating` | Star rating |
+| **Toggle** | `toggle` | Toggle button (pressed/unpressed) |
+| **ToggleGroup** | `toggle-group` | Grouped toggle buttons |
+
+### Form Utilities
 
-The `classNames` prop accepts an object where each key corresponds to a specific part of the component. Values are CSS class strings that are merged with the component's default classes using semantic class names.
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Form** | `form` | Form wrapper with react-hook-form + zod validation |
+| **Clipboard** | `clipboard` | Copy-to-clipboard with visual feedback |
 
-**Key Principles:**
+### Layout & Containers
 
-1. **Semantic Classes**: Each part uses a semantic class name in the format `{componentName}_{slot}` (e.g., `button_root`, `input_label`)
-2. **Data Attributes**: All parts include `data-slot` attributes for CSS targeting
-3. **Class Merging**: Custom classes are merged with default classes, allowing you to:
-   - Add Tailwind utilities
-   - Override specific properties
-   - Add state-based styles
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Button** | `button` | Button with solid, outline, soft, dashed, link, ghost variants |
+| **ButtonGroup** | `button-group` | Grouped buttons |
+| **Card** | `card` | Content card with header, body, footer, image sub-components |
+| **Grid** | `grid` | Responsive CSS grid layout |
+| **Divider** | `divider` | Horizontal/vertical content separator |
+| **ScrollArea** | `scroll-area` | Custom scrollbar container |
 
-### Basic Usage
+### Navigation
 
-```tsx
-import Button from '@mdigital_ui/ui/button'
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Tabs** | `tabs` | Tabbed content navigation |
+| **Breadcrumbs** | `breadcrumbs` | Hierarchical breadcrumb trail |
+| **Pagination** | `pagination` | Page navigation with page size control |
+| **Stepper** | `stepper` | Step progress indicator |
+| **Dropdown** | `dropdown` | Dropdown action menu |
+| **ContextMenu** | `context-menu` | Right-click context menu with submenus |
+| **Menubar** | `menubar` | Horizontal menu bar |
+| **NavigationMenu** | `navigation-menu` | Navigation with dropdown panels |
+| **Link** | `link` | Styled anchor element |
+| **Command** | `command` | Command palette / search (Cmd+K) |
 
-function App() {
-  return (
-    <Button
-      classNames={{
-        root: 'shadow-lg hover:shadow-xl',
-        icon: 'text-white',
-        content: 'font-bold uppercase',
-      }}
-    >
-      Click Me
-    </Button>
-  )
-}
-```
+### Overlays & Feedback
 
-### Targeting via Semantic Classes in CSS
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Modal** | `modal` | Dialog overlay with Radix primitives |
+| **Drawer** | `drawer` | Slide-in side panel |
+| **Tooltip** | `tooltip` | Hover information popup |
+| **Popover** | `popover` | Contextual popup with positioning |
+| **Notification** | `notification` | Inline alert/notification |
+| **Toast** | `toast` | Temporary toast notifications (Sonner) |
+| **FetchingOverlay** | `fetching-overlay` | Loading overlay |
+| **Progress** | `progress` | Progress bar (linear, circular, semicircle) |
+| **Spinner** | `spinner` | Loading spinner |
+| **Skeleton** | `skeleton` | Content loading placeholder |
+| **Empty** | `empty` | Empty state with icon, title, action |
 
-Use semantic class names in your CSS files:
+### Data Display
 
-```css
-/* Target the root button element */
-.button_root {
-  border-radius: 12px;
-  font-family: 'Inter', sans-serif;
-}
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Table** | `table` | Data table with TanStack Table (sorting, filtering, pagination, pinning, editing) |
+| **Tree** | `tree` | Hierarchical tree view with checkboxes |
+| **Descriptions** | `descriptions` | Key-value description list |
+| **Timeline** | `timeline` | Vertical timeline |
+| **Transfer** | `transfer` | Dual-list transfer |
+| **Carousel** | `carousel` | Content slider (Swiper) |
+| **Image** | `image` | Lazy-loaded image with blur placeholder |
+| **Collapse** | `collapse` | Collapsible content panel |
+| **Accordion** | `accordion` | Accordion panels (single/multiple) |
 
-/* Target button icon */
-.button_icon {
-  margin: 0 4px;
-}
+### Badges & Tags
 
-/* Combine with states */
-.button_root:hover {
-  transform: scale(1.05);
-}
-```
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **Badge** | `badge` | Status indicator label |
+| **Tag** | `tag` | Removable tag/chip with keyboard support |
+| **Avatar** | `avatar` | User avatar with image, fallback, status indicator |
+| **Kbd** | `kbd` | Keyboard key indicator |
+| **Ribbon** | `ribbon` | Corner ribbon overlay |
+
+### Theme
+
+| Component | Import | Description |
+|-----------|--------|-------------|
+| **ThemeProvider** | `theme` | Theme context with dark mode persistence |
+
+---
+
+## Common Props
+
+Most components share these variant props:
 
-### Using Data-Slot Attributes
+### `color`
 
-Target component parts using `data-slot` attributes:
+```
+"default" | "primary" | "secondary" | "accent" | "success" | "error" | "warning" | "info"
+```
 
-```css
-/* Target via data attribute (highest specificity) */
-[data-slot="root"] {
-  /* Styles */
-}
+### `size`
 
-[data-slot="content"] {
-  /* Styles */
-}
+```
+"xs" | "sm" | "md" | "lg"
 ```
 
-### Combining with Tailwind Classes
+### `variant`
 
-Mix custom Tailwind classes with component classNames:
+Varies per component. Common patterns:
 
-```tsx
-<Input
-  classNames={{
-    root: 'custom-wrapper',
-    input: 'bg-blue-50 text-blue-900 focus:ring-blue-500',
-    label: 'font-semibold text-blue-700',
-  }}
-/>
-```
+- **Button**: `"solid" | "outline" | "soft" | "dashed" | "link" | "ghost"`
+- **Card**: `"default" | "solid" | "outline" | "soft" | "ghost" | "elevated"`
+- **Input/Textarea**: `"outline" | "filled"`
+- **Notification**: `"default" | "solid" | "outline" | "soft"`
+- **Badge/Tag**: `"default" | "solid" | "outline" | "soft"`
 
-### TypeScript Support
+### Validation States
 
-Import type definitions for full IntelliSense:
+Form components support validation via boolean or string props:
 
 ```tsx
-import type { ButtonClassNames, InputClassNames, SelectClassNames } from '@mdigital_ui/ui'
+<Input error="Email is required" />
+<Input warning="Weak password" />
+<Input success />
+<Input info="We'll never share your email" />
+```
 
-const buttonClasses: ButtonClassNames = {
-  root: 'custom-root',
-  icon: 'custom-icon',
-  content: 'custom-content',
-  spinner: 'custom-spinner',
-}
+---
 
-<Button classNames={buttonClasses}>Submit</Button>
-```
+## Styling
 
-### ClassNames Reference
+### className (Root Element)
 
-Each component below documents all available `classNames` keys. Use these to target specific parts of the component for styling.
-
-#### Form Components
-
-**Input**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | input_root | Wrapper div containing label and input |
-| wrapper | input_wrapper | Input wrapper with positioning context |
-| label | input_label | Label element |
-| input | input_input | Input element |
-| leftIcon | input_leftIcon | Left icon container |
-| rightIcon | input_rightIcon | Right icon container |
-| clearButton | input_clearButton | Clear button element |
-| helper | input_helper | Helper/hint text |
-| error | input_error | Error message text |
-
-**InputPassword**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | inputPassword_root | Wrapper div |
-| wrapper | inputPassword_wrapper | Input wrapper with positioning |
-| label | inputPassword_label | Label element |
-| input | inputPassword_input | Password input element |
-| toggleButton | inputPassword_toggleButton | Show/hide toggle button |
-| toggleIcon | inputPassword_toggleIcon | Toggle icon element |
-| helper | inputPassword_helper | Helper text |
-| error | inputPassword_error | Error message text |
-
-**InputOTP**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | inputOTP_root | Root wrapper |
-| wrapper | inputOTP_wrapper | Input slots container |
-| label | inputOTP_label | Label element |
-| slot | inputOTP_slot | Individual OTP input slot |
-| slotActive | inputOTP_slotActive | Active/focused slot |
-| separator | inputOTP_separator | Separator between slots |
-| helper | inputOTP_helper | Helper text |
-
-**InputGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | inputGroup_root | Root wrapper |
-| addon | inputGroup_addon | Addon (prefix/suffix) element |
-| input | inputGroup_input | Input element |
-
-**Textarea**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | textarea_root | Wrapper div |
-| wrapper | textarea_wrapper | Textarea wrapper |
-| label | textarea_label | Label element |
-| textarea | textarea_textarea | Textarea element |
-| counter | textarea_counter | Character count display |
-| helper | textarea_helper | Helper text |
-| error | textarea_error | Error message |
-
-**Select**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | select_root | Root wrapper |
-| trigger | select_trigger | Dropdown trigger button |
-| triggerIcon | select_triggerIcon | Icon in trigger |
-| dropdown | select_dropdown | Dropdown menu container |
-| search | select_search | Search input in dropdown |
-| option | select_option | Individual option item |
-| optionSelected | select_optionSelected | Selected option |
-| group | select_group | Option group container |
-| groupLabel | select_groupLabel | Group label |
-| empty | select_empty | Empty state message |
-| label | select_label | Form label |
-| helper | select_helper | Helper text |
-
-**MultiSelect**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | multiSelect_root | Root wrapper |
-| trigger | multiSelect_trigger | Trigger button |
-| tag | multiSelect_tag | Selected item tag |
-| tagRemove | multiSelect_tagRemove | Remove button in tag |
-| dropdown | multiSelect_dropdown | Dropdown menu |
-| option | multiSelect_option | Option item |
-| optionSelected | multiSelect_optionSelected | Selected option |
-| selectAll | multiSelect_selectAll | Select all checkbox |
-| empty | multiSelect_empty | Empty state |
-| label | multiSelect_label | Form label |
-| helper | multiSelect_helper | Helper text |
-
-**Checkbox**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | checkbox_root | Root wrapper |
-| checkbox | checkbox_checkbox | Checkbox element |
-| indicator | checkbox_indicator | Checkmark indicator |
-| label | checkbox_label | Label text |
-| description | checkbox_description | Description text |
-
-**CheckboxGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | checkboxGroup_root | Root wrapper |
-| label | checkboxGroup_label | Group label |
-| group | checkboxGroup_group | Items container |
-| item | checkboxGroup_item | Individual checkbox |
-| helper | checkboxGroup_helper | Helper text |
-| error | checkboxGroup_error | Error message |
-
-**Radio**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | radio_root | Root wrapper |
-| radio | radio_radio | Radio button element |
-| indicator | radio_indicator | Selection indicator |
-| label | radio_label | Label text |
-| description | radio_description | Description text |
-
-**RadioGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | radioGroup_root | Root wrapper |
-| label | radioGroup_label | Group label |
-| group | radioGroup_group | Items container |
-| item | radioGroup_item | Individual radio |
-| helper | radioGroup_helper | Helper text |
-| error | radioGroup_error | Error message |
-
-**Switch**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | switch_root | Root wrapper |
-| track | switch_track | Track/background |
-| thumb | switch_thumb | Animated thumb |
-| label | switch_label | Label text |
-| description | switch_description | Description text |
-
-**Slider**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | slider_root | Root wrapper |
-| track | slider_track | Track background |
-| range | slider_range | Active range fill |
-| thumb | slider_thumb | Draggable thumb |
-| label | slider_label | Label text |
-| value | slider_value | Value display |
-
-**Rating**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | rating_root | Root wrapper |
-| star | rating_star | Star element |
-| starFilled | rating_starFilled | Filled star |
-| label | rating_label | Label text |
-
-**DatePicker**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | datePicker_root | Root wrapper |
-| trigger | datePicker_trigger | Input trigger |
-| calendar | datePicker_calendar | Calendar container |
-| header | datePicker_header | Calendar header |
-| navigation | datePicker_navigation | Navigation controls |
-| day | datePicker_day | Day cell |
-| daySelected | datePicker_daySelected | Selected day |
-| dayToday | datePicker_dayToday | Today indicator |
-
-**Upload**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | upload_root | Root wrapper |
-| dropzone | upload_dropzone | Drag-drop area |
-| input | upload_input | File input |
-| icon | upload_icon | Icon element |
-| text | upload_text | Text content |
-| hint | upload_hint | Hint/instructions |
-| fileList | upload_fileList | Files list container |
-| fileItem | upload_fileItem | Individual file item |
-| progress | upload_progress | Upload progress bar |
-
-#### Layout & Action Components
-
-**Button**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | button_root | Root button element |
-| icon | button_icon | Icon container |
-| spinner | button_spinner | Loading spinner container |
-| content | button_content | Button text content |
-
-**ButtonGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | buttonGroup_root | Root wrapper |
-| button | buttonGroup_button | Individual button |
-
-**Card**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | card_root | Root card element |
-| header | card_header | Header section |
-| title | card_title | Title element |
-| description | card_description | Description text |
-| content | card_content | Main content area |
-| footer | card_footer | Footer section |
-| action | card_action | Action buttons area |
-| image | card_image | Image element |
-
-**Modal**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | modal_root | Root wrapper |
-| overlay | modal_overlay | Backdrop overlay |
-| content | modal_content | Modal content box |
-| header | modal_header | Header section |
-| title | modal_title | Title element |
-| description | modal_description | Description text |
-| body | modal_body | Body content |
-| footer | modal_footer | Footer section |
-| closeButton | modal_closeButton | Close button |
-
-**Drawer**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | drawer_root | Root wrapper |
-| overlay | drawer_overlay | Backdrop overlay |
-| content | drawer_content | Drawer content box |
-| header | drawer_header | Header section |
-| title | drawer_title | Title element |
-| description | drawer_description | Description text |
-| body | drawer_body | Body content |
-| footer | drawer_footer | Footer section |
-| handle | drawer_handle | Drag handle (mobile) |
-| closeButton | drawer_closeButton | Close button |
-
-**Accordion**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | accordion_root | Root wrapper |
-| item | accordion_item | Individual accordion item |
-| trigger | accordion_trigger | Item trigger/header |
-| content | accordion_content | Item content |
-| icon | accordion_icon | Expand/collapse icon |
-
-**Tabs**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | tabs_root | Root wrapper |
-| list | tabs_list | Tab list container |
-| tab | tabs_tab | Individual tab |
-| tabActive | tabs_tabActive | Active tab |
-| panel | tabs_panel | Tab panel content |
-
-**Collapse**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | collapse_root | Root wrapper |
-| header | collapse_header | Header/trigger |
-| content | collapse_content | Collapsible content |
-| icon | collapse_icon | Toggle icon |
-
-**Toggle**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | toggle_root | Root toggle element |
-
-**ToggleGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | toggleGroup_root | Root wrapper |
-| item | toggleGroup_item | Individual toggle item |
-
-#### Navigation Components
-
-**Dropdown**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | dropdown_root | Root wrapper |
-| trigger | dropdown_trigger | Trigger button |
-| menu | dropdown_menu | Menu container |
-| item | dropdown_item | Menu item |
-| itemIcon | dropdown_itemIcon | Item icon |
-| itemLabel | dropdown_itemLabel | Item label |
-| divider | dropdown_divider | Divider line |
-
-**ContextMenu**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | contextMenu_root | Root wrapper |
-| content | contextMenu_content | Menu content |
-| item | contextMenu_item | Menu item |
-| itemIcon | contextMenu_itemIcon | Item icon |
-| itemLabel | contextMenu_itemLabel | Item label |
-| divider | contextMenu_divider | Divider line |
-| submenu | contextMenu_submenu | Submenu container |
-
-**Breadcrumbs**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | breadcrumbs_root | Root wrapper |
-| list | breadcrumbs_list | Breadcrumb list |
-| item | breadcrumbs_item | Individual breadcrumb |
-| link | breadcrumbs_link | Link element |
-| separator | breadcrumbs_separator | Separator between items |
-| current | breadcrumbs_current | Current page indicator |
-
-**Pagination**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | pagination_root | Root wrapper |
-| list | pagination_list | Items list |
-| item | pagination_item | Individual page item |
-| button | pagination_button | Page button |
-| buttonActive | pagination_buttonActive | Active page button |
-| ellipsis | pagination_ellipsis | Ellipsis indicator |
-| info | pagination_info | Info text |
-
-**Stepper**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | stepper_root | Root wrapper |
-| step | stepper_step | Individual step |
-| stepActive | stepper_stepActive | Active step |
-| stepCompleted | stepper_stepCompleted | Completed step |
-| icon | stepper_icon | Step icon |
-| label | stepper_label | Step label |
-| description | stepper_description | Step description |
-| connector | stepper_connector | Connector line between steps |
-
-#### Feedback Components
-
-**Notification**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | notification_root | Root wrapper |
-| icon | notification_icon | Icon element |
-| content | notification_content | Content container |
-| title | notification_title | Title text |
-| description | notification_description | Description text |
-| action | notification_action | Action button |
-| closeButton | notification_closeButton | Close button |
-
-**Tooltip**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | tooltip_root | Root wrapper |
-| trigger | tooltip_trigger | Trigger element |
-| content | tooltip_content | Tooltip content |
-| arrow | tooltip_arrow | Arrow element |
-
-**Popover**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | popover_root | Root wrapper |
-| trigger | popover_trigger | Trigger element |
-| content | popover_content | Popover content |
-| arrow | popover_arrow | Arrow element |
-| closeButton | popover_closeButton | Close button |
-
-**Progress**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | progress_root | Root wrapper |
-| track | progress_track | Background track |
-| fill | progress_fill | Progress fill |
-| label | progress_label | Label text |
-| value | progress_value | Value display |
-
-#### Data Display Components
-
-**Table**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | table_root | Root wrapper |
-| wrapper | table_wrapper | Table container |
-| header | table_header | Table head |
-| headerRow | table_headerRow | Header row |
-| headerCell | table_headerCell | Header cell |
-| body | table_body | Table body |
-| row | table_row | Table row |
-| cell | table_cell | Table cell |
-| footer | table_footer | Table footer |
-| pagination | table_pagination | Pagination area |
-| empty | table_empty | Empty state |
-| skeleton | table_skeleton | Loading skeleton |
-| actions | table_actions | Actions column |
-
-**Tree**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | tree_root | Root wrapper |
-| node | tree_node | Tree node |
-| nodeContent | tree_nodeContent | Node content |
-| icon | tree_icon | Node icon |
-| expandIcon | tree_expandIcon | Expand/collapse icon |
-| label | tree_label | Node label |
-| children | tree_children | Children container |
-
-**TreeSelect**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | treeSelect_root | Root wrapper |
-| trigger | treeSelect_trigger | Trigger button |
-| dropdown | treeSelect_dropdown | Dropdown menu |
-| tree | treeSelect_tree | Tree container |
-| node | treeSelect_node | Tree node |
-| checkbox | treeSelect_checkbox | Node checkbox |
-| label | treeSelect_label | Node label |
-
-**Tag**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | tag_root | Root wrapper |
-| content | tag_content | Tag content |
-| closeButton | tag_closeButton | Remove button |
-
-**Avatar**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | avatar_root | Root element |
-| image | avatar_image | Image element |
-| fallback | avatar_fallback | Fallback text |
-| status | avatar_status | Status indicator |
-
-**AvatarGroup**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | avatarGroup_root | Root wrapper |
-| overflow | avatarGroup_overflow | Overflow indicator |
-
-**Descriptions**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | descriptions_root | Root wrapper |
-| item | descriptions_item | Description item |
-| label | descriptions_label | Label text |
-| content | descriptions_content | Content text |
-
-**Empty**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | empty_root | Root wrapper |
-| icon | empty_icon | Icon element |
-| title | empty_title | Title text |
-| description | empty_description | Description text |
-| action | empty_action | Action buttons |
-
-**Image**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | image_root | Root wrapper |
-| image | image_image | Image element |
-| placeholder | image_placeholder | Placeholder |
-| error | image_error | Error state |
-
-**Carousel**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | carousel_root | Root wrapper |
-| wrapper | carousel_wrapper | Slides wrapper |
-| slide | carousel_slide | Individual slide |
-| navigation | carousel_navigation | Navigation area |
-| navButton | carousel_navButton | Navigation button |
-| pagination | carousel_pagination | Pagination area |
-| dot | carousel_dot | Pagination dot |
-| dotActive | carousel_dotActive | Active dot |
-
-**Command**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | command_root | Root wrapper |
-| input | command_input | Command input |
-| inputIcon | command_inputIcon | Input icon |
-| list | command_list | Commands list |
-| empty | command_empty | Empty state |
-| group | command_group | Command group |
-| groupLabel | command_groupLabel | Group label |
-| item | command_item | Command item |
-| itemIcon | command_itemIcon | Item icon |
-| shortcut | command_shortcut | Keyboard shortcut |
-
-**Cascader**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | cascader_root | Root wrapper |
-| trigger | cascader_trigger | Trigger button |
-| dropdown | cascader_dropdown | Dropdown menu |
-| menu | cascader_menu | Menu column |
-| option | cascader_option | Menu option |
-
-**Transfer**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | transfer_root | Root wrapper |
-| list | transfer_list | Individual list |
-| header | transfer_header | List header |
-| search | transfer_search | Search input |
-| item | transfer_item | Transfer item |
-| actions | transfer_actions | Action buttons |
-
-**Clipboard**
-
-| Key | Semantic Class | Purpose |
-|-----|----------------|---------|
-| root | clipboard_root | Root wrapper |
-| input | clipboard_input | Hidden input |
-| button | clipboard_button | Copy button |
-
-#### Single-Element Components
-
-Single-element components don't have a `classNames` prop. Instead, pass classes directly via the `className` prop or target via semantic CSS classes:
-
-| Component | Semantic Class |
-|-----------|----------------|
-| Badge | badge_root |
-| Divider | divider_root |
-| Kbd | kbd_root |
-| Skeleton | skeleton_root |
-| Spinner | spinner_root |
-| Ribbon | ribbon_root |
-| Grid | grid_root |
-| FetchingOverlay | fetchingOverlay_root |
-| Chart | chart_root |
+Every component accepts `className` for the root element:
 
 ```tsx
-// Direct className
-<Badge className="custom-badge-style">New</Badge>
-
-// Or target via CSS
-<style>
-  .badge_root {
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-  }
-</style>
+<Button className="shadow-lg my-4">Submit</Button>
 ```
 
-### Advanced Examples
+### classNames (Component Parts)
 
-**Theme-based customization:**
+Most components expose a `classNames` prop for styling internal parts:
 
 ```tsx
-const isDark = useTheme()
-
 <Button
   classNames={{
-    root: isDark ? 'dark:bg-slate-800 dark:text-white' : 'bg-white',
-    content: 'font-semibold uppercase tracking-wide',
+    root: 'shadow-lg',
+    icon: 'text-white',
+    content: 'font-bold uppercase',
+    spinner: 'opacity-50',
   }}
 >
-  Themed Button
+  Submit
 </Button>
 ```
 
-**Combining multiple approaches:**
+### Semantic CSS Classes
 
-```tsx
-<Input
-  className="mx-4 my-2"
-  classNames={{
-    root: 'my-custom-wrapper',
-    input: 'border-2 border-blue-300 focus:border-blue-600',
-    label: 'text-blue-900 font-bold',
-  }}
-  style={{ maxWidth: '400px' }}
-/>
+Every component part has a semantic class in the format `{component}_{slot}`:
+
+```css
+/* Target in CSS */
+.button_root { border-radius: 12px; }
+.input_label { font-weight: 700; }
+.card_header { padding: 2rem; }
+.modal_overlay { backdrop-filter: blur(8px); }
 ```
 
-**Component composition with consistent styling:**
+### data-slot Attributes
 
-```tsx
-const formClasses = {
-  label: 'text-sm font-semibold text-gray-700',
-  helper: 'text-xs text-gray-500 mt-1',
-  error: 'text-xs text-red-600 mt-1',
-}
+All component parts include `data-slot` attributes for CSS targeting:
 
-<div>
-  <Input classNames={formClasses} label="Email" />
-  <Input classNames={formClasses} label="Password" type="password" />
-  <Button classNames={{ content: 'font-bold' }}>Submit</Button>
-</div>
+```css
+[data-slot="root"] { /* ... */ }
+[data-slot="content"] { /* ... */ }
 ```
 
-## Available Components
-
-### Form Components (16)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Input** | Text input with validation states | `@mdigital_ui/ui/input` |
-| **InputGroup** | Input with addons (icons, buttons) | `@mdigital_ui/ui/input-group` |
-| **InputPassword** | Password input with visibility toggle | `@mdigital_ui/ui/input-password` |
-| **InputOTP** | One-time password input | `@mdigital_ui/ui/input-otp` |
-| **Textarea** | Multi-line text input | `@mdigital_ui/ui/textarea` |
-| **Select** | Dropdown selection | `@mdigital_ui/ui/select` |
-| **MultiSelect** | Multiple selection dropdown | `@mdigital_ui/ui/multi-select` |
-| **Checkbox** | Toggle option | `@mdigital_ui/ui/checkbox` |
-| **CheckboxGroup** | Grouped checkboxes | `@mdigital_ui/ui/checkbox-group` |
-| **Radio** | Single selection | `@mdigital_ui/ui/radio` |
-| **RadioGroup** | Grouped radio buttons | `@mdigital_ui/ui/radio-group` |
-| **Switch** | Toggle switch | `@mdigital_ui/ui/switch` |
-| **Toggle** | Toggle button | `@mdigital_ui/ui/toggle` |
-| **Slider** | Range slider | `@mdigital_ui/ui/slider` |
-| **Rating** | Star rating | `@mdigital_ui/ui/rating` |
-| **DatePicker** | Date selection (requires react-datepicker) | `@mdigital_ui/ui/date-picker` |
-| **Upload** | File upload | `@mdigital_ui/ui/upload` |
-
-### Display Components (13)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Card** | Content container | `@mdigital_ui/ui/card` |
-| **Badge** | Status indicator | `@mdigital_ui/ui/badge` |
-| **Tag** | Label chip | `@mdigital_ui/ui/tag` |
-| **Avatar** | User profile image | `@mdigital_ui/ui/avatar` |
-| **Skeleton** | Loading placeholder | `@mdigital_ui/ui/skeleton` |
-| **Empty** | Empty state | `@mdigital_ui/ui/empty` |
-| **Spinner** | Loading indicator | `@mdigital_ui/ui/spinner` |
-| **Progress** | Progress bar | `@mdigital_ui/ui/progress` |
-| **Ribbon** | Corner ribbon | `@mdigital_ui/ui/ribbon` |
-| **Divider** | Content separator | `@mdigital_ui/ui/divider` |
-| **Kbd** | Keyboard key | `@mdigital_ui/ui/kbd` |
-| **Descriptions** | Key-value display | `@mdigital_ui/ui/descriptions` |
-| **Image** | Optimized image with blur loading | `@mdigital_ui/ui/image` |
-
-### Navigation Components (6)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Tabs** | Tabbed navigation | `@mdigital_ui/ui/tabs` |
-| **Breadcrumbs** | Hierarchical navigation | `@mdigital_ui/ui/breadcrumbs` |
-| **Pagination** | Page navigation | `@mdigital_ui/ui/pagination` |
-| **Dropdown** | Dropdown menu | `@mdigital_ui/ui/dropdown` |
-| **Stepper** | Step progress indicator | `@mdigital_ui/ui/stepper` |
-
-### Feedback Components (6)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Modal** | Dialog overlay | `@mdigital_ui/ui/modal` |
-| **Drawer** | Side panel | `@mdigital_ui/ui/drawer` |
-| **Tooltip** | Hover information | `@mdigital_ui/ui/tooltip` |
-| **Popover** | Contextual popup | `@mdigital_ui/ui/popover` |
-| **Notification** | Toast messages | `@mdigital_ui/ui/notification` |
-| **FetchingOverlay** | Loading overlay | `@mdigital_ui/ui/fetching-overlay` |
-
-### Data Display Components (8)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Table** | Data table with sorting/filtering | `@mdigital_ui/ui/table` |
-| **Tree** | Hierarchical tree view | `@mdigital_ui/ui/tree` |
-| **TreeSelect** | Tree selection dropdown | `@mdigital_ui/ui/tree-select` |
-| **Transfer** | Dual list selector | `@mdigital_ui/ui/transfer` |
-| **Cascader** | Cascading selection | `@mdigital_ui/ui/cascader` |
-| **Collapse** | Collapsible panels | `@mdigital_ui/ui/collapse` |
-| **Accordion** | Accordion panels | `@mdigital_ui/ui/accordion` |
-
-### Layout Components (4)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Button** | Button with variants | `@mdigital_ui/ui/button` |
-| **ButtonGroup** | Grouped buttons | `@mdigital_ui/ui/button-group` |
-| **ToggleGroup** | Toggle button group | `@mdigital_ui/ui/toggle-group` |
-| **Grid** | Responsive grid system | `@mdigital_ui/ui/grid` |
-
-### Advanced Components (5)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **Chart** | LineChart, BarChart, AreaChart, PieChart | `@mdigital_ui/ui/chart` |
-| **Carousel** | Image/content slider (requires Swiper) | `@mdigital_ui/ui/carousel` |
-| **Command** | Command palette | `@mdigital_ui/ui/command` |
-| **ContextMenu** | Right-click menu | `@mdigital_ui/ui/context-menu` |
-| **Clipboard** | Copy to clipboard | `@mdigital_ui/ui/clipboard` |
-
-### Utilities (1)
-
-| Component | Description | Import |
-|-----------|-------------|--------|
-| **ThemeProvider** | Theme management with persistence | `@mdigital_ui/ui/theme` |
-
-## Import Patterns
-
-### Subpath Imports (Recommended for tree-shaking)
+### ClassNames Reference
 
-```tsx
-import Button from '@mdigital_ui/ui/button'
-import Input from '@mdigital_ui/ui/input'
-import Table from '@mdigital_ui/ui/table'
-```
+Every `classNames` key maps to a semantic class `{component}_{key}` and a `data-slot="{key}"` attribute.
 
-### Named Imports
+<details>
+<summary><strong>Form Components</strong></summary>
 
-```tsx
-import { Button, Input, Select } from '@mdigital_ui/ui'
-```
+| Component | classNames keys |
+|-----------|----------------|
+| **Input** | `root`, `wrapper`, `label`, `input`, `leftIcon`, `rightIcon`, `clearButton`, `helper`, `error` |
+| **FloatInput** | `root`, `wrapper`, `label`, `input`, `helper`, `error` |
+| **InputPassword** | `root`, `wrapper`, `label`, `input`, `toggleButton`, `toggleIcon`, `helper`, `error` |
+| **InputOTP** | `root`, `wrapper`, `label`, `slot`, `slotActive`, `helper` |
+| **InputGroup** | `root`, `addon`, `input` |
+| **NumberInput** | `root`, `wrapper`, `label`, `input`, `increment`, `decrement`, `helper`, `error` |
+| **Textarea** | `root`, `wrapper`, `label`, `textarea`, `counter`, `helper`, `error` |
+| **Select** | `root`, `trigger`, `triggerIcon`, `search`, `dropdown`, `option`, `optionSelected`, `group`, `groupLabel`, `empty`, `label`, `helper` |
+| **MultiSelect** | `root`, `trigger`, `tag`, `tagRemove`, `dropdown`, `option`, `optionSelected`, `selectAll`, `empty`, `label`, `helper` |
+| **Cascader** | `root`, `trigger`, `dropdown`, `menu`, `option` |
+| **TreeSelect** | `root`, `trigger`, `dropdown`, `tree`, `node`, `checkbox`, `label` |
+| **DatePicker** | `root`, `trigger`, `calendar`, `header`, `navigation`, `day`, `daySelected`, `dayToday` |
+| **Upload** | `root`, `dropzone`, `input`, `icon`, `text`, `hint`, `fileList`, `fileItem`, `progress` |
+| **Checkbox** | `root`, `checkbox`, `indicator`, `label`, `description` |
+| **CheckboxGroup** | `root`, `label`, `group`, `item`, `helper`, `error` |
+| **Radio** | `root`, `radio`, `indicator`, `label`, `description` |
+| **RadioGroup** | `root`, `label`, `group`, `item`, `helper`, `error` |
+| **Switch** | `root`, `track`, `thumb`, `label`, `description` |
+| **Slider** | `root`, `track`, `range`, `thumb`, `label`, `value` |
+| **Rating** | `root`, `star`, `starFilled`, `label` |
+| **Toggle** | `root` |
+| **ToggleGroup** | `root`, `item` |
+| **Clipboard** | `root`, `input`, `button` |
+| **Form** | `root`, `field`, `label`, `control`, `description`, `message` |
+
+</details>
+
+<details>
+<summary><strong>Layout & Navigation Components</strong></summary>
+
+| Component | classNames keys |
+|-----------|----------------|
+| **Button** | `root`, `icon`, `leftIcon`, `rightIcon`, `content`, `spinner` |
+| **ButtonGroup** | `root`, `button` |
+| **Card** | `root`, `header`, `title`, `description`, `content`, `footer`, `action`, `image` |
+| **Tabs** | `root`, `list`, `tab`, `tabActive`, `panel` |
+| **Accordion** | `root`, `item`, `trigger`, `content`, `icon` |
+| **Collapse** | `root`, `header`, `content`, `icon` |
+| **Breadcrumbs** | `root`, `list`, `item`, `link`, `separator`, `current` |
+| **Pagination** | `root`, `list`, `item`, `button`, `buttonActive`, `ellipsis`, `info` |
+| **Stepper** | `root`, `step`, `stepActive`, `stepCompleted`, `icon`, `label`, `description`, `connector` |
+| **Dropdown** | `root`, `trigger`, `menu`, `item`, `itemIcon`, `itemLabel`, `divider` |
+| **ContextMenu** | `root`, `content`, `item`, `itemIcon`, `itemLabel`, `divider`, `submenu` |
+| **Menubar** | `root`, `menu`, `trigger`, `content`, `item`, `separator` |
+| **NavigationMenu** | `root`, `list`, `item`, `trigger`, `link`, `content` |
+| **Link** | `root` |
+| **Command** | `root`, `input`, `inputIcon`, `list`, `empty`, `group`, `groupLabel`, `item`, `itemIcon`, `shortcut` |
+| **ScrollArea** | `root`, `viewport`, `scrollbar`, `thumb` |
+
+</details>
+
+<details>
+<summary><strong>Overlay & Feedback Components</strong></summary>
+
+| Component | classNames keys |
+|-----------|----------------|
+| **Modal** | `root`, `overlay`, `content`, `header`, `title`, `description`, `body`, `footer`, `closeButton` |
+| **Drawer** | `root`, `overlay`, `content`, `header`, `title`, `description`, `body`, `footer`, `handle`, `closeButton` |
+| **Tooltip** | `root`, `trigger`, `content`, `arrow` |
+| **Popover** | `content` |
+| **Notification** | `root`, `icon`, `content`, `title`, `description`, `action`, `closeButton` |
+| **Toast** | `root`, `title`, `description`, `action`, `closeButton` |
+| **Progress** | `root`, `track`, `fill`, `label`, `value` |
+| **Empty** | `root`, `icon`, `title`, `description`, `action` |
 
-### Type Imports
+</details>
 
-```tsx
-import type { ButtonProps, InputProps } from '@mdigital_ui/ui'
-```
+<details>
+<summary><strong>Data Display Components</strong></summary>
+
+| Component | classNames keys |
+|-----------|----------------|
+| **Table** | `root`, `wrapper`, `header`, `headerRow`, `headerCell`, `body`, `row`, `cell`, `footer`, `pagination`, `empty`, `skeleton`, `actions` |
+| **Tree** | `root`, `node`, `nodeContent`, `icon`, `expandIcon`, `label` |
+| **Descriptions** | `root`, `item`, `label`, `content` |
+| **Timeline** | `root`, `item`, `dot`, `connector`, `content`, `title`, `description` |
+| **Transfer** | `root`, `list`, `header`, `search`, `item`, `actions` |
+| **Carousel** | `root`, `wrapper`, `slide`, `navigation`, `navButton`, `pagination`, `dot`, `dotActive` |
+| **Image** | `root`, `image`, `placeholder`, `error` |
+| **Avatar** | `root`, `image`, `fallback`, `status` |
+| **AvatarGroup** | `root`, `overflow` |
+| **Tag** | `root`, `content`, `closeButton` |
+
+</details>
+
+**Single-element components** (use `className` directly): Badge, Divider, Kbd, Skeleton, Spinner, Ribbon, Grid, FetchingOverlay
+
+---
 
 ## Theming
 
 ### Dark Mode
 
-Enable dark mode by adding the `dark` class to your `<html>` element:
+Add the `dark` class to `<html>`:
 
 ```tsx
 <html className={isDark ? 'dark' : ''}>
-  <body>{children}</body>
-</html>
 ```
 
-All components automatically adapt via CSS variables.
+All components adapt automatically via CSS variables.
 
 ### Theme Presets
 
-Pre-built color schemes for quick brand customization:
-
-| Preset | Style | Use Case |
-|--------|-------|----------|
-| `corporate` | Professional navy blue | Enterprise, dashboards |
-| `vibrant` | Bold purple/magenta | Creative apps, consumer products |
-| `minimal` | Muted grayscale | Content-focused, reading interfaces |
-
-**Usage:**
-
 ```tsx
-// 1. Import preset CSS
 import '@mdigital_ui/ui/styles/themes/presets/corporate.css'
+// or vibrant.css, minimal.css
 
-// 2. Apply via data-theme attribute on <html>
 <html data-theme="corporate">
-  <body>{children}</body>
-</html>
-```
-
-**Combine with dark mode:**
-
-```tsx
-<html className="dark" data-theme="vibrant">
-  <body>{children}</body>
-</html>
 ```
 
-**Dynamic switching:**
+| Preset | Style |
+|--------|-------|
+| `corporate` | Professional navy blue |
+| `vibrant` | Bold purple/magenta |
+| `minimal` | Muted grayscale |
 
-```tsx
-import '@mdigital_ui/ui/styles/themes/presets/corporate.css'
-import '@mdigital_ui/ui/styles/themes/presets/vibrant.css'
-import '@mdigital_ui/ui/styles/themes/presets/minimal.css'
-
-function App() {
-  const [preset, setPreset] = useState<'corporate' | 'vibrant' | 'minimal'>('corporate')
-
-  useEffect(() => {
-    document.documentElement.setAttribute('data-theme', preset)
-  }, [preset])
-
-  return (
-    <Select
-      value={preset}
-      onChange={(e) => setPreset(e.target.value)}
-      options={[
-        { value: 'corporate', label: 'Corporate' },
-        { value: 'vibrant', label: 'Vibrant' },
-        { value: 'minimal', label: 'Minimal' },
-      ]}
-    />
-  )
-}
-```
+Combine with dark mode: `<html className="dark" data-theme="vibrant">`
 
 ### ThemeProvider
 
-For full theme management with persistence and SSR support:
-
 ```tsx
-import { ThemeProvider, useTheme } from '@mdigital_ui/ui'
-
-function App() {
-  return (
-    <ThemeProvider defaultTheme="system" storageKey="my-app-theme">
-      <YourApp />
-    </ThemeProvider>
-  )
-}
+import { ThemeProvider, useTheme } from '@mdigital_ui/ui/theme'
 
-function ThemeToggle() {
-  const { theme, setTheme, resolvedTheme } = useTheme()
+<ThemeProvider defaultTheme="system" storageKey="my-app-theme">
+  <App />
+</ThemeProvider>
 
-  return (
-    <button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
-      {resolvedTheme === 'dark' ? '☀️' : '🌙'}
-    </button>
-  )
-}
+// In any component:
+const { theme, setTheme, resolvedTheme } = useTheme()
 ```
 
 ### Custom CSS Variables
 
-Override any design token in your CSS:
+Override any design token after the UI kit styles:
 
 ```css
 :root {
-  /* Brand Colors */
+  /* Brand Colors (OKLCH) */
   --color-primary: oklch(0.55 0.22 270);
   --color-primary-hover: oklch(0.50 0.24 270);
   --color-accent: oklch(0.75 0.18 45);
@@ -1052,135 +428,339 @@ Override any design token in your CSS:
   /* Component Sizing */
   --button-height-md: 2.5rem;
   --input-height-md: 2.5rem;
-  --radius-md: 0.5rem;
 
   /* Typography */
   --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
 }
 ```
 
-Import after UI Kit styles:
+<details>
+<summary><strong>All CSS Variables</strong></summary>
 
-```tsx
-import '@mdigital_ui/ui/styles/global.css'
-import '@mdigital_ui/ui/styles/themes/light.css'
-import './your-theme.css'  // Your overrides
+**Colors**
 ```
-
-### Available CSS Variables
-
-#### Colors
-```css
-/* Brand */
---color-primary, --color-primary-hover, --color-primary-active, --color-primary-foreground
---color-secondary, --color-secondary-hover, --color-secondary-active, --color-secondary-foreground
---color-accent, --color-accent-hover, --color-accent-active, --color-accent-foreground
-
-/* Semantic */
---color-success, --color-error, --color-warning, --color-info (with hover/active variants)
-
-/* Surfaces */
---color-background, --color-background-secondary, --color-surface, --color-card
+--color-primary / -hover / -active / -foreground
+--color-secondary / -hover / -active / -foreground
+--color-accent / -hover / -active / -foreground
+--color-success / -hover / -active / -foreground
+--color-error / -hover / -active / -foreground
+--color-warning / -hover / -active / -foreground
+--color-info / -hover / -active / -foreground
+--color-background / -secondary
+--color-surface, --color-card, --color-card-foreground
 --color-border, --color-border-primary
-
-/* Text */
 --color-text-primary, --color-text-secondary, --color-text-muted
-
-/* Grayscale */
 --color-gray-50 through --color-gray-950
 ```
 
-#### Sizing
-```css
-/* Buttons */
+**Sizing**
+```
 --button-height-xs/sm/md/lg
 --button-padding-x-xs/sm/md/lg
-
-/* Inputs */
 --input-height-xs/sm/md/lg
 --input-padding-x-xs/sm/md/lg
-
-/* Switch */
+--select-height-xs/sm/md/lg
+--select-padding-x-xs/sm/md/lg
 --switch-width-xs/sm/md/lg/xl
 --switch-height-xs/sm/md/lg/xl
+--textarea-min-height-xs/sm/md/lg
+--textarea-padding-xs/sm/md/lg
+```
 
-/* Spacing */
---spacing-0 through --spacing-12
+**Effects**
+```
+--radius-none / -sm / -md / -lg / -xl / -full
+--shadow-sm / -md / -lg / -xl / -2xl
+--transition-fast / -base / -slow
+--z-dropdown / -sticky / -modal / -popover / -tooltip
 ```
 
-#### Effects
-```css
-/* Border Radius */
---radius-none, --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-full
+</details>
+
+---
+
+## Component Examples
 
-/* Shadows */
---shadow-sm, --shadow-md, --shadow-lg, --shadow-xl, --shadow-2xl
+### Button
 
-/* Transitions */
---transition-fast, --transition-base, --transition-slow
+```tsx
+import Button from '@mdigital_ui/ui/button'
 
-/* Z-Index */
---z-dropdown, --z-sticky, --z-modal, --z-popover, --z-tooltip
+<Button variant="solid" color="primary" size="md">Click me</Button>
+<Button variant="outline" color="error">Delete</Button>
+<Button variant="ghost" loading loadingText="Saving...">Save</Button>
+<Button icon={<Plus />} iconOnly aria-label="Add item" />
 ```
 
-## External Dependencies
+**Props**: `variant`, `color`, `size`, `shape` (`rounded` | `pill` | `square`), `loading`, `loadingText`, `loadingPosition`, `icon`, `iconPlacement`, `leftIcon`, `rightIcon`, `fullWidth`, `iconOnly`
 
-Some components require additional setup:
+### Input
 
-### Carousel (Swiper)
 ```tsx
-npm install swiper
+import Input from '@mdigital_ui/ui/input'
+
+<Input label="Email" placeholder="you@example.com" />
+<Input variant="filled" leftIcon={<Search />} clearable onClear={() => {}} />
+<Input error="Required" required />
+<Input loading showCount maxLength={100} />
+```
+
+**Props**: `variant`, `size`, `label`, `error`, `warning`, `info`, `success`, `helperText`, `messagePosition`, `leftIcon`, `rightIcon`, `clearable`, `onClear`, `loading`, `maxLength`, `showCount`, `fullWidth`
 
-// Import CSS in your entry file
-import 'swiper/css'
-import 'swiper/css/pagination'
-import 'swiper/css/navigation'
+### Select
+
+```tsx
+import Select from '@mdigital_ui/ui/select'
+
+<Select
+  label="Country"
+  placeholder="Choose..."
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' },
+    { value: 'de', label: 'Germany', group: 'Europe' },
+  ]}
+  value={value}
+  onChange={setValue}
+  clearable
+/>
 ```
 
-### DatePicker (react-datepicker)
+**Props**: `size`, `label`, `options`, `placeholder`, `value`, `defaultValue`, `onChange`, `clearable`, `loading`, `disabled`, `fullWidth`, `error`, `warning`, `info`, `success`, `helperText`, `virtualizeThreshold`, `maxDropdownHeight`
+
+### Table
+
 ```tsx
-npm install react-datepicker
+import Table from '@mdigital_ui/ui/table'
+
+<Table
+  data={users}
+  columns={[
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+    { accessorKey: 'role', header: 'Role' },
+  ]}
+  enableSorting
+  enablePagination
+  enableRowSelection
+  pageSize={10}
+  color="primary"
+  variant="outline"
+  striped
+  hoverable
+/>
 ```
 
-### Table (TanStack Table)
+**Props**: `data`, `columns`, `variant` (`outline` | `line` | `minimal`), `color`, `size`, `striped`, `hoverable`, `bordered`, `enableSorting`, `enableFiltering`, `enablePagination`, `enableRowSelection`, `enableColumnPinning`, `pageSize`, `onRowClick`
+
+### Modal
+
 ```tsx
-npm install @tanstack/react-table
+import Modal, { ModalContent, ModalHeader, ModalTitle, ModalFooter } from '@mdigital_ui/ui/modal'
+import Button from '@mdigital_ui/ui/button'
+
+<Modal open={open} onOpenChange={setOpen}>
+  <ModalContent size="md">
+    <ModalHeader>
+      <ModalTitle>Confirm Delete</ModalTitle>
+    </ModalHeader>
+    <div className="p-4">Are you sure?</div>
+    <ModalFooter>
+      <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button color="error" onClick={handleDelete}>Delete</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
 ```
 
-### Charts (Recharts)
+### Card
+
 ```tsx
-npm install recharts
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@mdigital_ui/ui/card'
+
+<Card variant="elevated" hoverable>
+  <CardHeader>
+    <CardTitle>Dashboard</CardTitle>
+    <CardDescription>Overview of your metrics</CardDescription>
+  </CardHeader>
+  <CardContent>Charts and data here</CardContent>
+  <CardFooter>
+    <Button variant="ghost">View Details</Button>
+  </CardFooter>
+</Card>
 ```
 
-## TypeScript
+**Props**: `variant`, `color`, `size`, `shadow`, `hoverable`, `clickable`, `bordered`, `loading`
 
-Full TypeScript support:
+### Drawer
 
 ```tsx
-import type { ButtonProps, ButtonColor, ButtonVariant } from '@mdigital_ui/ui'
+import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerBody } from '@mdigital_ui/ui/drawer'
+
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button>Open Panel</Button>
+  </DrawerTrigger>
+  <DrawerContent side="right" size="md">
+    <DrawerHeader>
+      <DrawerTitle>Settings</DrawerTitle>
+    </DrawerHeader>
+    <DrawerBody>Content here</DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+### Tabs
 
-const MyButton: React.FC<ButtonProps> = (props) => {
-  return <Button {...props} />
+```tsx
+import Tabs from '@mdigital_ui/ui/tabs'
+
+<Tabs
+  items={[
+    { key: 'overview', label: 'Overview', content: <Overview /> },
+    { key: 'settings', label: 'Settings', content: <Settings /> },
+    { key: 'billing', label: 'Billing', content: <Billing />, disabled: true },
+  ]}
+  variant="underline"
+  color="primary"
+/>
+```
+
+**Props**: `items`, `variant` (`underline` | `pills` | `enclosed` | `lifted`), `color`, `size`, `defaultValue`, `value`, `onChange`, `orientation`
+
+### Form (react-hook-form + zod)
+
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from '@mdigital_ui/ui/form'
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+
+const schema = z.object({ email: z.string().email() })
+
+function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema) })
+
+  return (
+    <Form form={form} onSubmit={(data) => console.log(data)}>
+      <FormField name="email" control={form.control} render={({ field }) => (
+        <FormItem>
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <Input {...field} />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )} />
+    </Form>
+  )
 }
 ```
 
+### Toast
+
+```tsx
+import { ToastProvider, useToast } from '@mdigital_ui/ui/toast'
+
+// Wrap your app
+<ToastProvider position="top-right">
+  <App />
+</ToastProvider>
+
+// Use anywhere
+const { toast } = useToast()
+toast({ title: 'Saved', description: 'Changes saved successfully', variant: 'success' })
+```
+
+### Command Palette
+
+```tsx
+import { Command, CommandInput, CommandList, CommandGroup, CommandItem } from '@mdigital_ui/ui/command'
+
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandGroup heading="Actions">
+      <CommandItem onSelect={() => {}}>Create new file</CommandItem>
+      <CommandItem onSelect={() => {}}>Open settings</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Upload
+
+```tsx
+import Upload from '@mdigital_ui/ui/upload'
+
+<Upload
+  variant="dragger"
+  accept="image/*"
+  maxSize={5 * 1024 * 1024}
+  maxCount={3}
+  onChange={(files) => console.log(files)}
+  color="primary"
+/>
+```
+
+**Props**: `variant` (`dragger` | `button` | `avatar`), `accept`, `maxSize`, `maxCount`, `multiple`, `disabled`, `onChange`, `onRemove`, `color`, `size`
+
+### Tree
+
+```tsx
+import Tree from '@mdigital_ui/ui/tree'
+
+<Tree
+  data={[
+    { key: '1', label: 'Documents', children: [
+      { key: '1-1', label: 'Resume.pdf', isLeaf: true },
+      { key: '1-2', label: 'Cover Letter.docx', isLeaf: true },
+    ]},
+  ]}
+  checkable
+  defaultExpandAll
+  onCheck={(keys, info) => console.log(keys)}
+/>
+```
+
+### Progress
+
+```tsx
+import Progress from '@mdigital_ui/ui/progress'
+
+<Progress value={65} color="primary" size="md" showValue />
+<Progress type="circular" value={80} color="success" />
+<Progress type="semicircle" value={45} color="warning" />
+```
+
+---
+
+## TypeScript
+
+All components export their props and classNames types:
+
+```tsx
+import type { ButtonProps, ButtonClassNames, ButtonVariant, ButtonColor } from '@mdigital_ui/ui'
+import type { TableProps, TableClassNames } from '@mdigital_ui/ui'
+import type { InputProps, SelectProps, ModalClassNames } from '@mdigital_ui/ui'
+```
+
+---
+
 ## Accessibility
 
-All components follow WCAG 2.1 AA standards:
+- Keyboard navigation on all interactive components
+- ARIA roles, labels, and live regions
+- Focus rings with `focus-visible` (no outline on mouse click)
+- `prefers-reduced-motion` respected globally (all animations disabled)
+- Color contrast following WCAG 2.1 AA
 
-- Keyboard navigation
-- Screen reader support
-- Focus indicators
-- ARIA attributes
-- Color contrast compliance
+---
 
 ## Browser Support
 
-- Chrome (latest 2 versions)
-- Firefox (latest 2 versions)
-- Safari (latest 2 versions)
-- Edge (latest 2 versions)
+Chrome, Firefox, Safari, Edge (latest 2 versions)
 
 ## License
 
-MIT © MDigital
+MIT