@vertesia/ui 1.2.0 → 1.4.0-dev.20260615.042549Z

package/llms.txt

@@ -3,612 +3,515 @@
 > React component library for building Vertesia UI plugins and applications.
 > This file documents component APIs and usage patterns for AI assistants.
 
-## Installation
+## Reference URLs
 
-```bash
-npm install @vertesia/ui
-# or
-pnpm add @vertesia/ui
-```
+- Visual style guide: https://design.vertesiahq.com
+- Markdown component guide: https://design.vertesiahq.com/components.md
+- LLM reference: https://design.vertesiahq.com/llms.txt
 
-## Import Paths
+# @vertesia/ui Component Reference
 
-```tsx
-// Core components (buttons, cards, inputs, modals, tabs)
-import { Button, Card, Input, VModal, VTabs } from '@vertesia/ui/core';
+> Markdown rendition of the Vertesia UI style guide for LLMs and text-first clients.
+> Visual style guide: https://design.vertesiahq.com
 
-// Hooks (data fetching, toasts)
-import { useFetch, useToast } from '@vertesia/ui/core';
+Use this file when generating React UI for Vertesia apps or plugins. Prefer `@vertesia/ui`
+components over local duplicates, and use semantic color classes instead of hardcoded colors.
 
-// Router (navigation, nested routing for plugins)
-import { useNavigate, useParams, NavLink, NestedRouterProvider } from '@vertesia/ui/router';
+# Import Paths
 
-// Session (authentication, Vertesia client access)
+```tsx
+import { Button, Input, Modal, SelectBox, Tabs } from '@vertesia/ui/core';
+import { FullHeightLayout, SidebarItem } from '@vertesia/ui/layout';
+import { GenericPageNavHeader, ModernAgentConversation } from '@vertesia/ui/features';
+import { NavLink, useLocation, useNavigate } from '@vertesia/ui/router';
 import { useUserSession } from '@vertesia/ui/session';
+```
 
-// Layout components (sidebar, full-height containers)
-import { Sidebar, SidebarSection, SidebarItem, useSidebarToggle, FullHeightLayout } from '@vertesia/ui/layout';
+# Catalog
+
+## Classes
+
+- [Semantic](https://design.vertesiahq.com/semantic)
+- [Background](https://design.vertesiahq.com/classes/background)
+- [Text](https://design.vertesiahq.com/classes/text)
+- [Border & Ring](https://design.vertesiahq.com/classes/border)
+- [Icons](https://design.vertesiahq.com/classes/icons)
+
+## Components
+
+- [Heading](https://design.vertesiahq.com/components/heading)
+- [Buttons](https://design.vertesiahq.com/components/buttons)
+- [Badges](https://design.vertesiahq.com/components/badges)
+- [Dot Badges](https://design.vertesiahq.com/components/dotBadges)
+- [Message Box](https://design.vertesiahq.com/components/messageBox)
+- [Modal](https://design.vertesiahq.com/components/modal)
+- [Confirm Modal](https://design.vertesiahq.com/components/confirmModal)
+- [Delete Modal](https://design.vertesiahq.com/components/deleteModal)
+- [Filter](https://design.vertesiahq.com/components/filter)
+- [Tabs](https://design.vertesiahq.com/components/tabs)
+- [Tooltips](https://design.vertesiahq.com/components/tooltips)
+- [Switch](https://design.vertesiahq.com/components/switch)
+- [Side Panel](https://design.vertesiahq.com/components/sidePanel)
+- [SelectBox](https://design.vertesiahq.com/components/selectBox)
+- [Overlay](https://design.vertesiahq.com/components/overlay)
+- [Breadcrumbs](https://design.vertesiahq.com/components/breadcrumb)
+- [Monaco](https://design.vertesiahq.com/components/monaco)
+- [Card](https://design.vertesiahq.com/components/card)
+- [Checkbox](https://design.vertesiahq.com/components/checkbox)
+- [Collapsible](https://design.vertesiahq.com/components/collapsible)
+- [Command](https://design.vertesiahq.com/components/command)
+- [Dropdown](https://design.vertesiahq.com/components/dropdown)
+- [Label](https://design.vertesiahq.com/components/label)
+- [Panel](https://design.vertesiahq.com/components/panel)
+- [Popover](https://design.vertesiahq.com/components/popover)
+- [Radio Group](https://design.vertesiahq.com/components/radioGroup)
+- [Resizeable](https://design.vertesiahq.com/components/resizeable)
+- [Separator](https://design.vertesiahq.com/components/separator)
+- [Text](https://design.vertesiahq.com/components/text)
+- [Theme](https://design.vertesiahq.com/components/theme)
+
+## Layout & Structure
+
+- [Avatar](https://design.vertesiahq.com/components/avatar)
+- [Center](https://design.vertesiahq.com/components/center)
+- [Divider](https://design.vertesiahq.com/components/divider)
+- [Link](https://design.vertesiahq.com/components/link)
+- [Portal](https://design.vertesiahq.com/components/portal)
+- [Spinner](https://design.vertesiahq.com/components/spinner)
+
+## Forms
+
+- [FormItem](https://design.vertesiahq.com/components/formItem)
+- [Inputs](https://design.vertesiahq.com/components/inputs)
+- [Textarea](https://design.vertesiahq.com/components/textarea)
+- [ComboBox](https://design.vertesiahq.com/components/comboBox)
+- [InputList](https://design.vertesiahq.com/components/inputList)
+- [MenuList](https://design.vertesiahq.com/components/menuList)
+- [NumberInput](https://design.vertesiahq.com/components/numberInput)
+- [SelectList](https://design.vertesiahq.com/components/selectList)
+- [TagsInput](https://design.vertesiahq.com/components/tagsInput)
+
+# Component Guidance
 
-// Feature components (headers, navigation, agent conversation)
-import { GenericPageNavHeader, ModernAgentConversation } from '@vertesia/ui/features';
+## Button
 
-// Shell (app wrapper with auth, routing, sidebar)
-import { VertesiaShell, StandaloneApp } from '@vertesia/ui/shell';
-```
+Primary action primitive with Vertesia variants, loading state, disabled state, and tooltip support.
 
