xertica-ui 2.0.2 → 2.0.4

package/llms-compact.txt

@@ -0,0 +1,327 @@
+# Xertica UI — Compact Reference
+
+> 97-component React design system. Tailwind CSS v4 + Radix UI + Lucide Icons.
+> Full docs: llms-full.txt | Component index: llms.txt | Decision guide: docs/decision-tree.md
+
+---
+
+## CRITICAL RULES
+
+```
+NEVER  raw <button>/<input>/<select>  → use <Button>/<Input>/<Select>
+NEVER  raw colors bg-blue-500         → use bg-primary, bg-muted, bg-destructive
+NEVER  hardcoded radius rounded-lg    → use rounded-[var(--radius)]
+NEVER  <h1>/<h2> for page headers    → use <PageHeader><PageHeaderHeading>
+NEVER  manage sidebar state locally  → use useLayout() from xertica-ui/hooks
+NEVER  render <Toaster> manually     → auto-injected by XerticaProvider
+NEVER  icons from xertica-ui         → use lucide-react exclusively
+ALWAYS wrap app in <XerticaProvider> → required for theme, toasts, tooltips
+ALWAYS import style.css at root      → import 'xertica-ui/style.css'
+ALWAYS confirm destructive actions   → pair with <AlertDialog> before executing
+```
+
+---
+
+## IMPORTS
+
+```tsx
+import { Button, Card, Input, Badge, Table,
+         Dialog, AlertDialog, Select, Checkbox,
+         Tabs, Sheet, Popover, Tooltip, Toast,
+         PageHeader, PageHeaderHeading,
+         Progress, Skeleton, Empty, ScrollArea,
+         Separator, Form, Label, Textarea }      from 'xertica-ui/ui';
+
+import { Sidebar, Header }                       from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo,
+         ThemeToggle, LanguageSelector }         from 'xertica-ui/brand';
+import { XerticaAssistant,
+         generateDemoResponse }                  from 'xertica-ui/assistant';
+import { VideoPlayer, AudioPlayer }              from 'xertica-ui/media';
+import { useLayout, useTheme }                   from 'xertica-ui/hooks';
+import 'xertica-ui/style.css';                   // once, at root only
+```
+
+---
+
+## DESIGN TOKENS (always use these, never raw colors)
+
+```
+bg-background / text-foreground        page bg + body text
+bg-card / text-card-foreground         card surface
+bg-muted / text-muted-foreground       subdued bg + secondary text
+bg-primary / text-primary-foreground   brand primary
+bg-destructive                         danger/error
+bg-accent / text-accent-foreground     hover states
+bg-success / bg-info / bg-warning      semantic states
+border-border                          standard borders
+border-input                           form borders
+```
+
+---
+
+## APP STRUCTURE
+
+```tsx
+// main.tsx
+import { XerticaProvider } from 'xertica-ui/brand';
+import { BrowserRouter }   from 'react-router-dom';
+import 'xertica-ui/style.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <XerticaProvider>
+    <BrowserRouter><App /></BrowserRouter>
+  </XerticaProvider>
+);
+```
+
+---
+
+## PAGE STRUCTURE (every page must follow this)
+
+```tsx
+import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui/ui';
+
+export function MyPage() {
+  return (
+    <>
+      <PageHeader>
+        <PageHeaderHeading>Title</PageHeaderHeading>
+        <Button>Primary Action</Button>
+      </PageHeader>
+      <div className="p-6 space-y-6">{/* content */}</div>
+    </>
+  );
+}
+```
+
+---
+
+## LAYOUT SYSTEM
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+const { sidebarExpanded, sidebarWidth, toggleSidebar,
+        assistenteExpanded, toggleAssistente } = useLayout();
+
+// Content container must offset for sidebar:
+<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
+```
+
+---
+
+## MOST-USED COMPONENTS
+
+### Button — 9 variants
+```tsx
+<Button variant="default">Save</Button>
+<Button variant="destructive">Delete</Button>   // always pair with AlertDialog
+<Button variant="outline">Cancel</Button>
+<Button variant="ghost" size="icon" aria-label="Settings"><Settings /></Button>
+<Button asChild><Link to="/page">Go</Link></Button>  // router navigation
+```
+
+### Card
+```tsx
+<Card>
+  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter><Button>Action</Button></CardFooter>
+</Card>
+```
+
+### Input + Label (form field)
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="you@company.com" />
+</div>
+```
+
+### Dialog
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
+    <DialogBody>Content</DialogBody>  {/* scrollable */}
+    <DialogFooter><Button type="submit">Save</Button></DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### AlertDialog (destructive confirmation)
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Table (CRUD list)
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow>
+  </TableHeader>
+  <TableBody>
+    {items.map(item => (
+      <TableRow key={item.id}>
+        <TableCell>{item.name}</TableCell>
+        <TableCell><Badge variant="success">{item.status}</Badge></TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+### Toast (via sonner)
+```tsx
+import { toast } from 'sonner';
+
+toast.success('Saved!');
+toast.error('Failed to save');
+toast.info('Processing...');
+// Never render <Toaster> — auto-injected by XerticaProvider
+```
+
+### Select
+```tsx
+<Select onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="Choose..." /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">Option A</SelectItem>
+    <SelectItem value="b">Option B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Sidebar
+```tsx
+import { Sidebar }   from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+function AppSidebar({ user, onLogout }) {
+  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
+  return (
+    <Sidebar
+      expanded={sidebarExpanded}
+      onToggle={toggleSidebar}
+      width={sidebarWidth}
+      navigate={useNavigate()}
+      location={useLocation()}
+      routes={[
+        { path: '/home', label: 'Home', icon: Home },
+        { path: '/settings', label: 'Settings', icon: Settings },
+      ]}
+      user={user}
+      onLogout={onLogout}
+    />
+  );
+}
+```
+
+### Header
+```tsx
+import { Header } from 'xertica-ui/layout';
+
+<Header
+  breadcrumbs={[{ label: 'Home', href: '/home' }, { label: 'Settings' }]}
+  user={user}
+  onLogout={onLogout}
+/>
+```
+
+### Empty state
+```tsx
+<Empty>
+  <EmptyIcon><FileX className="size-12 text-muted-foreground" /></EmptyIcon>
+  <EmptyTitle>No results</EmptyTitle>
+  <EmptyDescription>Try adjusting your filters.</EmptyDescription>
+  <EmptyAction><Button>Clear filters</Button></EmptyAction>
+</Empty>
+```
+
+### StatsCard (dashboard KPI)
+```tsx
+<StatsCard
+  title="Total Users"
+  value="12,430"
+  trend={8.2}
+  icon={<Users className="size-4" />}
+/>
+```
+
+---
+
+## QUICK COMPONENT SELECTION
+
+| Need | Use |
+|---|---|
+| User must confirm before proceeding | `AlertDialog` |
+| Form or detail view in overlay | `Dialog` |
+| Wide form from the side | `Sheet` |
+| Mobile overlay from bottom | `Drawer` |
+| Anchored interactive panel | `Popover` |
+| Short hover hint | `Tooltip` |
+| Rich hover preview | `HoverCard` |
+| Ephemeral message | `toast()` (sonner) |
+| Persistent inline message | `Alert` |
+| Loading state | `Skeleton` |
+| No data | `Empty` |
+| Multi-step flow | `Stepper` |
+| Tab switching | `Tabs` |
+| Collapsible FAQ/list | `Accordion` |
+| Single expandable | `Collapsible` |
+| Date input | `Calendar` + `Popover` |
+| Numeric range | `Slider` |
+| One of many options | `RadioGroup` or `Select` |
+| On/off setting | `Switch` |
+| Multi-select list | `Checkbox` group |
+| Search/filter | `Search` or `Command` |
+| Row actions | `DropdownMenu` |
+| Right-click actions | `ContextMenu` |
+
+---
+
+## FORM PATTERN (react-hook-form + zod)
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';
+
+const schema = z.object({ name: z.string().min(2) });
+
+function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema) });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField control={form.control} name="name" render={({ field }) => (
+          <FormItem>
+            <FormLabel>Name</FormLabel>
+            <FormControl><Input {...field} /></FormControl>
+            <FormMessage />
+          </FormItem>
+        )} />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  );
+}
+```

package/llms.txt

@@ -1,71 +1,160 @@
-# Xertica UI
-> Biblioteca de componentes React para prototipação AI-First.
-
-Este design system foi construído especificamente para ser consumido por IAs (LLMs, agentes autônomos, assistentes de código) garantindo a geração de telas consistentes, robustas e seguindo boas práticas sem ambiguidades.
-
-## 🚀 Manifesto Técnico Consolidado (Single Source of Truth)
-Para agentes com janelas de contexto grandes, utilize o arquivo abaixo para obter o contexto completo de toda a biblioteca em uma única leitura:
-- `llms-full.txt` - **DOCUMENTAÇÃO COMPLETA DE TODOS OS COMPONENTES**
-
-## 📖 Documentação Principal (Docs)
-- `/docs/getting-started.md` - Como iniciar um projeto e injetar a biblioteca.
-- `/docs/installation.md` - Requisitos e instalação via pacotes.
-- `/docs/guidelines.md` - Diretrizes visuais, de nomenclatura e de UX do Design System.
-- `/docs/architecture.md` - Estrutura modular e organização interna (Domain-Driven).
-- `/docs/ai-usage.md` - Manual de como agentes devem ler, compor e utilizar os componentes.
-
-## 🧩 Referência de Componentes (97 itens)
-Abaixo estão os links para a documentação individual de cada componente para consultas rápidas:
-
-### Layout & Navigation
-- `accordion`, `alert`, `alert-dialog`, `aspect-ratio`, `avatar`, `badge`, `breadcrumb`, `button`, `card`, `carousel`, `collapsible`, `command`, `context-menu`, `dialog`, `drawer`, `dropdown-menu`, `empty`, `header`, `hover-card`, `menubar`, `navigation-menu`, `page-header`, `pagination`, `popover`, `resizable`, `scroll-area`, `separator`, `sheet`, `sidebar`, `skeleton`, `tabs`, `tooltip`.
-
-### Forms & Inputs
-- `checkbox`, `file-upload`, `form`, `input`, `input-otp`, `label`, `radio-group`, `rating`, `search`, `select`, `slider`, `switch`, `textarea`, `toggle`, `toggle-group`, `rich-text-editor`.
-
-### Data & Feedback
-- `calendar`, `chart`, `progress`, `sonner`, `stats-card`, `stepper`, `table`, `timeline`, `tree-view`, `notification-badge`.
-
-### Maps & Geolocation
-- `map`, `route-map`, `simple-map`, `google-maps-loader`, `map-layers`.
-
-### Media
-- `video-player`, `audio-player`, `floating-media-wrapper`.
-
-### Assistant
-- `xertica-assistant`, `markdown-message`, `code-block`, `formatted-document`, `modern-chat-input`.
-
-### Brand
-- `theme-toggle`, `language-selector`, `xertica-logo`, `xertica-xlogo`, `xertica-orbe`, `xertica-provider`.
-
-### Pages
-- `login-page`, `home-page`, `home-content`, `template-page`, `template-content`, `forgot-password-page`, `reset-password-page`, `verify-email-page`.
-
-## 📦 Subpath Imports (FSD/FDA)
-O pacote expõe entradas granulares por camada, permitindo imports precisos sem carregar a biblioteca inteira:
-
-```ts
-import { Button, Card }         from 'xertica-ui/ui';        // shared/ui → primitivos
-import { useLayout, useTheme }  from 'xertica-ui/hooks';     // shared/lib → hooks
-import { XerticaProvider }      from 'xertica-ui/brand';     // app → providers/brand
-import { XerticaAssistant }     from 'xertica-ui/assistant'; // features → assistente
-import { Sidebar, Header }      from 'xertica-ui/layout';    // features → layout
-import { VideoPlayer }          from 'xertica-ui/media';     // features → media
-import 'xertica-ui/style.css';                               // estilos (importar uma vez no root)
-```
-
-> O import raiz `from 'xertica-ui'` continua disponível para compatibilidade total.
-
-## 🏗️ Padrões de Composição (Cookbook)
-- `/docs/patterns/form.md` - Formulários com validação Zod.
-- `/docs/patterns/dashboard.md` - Dashboards e Analytics.
-- `/docs/patterns/crud.md` - Listagens e edição de dados.
-
-## ⚖️ Diretrizes de Acessibilidade (A11y)
-- **Nomes Acessíveis**: Todo `<Button>` ou `<Input>` sem label visual **deve** obrigatoriamente ter um `aria-label`.
-- **Placeholder ≠ Label**: Nunca utilize o placeholder como substituto para o nome acessível do campo.
-- **Icon Buttons**: Botões contendo apenas ícones devem ter `aria-label` descritivo da ação (ex: "Fechar", "Configurações").
-
-> **Agente de IA**: Antes de sugerir implementações customizadas em HTML/Tailwind, procure obrigatoriamente um componente nesta biblioteca. Utilize `llms-full.txt` para entender as regras estritas de cada componente. Sempre priorize acessibilidade WCAG ao gerar componentes.
-> 
-> **IMPORTANTE**: Toda página **deve** obrigatoriamente utilizar o componente `<PageHeader>` para seu título principal e ações. Nunca utilize `h1`, `h2` ou `div` para cabeçalhos de página.
+# Xertica UI
+
+> Enterprise-grade React design system — 97 components built on Tailwind CSS v4, Radix UI, and Lucide Icons. Designed to be consumed directly by AI coding agents (LLMs, Cursor, Claude Code, Copilot).
+
+Xertica UI ships with full source, typed declarations, Storybook stories, and structured documentation inside `node_modules/xertica-ui/`. AI agents should read this file first, then follow links for component-specific detail.
+
+## Quick Start
+
+- [Getting Started](docs/getting-started.md): Provider setup, theming, routing integration, and subpath import patterns.
+- [Installation](docs/installation.md): Peer dependencies, CSS import, and provider setup steps.
+- [AI Usage Rules](docs/ai-usage.md): Mandatory rules for AI agents — what is permitted, what is forbidden.
+- [Compact Reference](llms-full.txt): Complete documentation of all 97 components in a single file (large context LLMs).
+- [Compact Quick-Reference](llms-compact.txt): ~4K token summary — import patterns, critical rules, most-used components.
+- [Component Selection Guide](docs/decision-tree.md): Decision trees for Dialog vs Sheet, Tooltip vs HoverCard, etc.
+
+## Critical Rules (read before generating any code)
+
+1. **Never use raw HTML elements** — `<button>`, `<input>`, `<select>` → always use library components.
+2. **Never use raw colors** — `bg-blue-500`, `#3b82f6` → always use semantic tokens (`bg-primary`, `bg-muted`).
+3. **Never use hardcoded radii** — `rounded-lg` → always `rounded-[var(--radius)]`.
+4. **Every page requires `<PageHeader>`** — never use `<h1>` or `<h2>` for page titles.
+5. **Wrap the app in `<XerticaProvider>`** — required for theme, toasts, tooltips, and layout context.
+6. **Import `xertica-ui/style.css` once** at the root entry file.
+7. **Icons come from `lucide-react`** — never from `xertica-ui`.
+8. **Layout state from `useLayout()`** — never hardcode sidebar widths.
+9. **Destructive actions require `<AlertDialog>`** — never execute directly on click.
+10. **`<Toaster>` is auto-injected** by `<XerticaProvider>` — never render it manually.
+
+## Import Patterns
+
+```tsx
+import { Button, Card, Input, Badge, Table, Dialog } from 'xertica-ui/ui';
+import { Sidebar, Header }                           from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo, ThemeToggle } from 'xertica-ui/brand';
+import { XerticaAssistant, generateDemoResponse }    from 'xertica-ui/assistant';
+import { VideoPlayer, AudioPlayer }                  from 'xertica-ui/media';
+import { useLayout, useTheme }                       from 'xertica-ui/hooks';
+import 'xertica-ui/style.css';
+```
+
+## Component Reference — UI Primitives (`xertica-ui/ui`)
+
+- [Accordion](docs/components/accordion.md): Vertically stacked collapsible sections. Use for FAQs, settings panels, dense trees.
+- [Alert](docs/components/alert.md): Inline persistent status banner. Use when the message must stay visible.
+- [AlertDialog](docs/components/alert-dialog.md): Blocking confirmation modal. Required before any destructive action.
+- [AspectRatio](docs/components/aspect-ratio.md): Fixed-ratio media container. Prevents layout shifts.
+- [Avatar](docs/components/avatar.md): User identity — photo or initials fallback.
+- [Badge](docs/components/badge.md): Compact non-interactive status label or count chip.
+- [Breadcrumb](docs/components/breadcrumb.md): Hierarchical navigation trail. Rendered inside `Header`.
+- [Button](docs/components/button.md): Primary interaction trigger. 9 variants: default, secondary, outline, ghost, destructive, link, success, info, warning.
+- [Calendar](docs/components/calendar.md): Date picker. Almost always wrapped in `Popover`.
+- [Card](docs/components/card.md): Primary content container. Never recreate with raw `<div>`.
+- [Carousel](docs/components/carousel.md): Horizontal content slider. Built on embla-carousel.
+- [Chart](docs/components/chart.md): Token-aware charts built on Recharts. Use `ChartContainer`.
+- [Checkbox](docs/components/checkbox.md): Boolean toggle or multi-select option.
+- [Collapsible](docs/components/collapsible.md): Single expandable section — no sibling management.
+- [Command](docs/components/command.md): Command palette (⌘K). Searchable action list.
+- [ContextMenu](docs/components/context-menu.md): Right-click menu.
+- [Dialog](docs/components/dialog.md): Modal overlay. Dismissible. Use for forms and detail views.
+- [Drawer](docs/components/drawer.md): Bottom-sliding panel. Mobile-optimized equivalent of Sheet.
+- [DropdownMenu](docs/components/dropdown-menu.md): Triggered contextual action menu.
+- [Empty](docs/components/empty.md): Zero-state container for lists and search results.
+- [FileUpload](docs/components/file-upload.md): Drag-and-drop file input.
+- [Form](docs/components/form.md): react-hook-form integration layer.
+- [HoverCard](docs/components/hover-card.md): Rich floating preview on hover. Use for user profiles, link previews.
+- [Input](docs/components/input.md): Single-line text field.
+- [InputOTP](docs/components/input-otp.md): OTP / PIN code segmented input.
+- [Label](docs/components/label.md): Accessible form field label. Always paired with Input via `htmlFor`.
+- [Menubar](docs/components/menubar.md): Application-style horizontal menu bar.
+- [NavigationMenu](docs/components/navigation-menu.md): Horizontal top-level nav with dropdown sub-menus.
+- [NotificationBadge](docs/components/notification-badge.md): Dot or count overlay on icon buttons.
+- [PageHeader](docs/components/page-header.md): Mandatory page title component. Every page must use it.
+- [Pagination](docs/components/pagination.md): Page navigation controls for data tables.
+- [Popover](docs/components/popover.md): Interactive floating panel anchored to a trigger.
+- [Progress](docs/components/progress.md): Read-only completion bar. 5 semantic variants.
+- [RadioGroup](docs/components/radio-group.md): Mutually exclusive options.
+- [Rating](docs/components/rating.md): Star-based rating input or display.
+- [Resizable](docs/components/resizable.md): Draggable panel splitter.
+- [RichTextEditor](docs/components/rich-text-editor.md): Native WYSIWYG text editor.
+- [ScrollArea](docs/components/scroll-area.md): Custom-styled scrollable container.
+- [Search](docs/components/search.md): Search input with icon and clear button.
+- [Select](docs/components/select.md): Accessible dropdown for single option selection. Never use native `<select>`.
+- [Separator](docs/components/separator.md): Visual divider between sections.
+- [Sheet](docs/components/sheet.md): Edge-anchored slide-in panel (top/right/bottom/left).
+- [Skeleton](docs/components/skeleton.md): Loading placeholder. Use instead of blank space.
+- [Slider](docs/components/slider.md): Range value picker by dragging a thumb.
+- [Sonner](docs/components/sonner.md): Toast notification system. Use `toast()` from `sonner`. Auto-injected by `XerticaProvider`.
+- [StatsCard](docs/components/stats-card.md): KPI metric card with trend indicator.
+- [Stepper](docs/components/stepper.md): Multi-step process indicator / wizard.
+- [Switch](docs/components/switch.md): Prominent on/off toggle. Use for feature flags and settings.
+- [Table](docs/components/table.md): Structured tabular data display.
+- [Tabs](docs/components/tabs.md): Content switcher with tab triggers.
+- [Textarea](docs/components/textarea.md): Multi-line text field.
+- [Timeline](docs/components/timeline.md): Vertical chronological event sequence.
+- [Toggle](docs/components/toggle.md): Pressable on/off button for toolbars.
+- [ToggleGroup](docs/components/toggle-group.md): Set of related toggles — single or multiple selection.
+- [Tooltip](docs/components/tooltip.md): Short hover hint for icon-only buttons and abbreviated text.
+- [TreeView](docs/components/tree-view.md): Hierarchical nested data tree.
+
+## Component Reference — Layout (`xertica-ui/layout`)
+
+- [Header](docs/components/header.md): Global top bar (64px). Breadcrumbs, language, theme, user profile.
+- [Sidebar](docs/components/sidebar.md): Primary vertical navigation. Default and Assistant variants.
+
+## Component Reference — Brand (`xertica-ui/brand`)
+
+- [XerticaProvider](docs/components/xertica-provider.md): Mandatory root wrapper. Initializes all contexts.
+- [ThemeToggle](docs/components/theme-toggle.md): Self-contained dark/light mode button. No provider needed.
+- [LanguageSelector](docs/components/language-selector.md): Language dropdown (pt/en/es).
+- [XerticaLogo](docs/components/xertica-logo.md): Full horizontal logotype SVG.
+- [XerticaXLogo](docs/components/xertica-xlogo.md): Compact X-mark logo. Use in collapsed sidebar.
+- [XerticaOrbe](docs/components/xertica-orbe.md): Animated decorative brand orb. For splash screens only.
+
+## Component Reference — AI Assistant (`xertica-ui/assistant`)
+
+- [XerticaAssistant](docs/components/assistant.md): Full AI chat panel with history, favorites, document workspace.
+- [MarkdownMessage](docs/components/markdown-message.md): Markdown renderer for AI responses.
+- [CodeBlock](docs/components/assistant.md): Syntax-highlighted code display with copy button.
+- [ModernChatInput](docs/components/assistant.md): Enhanced AI chat input with drag-and-drop.
+- [FormattedDocument](docs/components/assistant.md): Structured AI-generated document renderer.
+
+## Component Reference — Media (`xertica-ui/media`)
+
+- [VideoPlayer](docs/components/video-player.md): Custom video controls with floating mode.
+- [AudioPlayer](docs/components/audio-player.md): Podcast/audio player — card or global bar variant.
+- [FloatingMediaWrapper](docs/components/floating-media-wrapper.md): Draggable portal wrapper for media players.
+
+## Component Reference — Maps (`xertica-ui`)
+
+- [Map](docs/components/map.md): Google Maps integration with markers, polygons, controls.
+- [RouteMap](docs/components/route-map.md): Route + directions between origin and destination.
+- [SimpleMap](docs/components/simple-map.md): Simplified map for a single marker.
+- [GoogleMapsLoader](docs/components/google-maps-loader.md): Lazy-loads Maps API. Auto-managed by XerticaProvider.
+
+## Design Token Reference
+
+```
+bg-background / text-foreground       page background and body text
+bg-card / text-card-foreground        card surfaces
+bg-muted / text-muted-foreground      subdued areas, secondary text, placeholders
+bg-primary / text-primary-foreground  primary actions, active states
+bg-secondary / text-secondary-fg      secondary actions
+bg-destructive                        danger, delete, error
+bg-accent / text-accent-foreground    hover states
+bg-success / bg-info / bg-warning     semantic state colors
+border-border                         standard borders
+border-input                          form field borders
+ring-ring                             focus rings
+```
+
+## Composition Patterns
+
+- [Form pattern](docs/patterns/form.md): Validated forms with react-hook-form.
+- [CRUD pattern](docs/patterns/crud.md): Table + search + row actions.
+- [Dashboard pattern](docs/patterns/dashboard.md): StatsCard grid + Charts.
+- [Analytics pattern](docs/patterns/analytics.md): Filters + date range + charts.
+
+## Machine-Readable Registry
+
+- [components.json](components.json): All 97 components with name, category, import path, keywords, related components, source path, and doc path.