----
+- Route: https://design.vertesiahq.com/components/buttons
+- Import path: `@vertesia/ui/core`
+- Exports: `Button`, `CopyButton`, `buttonVariants`
 
-# Component API Reference
+### Use When
 
-## Input (Simplified API)
+- Use for commands, submissions, toolbar actions, and navigational actions that behave like buttons.
+- Use `variant="destructive"` only for dangerous or irreversible actions.
+- Use icon-size buttons with lucide icons for compact toolbars.
 
-**IMPORTANT:** Input passes the value directly to onChange, NOT an event object.
+### Notes
 
-```tsx
-interface InputProps {
-  value?: string;
-  onChange?: (value: string) => void;  // Value directly, not event!
-  placeholder?: string;
-  disabled?: boolean;
-  clearable?: boolean;  // Shows X button to clear (default: true)
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  variant?: 'default' | 'unstyled' | 'noPadding' | 'legacy';
-}
-
-// Usage - pass setState directly
-<Input value={name} onChange={setName} />
-
-// Or with transformation
-<Input value={name} onChange={(value) => setName(value.trim())} />
-
-// WRONG - this will NOT work:
-<Input onChange={(e) => setName(e.target.value)} />  // ❌ Error!
-```
+- `alt` or `title` wraps the button in `VTooltip`.
+- `isDisabled` and `isLoading` both disable interaction; `isLoading` also renders a spinner.
 
-## Textarea (Standard React API)
+### Button Props
 
-Textarea uses standard React event handling.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | 'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'unstyled' | 'primary' | Visual treatment. |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon' | 'md' | Control dimensions and text size. |
+| asChild | boolean | false | Render the child via Radix Slot. |
+| alt | string | - | Tooltip text. |
+| isDisabled | boolean | false | Disable interaction. |
+| isLoading | boolean | false | Show spinner and disable interaction. |
+| className | string | - | Additional Tailwind classes. |
+| children | React.ReactNode | - | Rendered child content. |
 
-```tsx
-// Standard React event object
-<Textarea
-  value={description}
-  onChange={(e) => setDescription(e.target.value)}
-/>
-```
+### CopyButton Props
 
-## Button
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| content * | string | - | Text copied to the clipboard. |
+| alt | string | - | Tooltip text; defaults to localized copy text. |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'icon' | - | Button size. |
+
+### Example
 
 ```tsx
-interface ButtonProps {
-  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
-  size?: 'default' | 'sm' | 'lg' | 'icon';
-  disabled?: boolean;
-  onClick?: () => void;
-  children: React.ReactNode;
-}
-
-<Button onClick={handleClick}>Click Me</Button>
-<Button variant="outline" size="sm">Secondary</Button>
-<Button variant="destructive">Delete</Button>
+import { Button } from '@vertesia/ui/core';
+
+<Button variant="primary" isLoading={saving} onClick={save}>
+  Save
+</Button>
 ```
 
-## Card Components
+## Input
 
-```tsx
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@vertesia/ui/core';
-
-<Card>
-  <CardHeader>
-    <CardTitle>Title</CardTitle>
-    <CardDescription>Optional description</CardDescription>
-  </CardHeader>
-  <CardContent>
-    Main content here
-  </CardContent>
-  <CardFooter>
-    <Button>Action</Button>
-  </CardFooter>
-</Card>
-```
+Single-line text input with a simplified value-based `onChange` callback.
 
-## VModal (Modal Dialog)
+- Route: https://design.vertesiahq.com/components/inputs
+- Import path: `@vertesia/ui/core`
+- Exports: `Input`
 
-```tsx
-import { VModal, VModalTitle, VModalBody, VModalFooter } from '@vertesia/ui/core';
-
-interface VModalProps {
-  isOpen: boolean;
-  onClose: () => void;
-  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
-}
-
-<VModal isOpen={open} onClose={() => setOpen(false)} size="md">
-  <VModalTitle description="Optional subtitle">
-    Modal Title
-  </VModalTitle>
-  <VModalBody>
-    <div className="space-y-4">
-      <Input value={name} onChange={setName} />
-    </div>
-  </VModalBody>
-  <VModalFooter>
-    <Button onClick={handleSubmit}>Submit</Button>
-    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
-  </VModalFooter>
-</VModal>
-```
+### Use When
 
-**Note:** VModalFooter uses `flex-row-reverse`, so primary button should be first in code but appears on the right.
+- Use for compact string fields in forms, filters, and search inputs.
+- Pass state setters directly because `onChange` receives the next value, not a DOM event.
 
-## VTabs (Tabbed Interface)
+### Notes
 
-```tsx
-import { VTabs, VTabsBar, VTabsPanel } from '@vertesia/ui/core';
-
-<VTabs
-  defaultValue="tab1"
-  tabs={[
-    { name: 'tab1', label: 'First Tab', content: <Tab1Content /> },
-    { name: 'tab2', label: 'Second Tab', content: <Tab2Content /> },
-    { name: 'tab3', label: 'Third Tab', content: <Tab3Content /> },
-  ]}
->
-  <VTabsBar />
-  <VTabsPanel />
-</VTabs>
-
-// With controlled value
-const [tab, setTab] = useState('tab1');
-<VTabs value={tab} onValueChange={setTab} tabs={[...]}>
-```
+- Textarea intentionally uses standard React change events; do not copy Input handling to Textarea.
 
-## Label
+### Input Props
 
-```tsx
-<Label htmlFor="input-id">Field Label</Label>
-<Input id="input-id" value={value} onChange={setValue} />
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | - | Current input value. |
+| onChange | (value: string) => void | - | Called with the next value. |
+| placeholder | string | - | Placeholder text. |
+| disabled | boolean | - | Disable editing. |
+| clearable | boolean | - | Show a clear button when populated. |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Input size. |
+| variant | 'default' \| 'unstyled' \| 'noPadding' \| 'legacy' | 'default' | Visual treatment. |
 
-## Badge
+### Example
 
 ```tsx
-import { Badge } from '@vertesia/ui/core';
+const [name, setName] = useState('');
 
-<Badge variant="default">Default</Badge>
-<Badge variant="secondary">Secondary</Badge>
-<Badge variant="destructive">Error</Badge>
-<Badge variant="outline">Outline</Badge>
+<Input value={name} onChange={setName} placeholder="Name" />
 ```
 
-## Spinner & ErrorBox
+## Textarea
 
-```tsx
-import { Spinner, ErrorBox } from '@vertesia/ui/core';
+Multi-line text control using standard React textarea event handling.
 
-// Loading state
-if (isLoading) return <Spinner />;
+- Route: https://design.vertesiahq.com/components/textarea
+- Import path: `@vertesia/ui/core`
+- Exports: `Textarea`
 
-// Error state
-if (error) return <ErrorBox>{error.message}</ErrorBox>;
-```
+### Use When
+
+- Use for descriptions, prompts, comments, and other multi-line text.
 
-## Table
+### Notes
+
+- Unlike `Input`, `Textarea` passes a React change event to `onChange`.
+
+### Textarea Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | - | Current value. |
+| onChange | (event: React.ChangeEvent<HTMLTextAreaElement>) => void | - | Standard React textarea change handler. |
+| placeholder | string | - | Placeholder text. |
+| disabled | boolean | - | Disable editing. |
+
+### Example
 
 ```tsx
-import { Table, TBody, THead, Th, Tr, Td } from '@vertesia/ui/core';
-
-<Table>
-  <THead>
-    <Tr>
-      <Th>Name</Th>
-      <Th>Value</Th>
-    </Tr>
-  </THead>
-  <TBody>
-    {items.map(item => (
-      <Tr key={item.id}>
-        <Td>{item.name}</Td>
-        <Td>{item.value}</Td>
-      </Tr>
-    ))}
-  </TBody>
-</Table>
+<Textarea value={notes} onChange={(event) => setNotes(event.target.value)} />
 ```
 
----
+## FormItem
+
+Field wrapper for labels, required indicators, and help tooltips.
 
-# Hooks
+- Route: https://design.vertesiahq.com/components/formItem
+- Import path: `@vertesia/ui/core`
+- Exports: `FormItem`
 
-## useFetch
+### Use When
 
-Data fetching hook with loading, error, and refetch support.
+- Use around most labeled fields in create/edit forms.
+- Use `description` instead of loose helper paragraphs when a tooltip is enough.
+
+### FormItem Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| label * | React.ReactNode | - | Field label. |
+| required | boolean | - | Render required marker. |
+| description | React.ReactNode | - | Help tooltip content. |
+| direction | 'column' \| 'row' | 'column' | Label/control layout. |
+| disabled | boolean | - | Dim the label. |
+| className | string | - | Additional Tailwind classes. |
+| children | React.ReactNode | - | Rendered child content. |
+
+### Example
 
 ```tsx
-import { useFetch } from '@vertesia/ui/core';
-
-const { data, isLoading, error, refetch } = useFetch(
-  async () => {
-    return await client.store.collections.list();
-  },
-  [dependency1, dependency2]  // Refetch when dependencies change
-);
-
-// With options
-const { data } = useFetch(
-  fetchFn,
-  [deps],
-  {
-    onSuccess: (data) => console.log('Loaded', data),
-    onError: (err) => console.error('Failed', err),
-  }
-);
+<FormItem label="Name" required description="Visible to users">
+  <Input value={name} onChange={setName} />
+</FormItem>
 ```
 
-## useToast
+## Modal
 
-Show toast notifications.
+Accessible overlay dialog for focused tasks and forms.
 
-```tsx
-import { useToast } from '@vertesia/ui/core';
+- Route: https://design.vertesiahq.com/components/modal
+- Import path: `@vertesia/ui/core`
+- Exports: `Modal`, `ModalTitle`, `ModalBody`, `ModalFooter`
 
-const toast = useToast();
+### Use When
 
-// Success toast
-toast({ title: 'Success', description: 'Item created' });
+- Use for short create/edit flows, confirmations with custom content, and focused secondary tasks.
+- Use `disableCloseOnClickOutside` for forms with unsaved user input.
 
-// Error toast
-toast({ title: 'Error', description: error.message, variant: 'destructive' });
-```
+### Modal Props
 
-## useUserSession
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| isOpen * | boolean | - | Whether the modal is visible. |
+| onClose * | () => void | - | Called when the user dismisses the modal. |
+| size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Modal width. |
+| disableCloseOnClickOutside | boolean | - | Prevent accidental close from overlay click. |
+| noCloseButton | boolean | - | Hide the close button. |
+| allowOverflow | boolean | - | Allow content to overflow modal bounds. |
 
-Access authenticated user and Vertesia client.
+### ModalFooter Props
 
-```tsx
-import { useUserSession } from '@vertesia/ui/session';
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| align | 'left' \| 'center' \| 'right' | 'right' | Footer action alignment. |
+| className | string | - | Additional Tailwind classes. |
+| children | React.ReactNode | - | Rendered child content. |
 
-const { client, user, project } = useUserSession();
+### Example
 
-// client is the Vertesia API client
-const collections = await client.store.collections.list();
+```tsx
+<Modal isOpen={open} onClose={onClose} size="lg" disableCloseOnClickOutside>
+  <ModalTitle>Edit item</ModalTitle>
+  <ModalBody>...</ModalBody>
+  <ModalFooter>
+    <Button variant="outline" onClick={onClose}>Cancel</Button>
+    <Button onClick={save}>Save</Button>
+  </ModalFooter>
+</Modal>
 ```
 
----
+## ConfirmModal
 
-# Router
+Confirmation dialog for actions that need explicit user consent.
 
-## NestedRouterProvider
+- Route: https://design.vertesiahq.com/components/confirmModal
+- Import path: `@vertesia/ui/core`
+- Exports: `ConfirmModal`
 
-For plugin routing (nested within host app router).
+### Use When
 
-```tsx
-import { NestedRouterProvider } from '@vertesia/ui/router';
+- Use for consequential actions when a simple confirmation is enough.
 
-const routes = [
-  { path: '/', Component: HomePage },
-  { path: '/items/:id', Component: ItemPage },
-  { path: '*', Component: NotFound },
-];
+### ConfirmModal Props
 
-<NestedRouterProvider routes={routes} index="/" />
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| isOpen * | boolean | - | Whether the dialog is visible. |
+| title * | React.ReactNode | - | Dialog title. |
+| content * | React.ReactNode | - | Dialog body. |
+| onConfirm * | () => void \| Promise<void> | - | Confirm handler. |
+| onCancel * | () => void | - | Cancel handler. |
+| isLoading | boolean | - | Show loading state while confirming. |
 
-## Navigation Hooks
+## DeleteModal
 
-```tsx
-import { useNavigate, useParams, useSearchParams } from '@vertesia/ui/router';
+Delete-specific confirmation wrapper with async delete handling and toast feedback.
 
-// Navigate programmatically
-const navigate = useNavigate();
-navigate('/items/123');
-navigate(-1);  // Go back
+- Route: https://design.vertesiahq.com/components/deleteModal
+- Import path: `@vertesia/ui/core`
+- Exports: `DeleteModal`
 
-// Get route params
-const { id } = useParams();  // From /items/:id
+### Use When
 
-// Get/set query params
-const [searchParams, setSearchParams] = useSearchParams();
-const query = searchParams.get('q');
-```
+- Use for deletion flows where the target is represented by an id.
 
-## NavLink
+### Notes
 
-Navigation link component.
+- Requires a `ToastProvider` ancestor.
 
-```tsx
-import { NavLink } from '@vertesia/ui/router';
+### DeleteModal Props
 
-<NavLink href="/items">Go to Items</NavLink>
-<NavLink href={`/items/${item.id}`}>View Item</NavLink>
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| idToDelete * | string \| undefined | - | Open when populated. |
+| setIdToDelete * | (id: string \| undefined) => void | - | Closes/reset target. |
+| deleteApi * | (id: string) => Promise<void> | - | Async delete function. |
+| title * | React.ReactNode | - | Dialog title. |
+| content * | React.ReactNode | - | Dialog body. |
+
+## SelectBox
+
+Dropdown select for string or object options, with optional search, clear, and multi-select modes.
 
----
+- Route: https://design.vertesiahq.com/components/selectBox
+- Import path: `@vertesia/ui/core`
+- Exports: `SelectBox`
 
-# Layout & Features
+### Use When
 
-## GenericPageNavHeader
+- Use for choosing one or more values from a bounded list.
+- Use `filterBy` for large lists and `by` for stable object equality.
 
-Standard page header with breadcrumbs and actions.
+### SelectBox Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| options * | T[] | - | Selectable options. |
+| value * | T \| T[] \| undefined | - | Selected value or values. |
+| onChange * | (value: T \| T[]) => void | - | Selection change handler. |
+| multiple | boolean | false | Enable multi-select. |
+| optionLabel | (option: T) => React.ReactNode | - | Custom option renderer. |
+| filterBy | keyof T \| ((option: T) => string) | - | Enable searchable filtering. |
+| by | keyof T \| ((a: T, b: T) => boolean) | - | Equality key or comparator. |
+| isClearable | boolean | false | Show clear action. |
+| placeholder | string | - | Placeholder when empty. |
+| disabled | boolean | - | Disable interaction. |
+
+### Example
 
 ```tsx
-import { GenericPageNavHeader } from '@vertesia/ui/features';
-import { NavLink } from '@vertesia/ui/router';
-
-<GenericPageNavHeader
-  title="Page Title"
-  description="Optional page description"
-  breadcrumbs={[
-    <NavLink href="/" key="home">Home</NavLink>,
-    <NavLink href="/items" key="items">Items</NavLink>,
-    <span key="current">Current Page</span>,
-  ]}
-  actions={
-    <Button onClick={() => setShowCreate(true)}>
-      <Plus className="w-4 h-4 mr-2" />
-      Create New
-    </Button>
-  }
+<SelectBox<Person>
+  options={people}
+  value={person}
+  onChange={setPerson}
+  optionLabel={(option) => option.name}
+  filterBy="name"
+  by="id"
 />
 ```
 
-## FullHeightLayout
+## Tabs
 
-Full height container layout.
+Tab container driven by an array of tab objects and companion bar/panel components.
 
-```tsx
-import { FullHeightLayout } from '@vertesia/ui/layout';
+- Route: https://design.vertesiahq.com/components/tabs
+- Import path: `@vertesia/ui/core`
+- Exports: `Tabs`, `TabsBar`, `TabsPanel`, `VTabs`, `VTabsBar`, `VTabsPanel`
 
-<FullHeightLayout>
-  <div>Content fills available height</div>
-</FullHeightLayout>
-```
+### Use When
 
-## Sidebar Components
+- Use to switch between sibling views on the same page.
+- Prefer the current `Tabs` API shown in the style guide for new docs-ui code.
 
-Collapsible sidebar with sections and navigation items.
+### Tabs Props
 
-```tsx
-import { Sidebar, SidebarSection, SidebarItem, useSidebarToggle } from '@vertesia/ui/layout';
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| tabs * | Tab[] | - | Tabs with name, label, and content. |
+| defaultValue | string | - | Initially selected tab. |
+| value | string | - | Controlled selected tab. |
+| onTabChange | (tabName: string) => void | - | Called when selection changes. |
+| variant | 'tabs' \| 'pills' | 'tabs' | Visual treatment. |
+| fullWidth | boolean | - | Stretch tabs across available width. |
+| responsive | boolean | - | Adapt tab layout at smaller widths. |
 
-### SidebarSection
+## Badge and DotBadge
 
-Groups sidebar items with an optional title header.
+Compact status and category labels.
 
-```tsx
-interface SidebarSectionProps {
-  title?: React.ReactNode;     // Section header (hidden when sidebar collapsed)
-  action?: React.ReactNode;    // Action element next to title
-  isFooter?: boolean;          // Pushes section to bottom (mt-auto)
-  className?: string;
-}
-
-<SidebarSection title="Navigation">
-  <SidebarItem ...>Home</SidebarItem>
-  <SidebarItem ...>Settings</SidebarItem>
-</SidebarSection>
-
-// Footer section (theme toggle, user menu, etc.)
-<SidebarSection isFooter>
-  <ModeToggle label={isOpen ? 'Theme' : false} />
-</SidebarSection>
-```
+- Route: https://design.vertesiahq.com/components/badges
+- Import path: `@vertesia/ui/core`
+- Exports: `Badge`, `DotBadge`
 
-### SidebarItem
+### Use When
 
-Navigation link within a sidebar section.
+- Use `Badge` for short textual labels.
+- Use `DotBadge` for status chips where the colored dot carries state.
 
-```tsx
-interface SidebarItemProps {
-  href: string;
-  icon?: React.ComponentType;   // Lucide icon or similar
-  current?: boolean;            // Active/selected state
-  id?: string;
-  external?: boolean;           // Opens in new tab
-  replace?: boolean;            // Replace history entry
-  tools?: React.ReactNode;      // Right-side actions
-  className?: string;
-}
-
-<SidebarItem
-  href="/app/settings"
-  icon={SettingsIcon}
-  current={path === '/app/settings'}
->
-  Settings
-</SidebarItem>
-
-// For long text, wrap children to truncate
-<SidebarItem href={href} icon={MessageSquare} className="overflow-hidden">
-  <span className="truncate">{longLabel}</span>
-</SidebarItem>
-```
+### Notes
 
-### useSidebarToggle
+- Use semantic variants for status meaning instead of custom colors.
 
-Access sidebar open/collapsed state.
+## MessageBox
 
-```tsx
-const { isOpen, toggleMobile } = useSidebarToggle();
-// isOpen: boolean — true when sidebar is expanded
-// toggleMobile(open?: boolean) — toggle mobile sidebar
-```
+Semantic feedback box for success, attention, destructive, done, info, and muted messages.
 
-## ModeToggle (Dark/Light Theme)
+- Route: https://design.vertesiahq.com/components/messageBox
+- Import path: `@vertesia/ui/core`
+- Exports: `MessageBox`
 
-```tsx
-import { ModeToggle } from '@vertesia/ui/core';
+### Use When
 
-<ModeToggle />                           // Icon only
-<ModeToggle label="Theme" />             // With label text
-<ModeToggle label={isOpen ? 'Theme' : false} />  // Label when sidebar open
-```
+- Use for inline feedback, warnings, errors, and informational notices.
 
-## ModernAgentConversation
+## Checkbox, Switch, and RadioGroup
 
-Full-featured agent chat interface with streaming messages, plan visualization, and workstream management.
+Choice controls for boolean values and mutually exclusive option sets.
 
-```tsx
-import { ModernAgentConversation } from '@vertesia/ui/features';
-
-interface ModernAgentConversationProps {
-  run?: { runId: string; workflowId: string };  // Active conversation (undefined = start view)
-  startWorkflow: (initialMessage?: string) => Promise<{ run_id: string; workflow_id: string } | undefined>;
-  resetWorkflow?: () => void;          // Called when user clicks "New conversation"
-  title?: string;                       // Header title (default: "Agent")
-  placeholder?: string;                 // Input placeholder text
-  startButtonText?: string;             // Start button label
-  hideObjectLinking?: boolean;          // Hide document linking UI
-  interactive?: boolean;                // Enable user input during conversation
-  fullWidth?: boolean;                  // Disable max-width constraint
-}
-
-// Basic usage
-<ModernAgentConversation
-  run={run ? { runId: run.run_id, workflowId: run.workflow_id } : undefined}
-  startWorkflow={startWorkflow}
-  resetWorkflow={handleReset}
-  title="My Assistant"
-  placeholder="Ask me anything..."
-  startButtonText="Start Conversation"
-  hideObjectLinking
-  interactive
-/>
-```
+- Route: https://design.vertesiahq.com/components/checkbox
+- Import path: `@vertesia/ui/core`
+- Exports: `Checkbox`, `Switch`, `RadioGroup`, `RadioGroupItem`, `RadioGroupOption`
 
-**Two states:**
-- No `run` prop → shows start view with title, description area, and input to begin a conversation
-- With `run` prop → streams messages and shows the active conversation with real-time updates
+### Use When
 
----
+- Use `Checkbox` for independent boolean fields.
+- Use `Switch` for settings that take effect immediately.
+- Use `RadioGroup` for one-of-many choices when all options should be visible.
 
-# Styling
+## Dropdown, Popover, Command, Tooltip
 
-Use Tailwind CSS with semantic color classes:
+Overlay primitives for action menus, floating content, command palettes, and contextual help.
 
-```tsx
-// Status colors
-<span className="text-success">Success</span>
-<span className="text-attention">Warning</span>
-<span className="text-destructive">Error</span>
-<span className="text-muted-foreground">Muted</span>
-
-// Backgrounds with opacity
-<div className="bg-success/10 text-success">Success message</div>
-<div className="bg-destructive/10 text-destructive">Error message</div>
-
-// Common layout patterns
-<div className="p-4 space-y-4">         {/* Padding + vertical spacing */}
-<div className="flex items-center gap-2"> {/* Horizontal flex */}
-<div className="grid grid-cols-3 gap-4">  {/* Grid layout */}
-```
+- Route: https://design.vertesiahq.com/components/dropdown
+- Import path: `@vertesia/ui/core`
+- Exports: `Dropdown`, `MenuGroup`, `MenuItem`, `Popover`, `Command`, `VTooltip`, `Tooltip`
 
----
+### Use When
 
-# Common Patterns
+- Use `Dropdown` for action menus.
+- Use `Popover` for small interactive floating panels.
+- Use `Command` for searchable command or selection lists.
+- Use `VTooltip` or `Tooltip` for short hover/focus help.
 
-## Form with Input and Textarea
+## Card and Panel
 
-```tsx
-function MyForm() {
-  const [name, setName] = useState('');
-  const [description, setDescription] = useState('');
-
-  return (
-    <form className="space-y-4">
-      <div>
-        <Label htmlFor="name">Name</Label>
-        <Input id="name" value={name} onChange={setName} />
-      </div>
-      <div>
-        <Label htmlFor="desc">Description</Label>
-        <Textarea
-          id="desc"
-          value={description}
-          onChange={(e) => setDescription(e.target.value)}
-        />
-      </div>
-      <Button type="submit">Submit</Button>
-    </form>
-  );
-}
-```
+Content containers for repeated items and framed tool surfaces.
 
-## Data List with Loading/Error States
+- Route: https://design.vertesiahq.com/components/card
+- Import path: `@vertesia/ui/core`
+- Exports: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `Panel`
 
-```tsx
-function ItemList() {
-  const { client } = useUserSession();
-  const { data, isLoading, error, refetch } = useFetch(
-    () => client.store.collections.list(),
-    []
-  );
-
-  if (isLoading) return <Spinner />;
-  if (error) return <ErrorBox>{error.message}</ErrorBox>;
-
-  return (
-    <div className="space-y-2">
-      {data?.map(item => (
-        <Card key={item.id}>
-          <CardHeader>
-            <CardTitle>{item.name}</CardTitle>
-          </CardHeader>
-        </Card>
-      ))}
-    </div>
-  );
-}
-```
+### Use When
 
-## Modal with Form
+- Use cards for repeated items, modal content groups, and genuinely framed tools.
+- Avoid putting cards inside cards or styling whole page sections as floating cards.
 
-```tsx
-function CreateModal({ open, onClose, onCreated }) {
-  const [name, setName] = useState('');
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const { client } = useUserSession();
-  const toast = useToast();
-
-  const handleSubmit = async () => {
-    setIsSubmitting(true);
-    try {
-      await client.store.collections.create({ name });
-      toast({ title: 'Created successfully' });
-      onCreated();
-      onClose();
-    } catch (err) {
-      toast({ title: 'Error', description: err.message, variant: 'destructive' });
-    } finally {
-      setIsSubmitting(false);
-    }
-  };
-
-  return (
-    <VModal isOpen={open} onClose={onClose} size="md">
-      <VModalTitle>Create Item</VModalTitle>
-      <VModalBody>
-        <Label>Name</Label>
-        <Input value={name} onChange={setName} disabled={isSubmitting} />
-      </VModalBody>
-      <VModalFooter>
-        <Button onClick={handleSubmit} disabled={!name || isSubmitting}>
-          {isSubmitting ? 'Creating...' : 'Create'}
-        </Button>
-        <Button variant="outline" onClick={onClose}>Cancel</Button>
-      </VModalFooter>
-    </VModal>
-  );
-}
-```
+## Layout Primitives
+
+Small primitives for display, separation, links, loading states, portals, and overlays.
+
+- Route: https://design.vertesiahq.com/components/center
+- Import path: `@vertesia/ui/core`
+- Exports: `Avatar`, `SvgAvatar`, `Center`, `Divider`, `Link`, `Portal`, `Spinner`, `Separator`, `Overlay`
+
+### Use When
+
+- Use `Spinner` for loading states and `Center` to center short empty/loading content.
+- Use `Separator` for semantic separators and `Divider` for a simple visual rule.
+- Use `Avatar` for users or entities with image, initials, or fallback display.
+
+## Semantic Colors and Icons
+
+Semantic Tailwind classes and approved lucide-react icon guidance for Vertesia apps.
+
+- Route: https://design.vertesiahq.com/semantic
+- Import path: `@vertesia/ui/core`
+- Exports: `ModeToggle`
+
+### Use When
+
+- Use semantic colors: success, attention, destructive, done, info, muted.
+- Use lucide-react icons in buttons and toolbars when an icon exists.
+- Use `ModeToggle` for light/dark theme control.
+
+### Notes
 
----
+- Examples: `text-success`, `bg-attention`, `border-destructive`, `bg-mixer-muted/30`.
+- Avoid hardcoded color values in application UI.
 
-# Key Differences from Standard React
+# Key Rules
 
-1. **Input onChange** passes value directly: `onChange={setValue}` not `onChange={(e) => setValue(e.target.value)}`
-2. **Textarea onChange** uses standard React events
-3. **VModalFooter** uses flex-row-reverse (primary button first in code, appears right)
-4. **NestedRouterProvider** for plugin routing (instead of BrowserRouter)
-5. **useUserSession** provides pre-authenticated Vertesia client
+- `Input` passes a string value to `onChange`; `Textarea` passes a React change event.
+- Use `FormItem` for labeled form fields in create/edit forms.
+- Use semantic colors: `success`, `attention`, `destructive`, `done`, `info`, and `muted`.
+- Use lucide-react icons in icon buttons and compact toolbars.
+- Avoid nested cards and avoid styling whole page sections as cards.