xertica-ui 2.5.0 → 2.5.2

package/docs/llms.md

@@ -1,295 +1,295 @@
-# Xertica UI — LLM Reference Index
-
-> **This is the primary entrypoint for AI agents operating on any project that uses `xertica-ui`.** Read this document first before exploring any other file.
-
-## Statistics
-
-- **Total Components:** 104
-- **UI Components:** 62
-- **Assistant Components:** 8
-- **Brand Components:** 6
-- **Media Components:** 3
-- **Layout Components:** 2
-- **Page Templates:** 8
-- **Hooks:** 10
-- **Shared Utilities:** ErrorBoundary (3 variants), i18n integration, navigation
-
-## What is Xertica UI?
-
-Xertica UI is an **enterprise-grade React design system** built on top of Tailwind CSS v4, Radix UI, and Lucide Icons. It provides a comprehensive set of accessible, themeable components designed for business applications: dashboards, management panels, data-heavy CRUD interfaces, and AI-powered tools.
-
-The library is distributed as an npm package (`xertica-ui`) and ships with a CLI tool (`npx xertica-ui@latest init`) for scaffolding new projects.
-
----
-
-## Reading Order for AI Agents
-
-Follow this order when onboarding to a project that uses `xertica-ui`:
-
-1. **This document** (`docs/llms.md`) — orientation and navigation
-2. **`docs/ai-usage.md`** — mandatory rules for AI agents operating this library
-3. **`docs/guidelines.md`** — design tokens, color semantics, spacing, typography
-4. **`docs/getting-started.md`** — provider setup, theming, routing, AuthContext, lazy loading
-5. **`docs/installation.md`** — installation, peer dependencies, CSS import
-6. **`docs/layout.md`** — the layout system, `LayoutContext`, `useLayout` hook
-7. **`docs/state-management.md`** — React Query, Zustand, AuthContext, `features/` slice pattern
-8. **`docs/i18n.md`** — i18next setup, `useTranslation`, locale files, language switching
-9. **`docs/architecture.md`** — internal folder structure after modularization (for contributors)
-10. **`docs/patterns/`** — pre-built composition patterns for common page types
-11. **`docs/components/`** — individual component references (read on demand)
-
----
-
-## Library Philosophy
-
-| Principle                                 | Description                                                                                                                                                                                                                                         |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Composition over configuration**        | Build complex UIs by composing simple, focused components                                                                                                                                                                                           |
-| **Semantic tokens for semantic contexts** | Never use raw hex colors (`#3b82f6`, `rgb(...)`). For error/warning/success/status contexts, always use semantic tokens (`bg-destructive`, `bg-success`, etc.). For layout and general non-semantic UI, standard Tailwind utilities are acceptable. |
-| **No native HTML alternatives**           | Always use the library's components; never use raw `<button>`, `<input>`, `<div>` for UI surfaces                                                                                                                                                   |
-| **Accessible by default**                 | All interactive components are built on Radix UI primitives with full ARIA support                                                                                                                                                                  |
-| **LLM-first documentation**               | Every component doc contains explicit rules, anti-patterns, and composition guidance                                                                                                                                                                |
-
----
-
-## Component Catalog Index
-
-### Layout & Navigation
-
-| Component               | Doc                                                   | Purpose                                                  |
-| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
-| `Header`                | [header.md](./components/header.md)                   | Top bar with breadcrumbs, user profile, actions          |
-| `Sidebar`               | [sidebar.md](./components/sidebar.md)                 | Primary navigation drawer (default + assistant variants) |
-| `PageHeader`            | [page-header.md](./components/page-header.md)         | Sticky breadcrumb bar with language/theme controls       |
-| `PageHeaderHeading`     | [page-header.md](./components/page-header.md)         | Styled `<h1>` for page content areas                     |
-| `PageHeaderDescription` | [page-header.md](./components/page-header.md)         | Styled subtitle paragraph                                |
-| `Breadcrumb`            | [breadcrumb.md](./components/breadcrumb.md)           | Hierarchical page path indicator                         |
-| `NavigationMenu`        | [navigation-menu.md](./components/navigation-menu.md) | Horizontal top-level navigation                          |
-
-### Core Surfaces
-
-| Component     | Doc                                             | Purpose                                    |
-| ------------- | ----------------------------------------------- | ------------------------------------------ |
-| `Card`        | [card.md](./components/card.md)                 | Primary container for content blocks       |
-| `Separator`   | [separator.md](./components/separator.md)       | Visual divider between sections            |
-| `ScrollArea`  | [scroll-area.md](./components/scroll-area.md)   | Scrollable container with custom scrollbar |
-| `AspectRatio` | [aspect-ratio.md](./components/aspect-ratio.md) | Fixed-ratio media container                |
-| `Resizable`   | [resizable.md](./components/resizable.md)       | Draggable panel splitter                   |
-
-### Form Elements
-
-| Component        | Doc                                                     | Purpose                           |
-| ---------------- | ------------------------------------------------------- | --------------------------------- |
-| `Form`           | [form.md](./components/form.md)                         | React Hook Form integration layer |
-| `Input`          | [input.md](./components/input.md)                       | Text field                        |
-| `Textarea`       | [textarea.md](./components/textarea.md)                 | Multi-line text field             |
-| `RichTextEditor` | [rich-text-editor.md](./components/rich-text-editor.md) | Native WYSIWYG document editor    |
-| `Label`          | [label.md](./components/label.md)                       | Accessible field label            |
-| `Checkbox`       | [checkbox.md](./components/checkbox.md)                 | Boolean toggle                    |
-| `RadioGroup`     | [radio-group.md](./components/radio-group.md)           | Single-choice selection           |
-| `Switch`         | [switch.md](./components/switch.md)                     | Feature toggle                    |
-| `Select`         | [select.md](./components/select.md)                     | Single-option dropdown            |
-| `Slider`         | [slider.md](./components/slider.md)                     | Range value picker                |
-| `Calendar`       | [calendar.md](./components/calendar.md)                 | Date picker                       |
-| `InputOTP`       | [input-otp.md](./components/input-otp.md)               | OTP / PIN code input              |
-| `FileUpload`     | [file-upload.md](./components/file-upload.md)           | Drag-and-drop file input          |
-| `Search`         | [search.md](./components/search.md)                     | Search input with icon            |
-
-### Actions & Controls
-
-| Component     | Doc                                             | Purpose                           |
-| ------------- | ----------------------------------------------- | --------------------------------- |
-| `Button`      | [button.md](./components/button.md)             | Primary interaction trigger       |
-| `Toggle`      | [toggle.md](./components/toggle.md)             | Pressable on/off button           |
-| `ToggleGroup` | [toggle-group.md](./components/toggle-group.md) | Set of mutually exclusive toggles |
-| `Rating`      | [rating.md](./components/rating.md)             | Star-based rating input           |
-
-### Data Display
-
-| Component           | Doc                                                         | Purpose                                                                                                                                                                                                                                                                                          |
-| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `Table`             | [table.md](./components/table.md)                           | Structured tabular data                                                                                                                                                                                                                                                                          |
-| `Badge`             | [badge.md](./components/badge.md)                           | Status labels and tags                                                                                                                                                                                                                                                                           |
-| `Avatar`            | [avatar.md](./components/avatar.md)                         | User identity image                                                                                                                                                                                                                                                                              |
-| `Progress`          | [progress.md](./components/progress.md)                     | Completion percentage bar                                                                                                                                                                                                                                                                        |
-| `Skeleton`          | [skeleton.md](./components/skeleton.md)                     | Loading placeholder                                                                                                                                                                                                                                                                              |
-| `Empty`             | [empty.md](./components/empty.md)                           | Empty state placeholder                                                                                                                                                                                                                                                                          |
-| `StatsCard`         | [stats-card.md](./components/stats-card.md)                 | KPI metric card                                                                                                                                                                                                                                                                                  |
-| `Timeline`          | [timeline.md](./components/timeline.md)                     | Vertical event sequence                                                                                                                                                                                                                                                                          |
-| `Stepper`           | [stepper.md](./components/stepper.md)                       | Multi-step process indicator                                                                                                                                                                                                                                                                     |
-| `TreeView`          | [tree-view.md](./components/tree-view.md)                   | Hierarchical data tree                                                                                                                                                                                                                                                                           |
-| `NotificationBadge` | [notification-badge.md](./components/notification-badge.md) | Dot/count badge overlay                                                                                                                                                                                                                                                                          |
-| `Chart`             | [chart.md](./components/chart.md)                           | Recharts-based data charts — 11 dashboard-ready wrappers: `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, `GaugeChart` |
-
-### Structure & Layout Utilities
-
-| Component     | Doc                                           | Purpose                     |
-| ------------- | --------------------------------------------- | --------------------------- |
-| `Tabs`        | [tabs.md](./components/tabs.md)               | Tabbed content switcher     |
-| `Accordion`   | [accordion.md](./components/accordion.md)     | Expandable content sections |
-| `Collapsible` | [collapsible.md](./components/collapsible.md) | Single expandable section   |
-| `Carousel`    | [carousel.md](./components/carousel.md)       | Horizontal content slider   |
-| `Pagination`  | [pagination.md](./components/pagination.md)   | Page navigation controls    |
-
-### Overlays & Feedback
-
-| Component     | Doc                                             | Purpose                 |
-| ------------- | ----------------------------------------------- | ----------------------- |
-| `Dialog`      | [dialog.md](./components/dialog.md)             | Modal dialog            |
-| `AlertDialog` | [alert-dialog.md](./components/alert-dialog.md) | Confirmation modal      |
-| `Sheet`       | [sheet.md](./components/sheet.md)               | Side-panel drawer       |
-| `Drawer`      | [drawer.md](./components/drawer.md)             | Bottom sheet (mobile)   |
-| `Popover`     | [popover.md](./components/popover.md)           | Anchored floating panel |
-| `HoverCard`   | [hover-card.md](./components/hover-card.md)     | Preview on hover        |
-| `Tooltip`     | [tooltip.md](./components/tooltip.md)           | Short contextual hint   |
-| `Alert`       | [alert.md](./components/alert.md)               | Inline message banner   |
-| `Sonner`      | [sonner.md](./components/sonner.md)             | Toast notifications     |
-| `Command`     | [command.md](./components/command.md)           | Command palette         |
-
-### Menus
-
-| Component      | Doc                                               | Purpose                         |
-| -------------- | ------------------------------------------------- | ------------------------------- |
-| `DropdownMenu` | [dropdown-menu.md](./components/dropdown-menu.md) | Triggered contextual menu       |
-| `ContextMenu`  | [context-menu.md](./components/context-menu.md)   | Right-click contextual menu     |
-| `Menubar`      | [menubar.md](./components/menubar.md)             | Horizontal application menu bar |
-
-### Maps & Geolocation
-
-| Component          | Doc                                                         | Purpose                                  |
-| ------------------ | ----------------------------------------------------------- | ---------------------------------------- |
-| `Map`              | [map.md](./components/map.md)                               | General-purpose Google Maps integration  |
-| `RouteMap`         | [route-map.md](./components/route-map.md)                   | Route + directions between two locations |
-| `SimpleMap`        | [simple-map.md](./components/simple-map.md)                 | Simplified map view for single markers   |
-| `GoogleMapsLoader` | [google-maps-loader.md](./components/google-maps-loader.md) | Provider/Hook for lazy-loading Maps API  |
-
-### Hooks
-
-| Hook                        | Doc                                                       | Purpose                                                             |
-| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
-| `useMobile` / `useIsMobile` | [use-mobile.md](./components/use-mobile.md)               | Detects mobile viewport for conditional rendering                   |
-| `useLayout`                 | [layout.md](../layout.md)                                 | Accesses sidebar width, state, and toggle functions                 |
-| `useTheme`                  | [hooks.md](./components/hooks.md#usetheme)                | Reads and toggles the current color theme (light/dark)              |
-| `useLanguage`               | [hooks.md](./components/hooks.md#uselanguage)             | Reads and sets the current UI language; calls `i18n.changeLanguage` |
-| `useAuth`                   | [state-management.md](../state-management.md#authcontext) | Current user, login, logout — from `AuthContext`                    |
-| `useBrandColors`            | [hooks.md](./components/hooks.md#usebrandcolors)          | Reads and modifies brand color CSS variables                        |
-| `useAssistente`             | [hooks.md](./components/hooks.md#useassistente)           | Accesses the global AI assistant context                            |
-| `useApiKey`                 | [hooks.md](./components/hooks.md#useapikey)               | Manages API keys for Xertica, Gemini, and Google Maps               |
-| `useAudioPlayer`            | [hooks.md](./components/hooks.md#useaudioplayer)          | Headless hook for building custom audio player UIs                  |
-| `useLayoutShortcuts`        | [hooks.md](./components/hooks.md#uselayoutshortcuts)      | Registers global keyboard shortcuts (Ctrl+B = sidebar toggle)       |
-
-### Page Templates
-
-| Component            | Doc                                                  | Purpose                                                             |
-| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
-| `LoginPage`          | [pages.md](./components/pages.md#loginpage)          | Complete login screen with email/password and SSO placeholders      |
-| `ForgotPasswordPage` | [pages.md](./components/pages.md#forgotpasswordpage) | Password recovery form                                              |
-| `ResetPasswordPage`  | [pages.md](./components/pages.md#resetpasswordpage)  | New password form for reset flow                                    |
-| `VerifyEmailPage`    | [pages.md](./components/pages.md#verifyemailpage)    | Email verification confirmation screen                              |
-| `HomePage`           | [pages.md](./components/pages.md#homepage)           | Root dashboard shell (Sidebar + HomeContent + Assistant)            |
-| `HomeContent`        | [pages.md](./components/pages.md#homecontent)        | Dashboard main content area with stats, charts, and tables          |
-| `TemplatePage`       | [pages.md](./components/pages.md#templatepage)       | Full layout reference shell (Sidebar + TemplateContent + Assistant) |
-| `TemplateContent`    | [pages.md](./components/pages.md#templatecontent)    | Comprehensive component showcase for development reference          |
-
-### AI Features
-
-| Component           | Doc                                                         | Purpose                                                      |
-| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
-| `XerticaAssistant`  | [assistant.md](./components/assistant.md)                   | Embedded AI chat panel & document workspace                  |
-| `CodeBlock`         | [code-block.md](./components/code-block.md)                 | Syntax-highlighted code display with copy button             |
-| `MarkdownMessage`   | [markdown-message.md](./components/markdown-message.md)     | Renders AI responses with Markdown formatting                |
-| `ModernChatInput`   | [modern-chat-input.md](./components/modern-chat-input.md)   | Enhanced AI chat input with action chips and voice recording |
-| `FormattedDocument` | [formatted-document.md](./components/formatted-document.md) | Collapsible Markdown renderer for AI-generated documents     |
-| `AssistantChart`    | [assistant-chart.md](./components/assistant-chart.md)       | Specialized data visualization for AI insights               |
-
-### Brand & Theme
-
-| Component          | Doc                                                       | Purpose                                                                                                      |
-| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `ThemeToggle`      | [theme-toggle.md](./components/theme-toggle.md)           | Self-contained dark/light mode switcher (DOM-based, no context required)                                     |
-| `LanguageSelector` | [language-selector.md](./components/language-selector.md) | Language picker wired to `LanguageContext` + `i18next` (pt-BR/en/es)                                         |
-| `XerticaLogo`      | [xertica-logo.md](./components/xertica-logo.md)           | Full horizontal Xertica logotype SVG                                                                         |
-| `XerticaXLogo`     | [xertica-xlogo.md](./components/xertica-xlogo.md)         | Compact X-mark logo variant                                                                                  |
-| `XerticaOrbe`      | [xertica-orbe.md](./components/xertica-orbe.md)           | Animated orb brand mark                                                                                      |
-| `XerticaProvider`  | [xertica-provider.md](./components/xertica-provider.md)   | Recommended app provider for theme, brand, language, API keys, assistant, layout, maps, tooltips, and toasts |
-
-### Shared Utilities
-
-| Component / Utility    | Doc                                                 | Purpose                                                             |
-| ---------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
-| `AppErrorBoundary`     | [error-boundary.md](./components/error-boundary.md) | Root-level error boundary — wraps entire app outside all providers  |
-| `PageErrorBoundary`    | [error-boundary.md](./components/error-boundary.md) | Route-level error boundary — wraps `<Routes>` / `<AuthGuard>`       |
-| `SectionErrorBoundary` | [error-boundary.md](./components/error-boundary.md) | Section-level error boundary — wraps data tables, charts, assistant |
-| `ErrorBoundary` (base) | [error-boundary.md](./components/error-boundary.md) | Raw class component with custom `fallback` prop                     |
-
-### Blocks (Rich Components)
-
-| Component     | Doc                                             | Purpose                                                                     |
-| ------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
-| `AudioPlayer` | [audio-player.md](./components/audio-player.md) | Audio playback control bar with waveform, adapts to sidebar/assistant width |
-| `VideoPlayer` | [video-player.md](./components/video-player.md) | Video player with custom controls and floating support                      |
-
----
-
-## Design Token Quick Reference
-
-Use semantic tokens for semantic/status contexts. **Never use raw hex values or `rgb()`/`hsl()` literals.**
-
-```
-Background:     bg-background          text-foreground
-Card surface:   bg-card                text-card-foreground
-Muted area:     bg-muted               text-muted-foreground
-Primary action: bg-primary             text-primary-foreground
-Secondary:      bg-secondary           text-secondary-foreground
-Destructive:    bg-destructive         text-destructive-foreground
-Border:         border-border
-Input border:   border-input
-Ring:           ring-ring
-```
-
----
-
-## Import Pattern
-
-### Subpath Imports (v2 — Recommended for FSD/FDA projects)
-
-```tsx
-import { Button, Card, CardContent, Input, Badge } from 'xertica-ui/ui';
-import { Sidebar, Header } from 'xertica-ui/layout';
-import { XerticaProvider, XerticaLogo } from 'xertica-ui/brand';
-import { XerticaAssistant } from 'xertica-ui/assistant';
-import { VideoPlayer, AudioPlayer } from 'xertica-ui/media';
-import { useLayout, useTheme } from 'xertica-ui/hooks';
-import 'xertica-ui/style.css';
-```
-
-### Root Barrel (backward compatible)
-
-```tsx
-import { Button, Card, CardContent, Input, Badge } from 'xertica-ui';
-```
-
-Icons are NOT included — use `lucide-react` separately:
-
-```tsx
-import { Home, Settings, LogOut } from 'lucide-react';
-```
-
----
-
-## Critical Rules (Summary)
-
-1. **No raw HTML UI elements** — use `<Button>`, `<Input>`, `<Card>` etc., never `<button>`, `<input>`, `<div class="card">`
-2. **No raw SVGs** — always use `lucide-react` icons
-3. **No raw hex/rgb colors** — never use `#3b82f6`, `rgb(...)`, or `hsl(...)` literals. Use semantic tokens for semantic/status contexts; standard Tailwind utilities are acceptable for layout and non-semantic UI.
-4. **Wrap full apps in `<XerticaProvider>`** — import from `xertica-ui/brand`; recommended for shared services and synchronized layout
-5. **Import `xertica-ui/style.css`** — without it, components render without styles
-6. **Use `useLayout()`** — for sidebar state and width, never manage layout state manually
-7. **Wrap `<Routes>` in `<PageErrorBoundary>`** — prevents lazy-chunk failures from crashing the entire app
-8. **Wrap data sections in `<SectionErrorBoundary>`** — tables, charts, and the assistant panel must not crash the page
-9. **Use `useAuth()` for authentication state** — never pass `user` or `onLogout` as props to page components
-10. **Use `useTranslation()` for all UI strings** — never hardcode text in JSX; add keys to the appropriate file under `locales/<lang>/` (e.g., `locales/pt-BR/common.json`, `locales/pt-BR/pages/home.json`) instead
-11. **Use `useQuery` (React Query) for server data** — never `useState + useEffect + fetch` for data that comes from an API
-12. **Use Zustand for client UI state** — filters, toggles, and tab selections that don't come from a server
-
-For the full rule set, see [`docs/ai-usage.md`](./ai-usage.md) and [`docs/state-management.md`](../state-management.md).
+# Xertica UI — LLM Reference Index
+
+> **This is the primary entrypoint for AI agents operating on any project that uses `xertica-ui`.** Read this document first before exploring any other file.
+
+## Statistics
+
+- **Total Components:** 104
+- **UI Components:** 62
+- **Assistant Components:** 8
+- **Brand Components:** 6
+- **Media Components:** 3
+- **Layout Components:** 2
+- **Page Templates:** 8
+- **Hooks:** 10
+- **Shared Utilities:** ErrorBoundary (3 variants), i18n integration, navigation
+
+## What is Xertica UI?
+
+Xertica UI is an **enterprise-grade React design system** built on top of Tailwind CSS v4, Radix UI, and Lucide Icons. It provides a comprehensive set of accessible, themeable components designed for business applications: dashboards, management panels, data-heavy CRUD interfaces, and AI-powered tools.
+
+The library is distributed as an npm package (`xertica-ui`) and ships with a CLI tool (`npx xertica-ui@latest init`) for scaffolding new projects.
+
+---
+
+## Reading Order for AI Agents
+
+Follow this order when onboarding to a project that uses `xertica-ui`:
+
+1. **This document** (`docs/llms.md`) — orientation and navigation
+2. **`docs/ai-usage.md`** — mandatory rules for AI agents operating this library
+3. **`docs/guidelines.md`** — design tokens, color semantics, spacing, typography
+4. **`docs/getting-started.md`** — provider setup, theming, routing, AuthContext, lazy loading
+5. **`docs/installation.md`** — installation, peer dependencies, CSS import
+6. **`docs/layout.md`** — the layout system, `LayoutContext`, `useLayout` hook
+7. **`docs/state-management.md`** — React Query, Zustand, AuthContext, `features/` slice pattern
+8. **`docs/i18n.md`** — i18next setup, `useTranslation`, locale files, language switching
+9. **`docs/architecture.md`** — internal folder structure after modularization (for contributors)
+10. **`docs/patterns/`** — pre-built composition patterns for common page types
+11. **`docs/components/`** — individual component references (read on demand)
+
+---
+
+## Library Philosophy
+
+| Principle                                 | Description                                                                                                                                                                                                                                         |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Composition over configuration**        | Build complex UIs by composing simple, focused components                                                                                                                                                                                           |
+| **Semantic tokens for semantic contexts** | Never use raw hex colors (`#3b82f6`, `rgb(...)`). For error/warning/success/status contexts, always use semantic tokens (`bg-destructive`, `bg-success`, etc.). For layout and general non-semantic UI, standard Tailwind utilities are acceptable. |
+| **No native HTML alternatives**           | Always use the library's components; never use raw `<button>`, `<input>`, `<div>` for UI surfaces                                                                                                                                                   |
+| **Accessible by default**                 | All interactive components are built on Radix UI primitives with full ARIA support                                                                                                                                                                  |
+| **LLM-first documentation**               | Every component doc contains explicit rules, anti-patterns, and composition guidance                                                                                                                                                                |
+
+---
+
+## Component Catalog Index
+
+### Layout & Navigation
+
+| Component               | Doc                                                   | Purpose                                                  |
+| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
+| `Header`                | [header.md](./components/header.md)                   | Top bar with breadcrumbs, user profile, actions          |
+| `Sidebar`               | [sidebar.md](./components/sidebar.md)                 | Primary navigation drawer (default + assistant variants) |
+| `PageHeader`            | [page-header.md](./components/page-header.md)         | Sticky breadcrumb bar with language/theme controls       |
+| `PageHeaderHeading`     | [page-header.md](./components/page-header.md)         | Styled `<h1>` for page content areas                     |
+| `PageHeaderDescription` | [page-header.md](./components/page-header.md)         | Styled subtitle paragraph                                |
+| `Breadcrumb`            | [breadcrumb.md](./components/breadcrumb.md)           | Hierarchical page path indicator                         |
+| `NavigationMenu`        | [navigation-menu.md](./components/navigation-menu.md) | Horizontal top-level navigation                          |
+
+### Core Surfaces
+
+| Component     | Doc                                             | Purpose                                    |
+| ------------- | ----------------------------------------------- | ------------------------------------------ |
+| `Card`        | [card.md](./components/card.md)                 | Primary container for content blocks       |
+| `Separator`   | [separator.md](./components/separator.md)       | Visual divider between sections            |
+| `ScrollArea`  | [scroll-area.md](./components/scroll-area.md)   | Scrollable container with custom scrollbar |
+| `AspectRatio` | [aspect-ratio.md](./components/aspect-ratio.md) | Fixed-ratio media container                |
+| `Resizable`   | [resizable.md](./components/resizable.md)       | Draggable panel splitter                   |
+
+### Form Elements
+
+| Component        | Doc                                                     | Purpose                           |
+| ---------------- | ------------------------------------------------------- | --------------------------------- |
+| `Form`           | [form.md](./components/form.md)                         | React Hook Form integration layer |
+| `Input`          | [input.md](./components/input.md)                       | Text field                        |
+| `Textarea`       | [textarea.md](./components/textarea.md)                 | Multi-line text field             |
+| `RichTextEditor` | [rich-text-editor.md](./components/rich-text-editor.md) | Native WYSIWYG document editor    |
+| `Label`          | [label.md](./components/label.md)                       | Accessible field label            |
+| `Checkbox`       | [checkbox.md](./components/checkbox.md)                 | Boolean toggle                    |
+| `RadioGroup`     | [radio-group.md](./components/radio-group.md)           | Single-choice selection           |
+| `Switch`         | [switch.md](./components/switch.md)                     | Feature toggle                    |
+| `Select`         | [select.md](./components/select.md)                     | Single-option dropdown            |
+| `Slider`         | [slider.md](./components/slider.md)                     | Range value picker                |
+| `Calendar`       | [calendar.md](./components/calendar.md)                 | Date picker                       |
+| `InputOTP`       | [input-otp.md](./components/input-otp.md)               | OTP / PIN code input              |
+| `FileUpload`     | [file-upload.md](./components/file-upload.md)           | Drag-and-drop file input          |
+| `Search`         | [search.md](./components/search.md)                     | Search input with icon            |
+
+### Actions & Controls
+
+| Component     | Doc                                             | Purpose                           |
+| ------------- | ----------------------------------------------- | --------------------------------- |
+| `Button`      | [button.md](./components/button.md)             | Primary interaction trigger       |
+| `Toggle`      | [toggle.md](./components/toggle.md)             | Pressable on/off button           |
+| `ToggleGroup` | [toggle-group.md](./components/toggle-group.md) | Set of mutually exclusive toggles |
+| `Rating`      | [rating.md](./components/rating.md)             | Star-based rating input           |
+
+### Data Display
+
+| Component           | Doc                                                         | Purpose                                                                                                                                                                                                                                                                                          |
+| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Table`             | [table.md](./components/table.md)                           | Structured tabular data                                                                                                                                                                                                                                                                          |
+| `Badge`             | [badge.md](./components/badge.md)                           | Status labels and tags                                                                                                                                                                                                                                                                           |
+| `Avatar`            | [avatar.md](./components/avatar.md)                         | User identity image                                                                                                                                                                                                                                                                              |
+| `Progress`          | [progress.md](./components/progress.md)                     | Completion percentage bar                                                                                                                                                                                                                                                                        |
+| `Skeleton`          | [skeleton.md](./components/skeleton.md)                     | Loading placeholder                                                                                                                                                                                                                                                                              |
+| `Empty`             | [empty.md](./components/empty.md)                           | Empty state placeholder                                                                                                                                                                                                                                                                          |
+| `StatsCard`         | [stats-card.md](./components/stats-card.md)                 | KPI metric card                                                                                                                                                                                                                                                                                  |
+| `Timeline`          | [timeline.md](./components/timeline.md)                     | Vertical event sequence                                                                                                                                                                                                                                                                          |
+| `Stepper`           | [stepper.md](./components/stepper.md)                       | Multi-step process indicator                                                                                                                                                                                                                                                                     |
+| `TreeView`          | [tree-view.md](./components/tree-view.md)                   | Hierarchical data tree                                                                                                                                                                                                                                                                           |
+| `NotificationBadge` | [notification-badge.md](./components/notification-badge.md) | Dot/count badge overlay                                                                                                                                                                                                                                                                          |
+| `Chart`             | [chart.md](./components/chart.md)                           | Recharts-based data charts — 11 dashboard-ready wrappers: `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, `GaugeChart` |
+
+### Structure & Layout Utilities
+
+| Component     | Doc                                           | Purpose                     |
+| ------------- | --------------------------------------------- | --------------------------- |
+| `Tabs`        | [tabs.md](./components/tabs.md)               | Tabbed content switcher     |
+| `Accordion`   | [accordion.md](./components/accordion.md)     | Expandable content sections |
+| `Collapsible` | [collapsible.md](./components/collapsible.md) | Single expandable section   |
+| `Carousel`    | [carousel.md](./components/carousel.md)       | Horizontal content slider   |
+| `Pagination`  | [pagination.md](./components/pagination.md)   | Page navigation controls    |
+
+### Overlays & Feedback
+
+| Component     | Doc                                             | Purpose                 |
+| ------------- | ----------------------------------------------- | ----------------------- |
+| `Dialog`      | [dialog.md](./components/dialog.md)             | Modal dialog            |
+| `AlertDialog` | [alert-dialog.md](./components/alert-dialog.md) | Confirmation modal      |
+| `Sheet`       | [sheet.md](./components/sheet.md)               | Side-panel drawer       |
+| `Drawer`      | [drawer.md](./components/drawer.md)             | Bottom sheet (mobile)   |
+| `Popover`     | [popover.md](./components/popover.md)           | Anchored floating panel |
+| `HoverCard`   | [hover-card.md](./components/hover-card.md)     | Preview on hover        |
+| `Tooltip`     | [tooltip.md](./components/tooltip.md)           | Short contextual hint   |
+| `Alert`       | [alert.md](./components/alert.md)               | Inline message banner   |
+| `Sonner`      | [sonner.md](./components/sonner.md)             | Toast notifications     |
+| `Command`     | [command.md](./components/command.md)           | Command palette         |
+
+### Menus
+
+| Component      | Doc                                               | Purpose                         |
+| -------------- | ------------------------------------------------- | ------------------------------- |
+| `DropdownMenu` | [dropdown-menu.md](./components/dropdown-menu.md) | Triggered contextual menu       |
+| `ContextMenu`  | [context-menu.md](./components/context-menu.md)   | Right-click contextual menu     |
+| `Menubar`      | [menubar.md](./components/menubar.md)             | Horizontal application menu bar |
+
+### Maps & Geolocation
+
+| Component          | Doc                                                         | Purpose                                  |
+| ------------------ | ----------------------------------------------------------- | ---------------------------------------- |
+| `Map`              | [map.md](./components/map.md)                               | General-purpose Google Maps integration  |
+| `RouteMap`         | [route-map.md](./components/route-map.md)                   | Route + directions between two locations |
+| `SimpleMap`        | [simple-map.md](./components/simple-map.md)                 | Simplified map view for single markers   |
+| `GoogleMapsLoader` | [google-maps-loader.md](./components/google-maps-loader.md) | Provider/Hook for lazy-loading Maps API  |
+
+### Hooks
+
+| Hook                        | Doc                                                       | Purpose                                                             |
+| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |
+| `useMobile` / `useIsMobile` | [use-mobile.md](./components/use-mobile.md)               | Detects mobile viewport for conditional rendering                   |
+| `useLayout`                 | [layout.md](../layout.md)                                 | Accesses sidebar width, state, and toggle functions                 |
+| `useTheme`                  | [hooks.md](./components/hooks.md#usetheme)                | Reads and toggles the current color theme (light/dark)              |
+| `useLanguage`               | [hooks.md](./components/hooks.md#uselanguage)             | Reads and sets the current UI language; calls `i18n.changeLanguage` |
+| `useAuth`                   | [state-management.md](../state-management.md#authcontext) | Current user, login, logout — from `AuthContext`                    |
+| `useBrandColors`            | [hooks.md](./components/hooks.md#usebrandcolors)          | Reads and modifies brand color CSS variables                        |
+| `useAssistente`             | [hooks.md](./components/hooks.md#useassistente)           | Accesses the global AI assistant context                            |
+| `useApiKey`                 | [hooks.md](./components/hooks.md#useapikey)               | Manages API keys for Xertica, Gemini, and Google Maps               |
+| `useAudioPlayer`            | [hooks.md](./components/hooks.md#useaudioplayer)          | Headless hook for building custom audio player UIs                  |
+| `useLayoutShortcuts`        | [hooks.md](./components/hooks.md#uselayoutshortcuts)      | Registers global keyboard shortcuts (Ctrl+B = sidebar toggle)       |
+
+### Page Templates
+
+| Component            | Doc                                                  | Purpose                                                             |
+| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
+| `LoginPage`          | [pages.md](./components/pages.md#loginpage)          | Complete login screen with email/password and SSO placeholders      |
+| `ForgotPasswordPage` | [pages.md](./components/pages.md#forgotpasswordpage) | Password recovery form                                              |
+| `ResetPasswordPage`  | [pages.md](./components/pages.md#resetpasswordpage)  | New password form for reset flow                                    |
+| `VerifyEmailPage`    | [pages.md](./components/pages.md#verifyemailpage)    | Email verification confirmation screen                              |
+| `HomePage`           | [pages.md](./components/pages.md#homepage)           | Root dashboard shell (Sidebar + HomeContent + Assistant)            |
+| `HomeContent`        | [pages.md](./components/pages.md#homecontent)        | Dashboard main content area with stats, charts, and tables          |
+| `TemplatePage`       | [pages.md](./components/pages.md#templatepage)       | Full layout reference shell (Sidebar + TemplateContent + Assistant) |
+| `TemplateContent`    | [pages.md](./components/pages.md#templatecontent)    | Comprehensive component showcase for development reference          |
+
+### AI Features
+
+| Component           | Doc                                                         | Purpose                                                      |
+| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `XerticaAssistant`  | [assistant.md](./components/assistant.md)                   | Embedded AI chat panel & document workspace                  |
+| `CodeBlock`         | [code-block.md](./components/code-block.md)                 | Syntax-highlighted code display with copy button             |
+| `MarkdownMessage`   | [markdown-message.md](./components/markdown-message.md)     | Renders AI responses with Markdown formatting                |
+| `ModernChatInput`   | [modern-chat-input.md](./components/modern-chat-input.md)   | Enhanced AI chat input with action chips and voice recording |
+| `FormattedDocument` | [formatted-document.md](./components/formatted-document.md) | Collapsible Markdown renderer for AI-generated documents     |
+| `AssistantChart`    | [assistant-chart.md](./components/assistant-chart.md)       | Specialized data visualization for AI insights               |
+
+### Brand & Theme
+
+| Component          | Doc                                                       | Purpose                                                                                                      |
+| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ThemeToggle`      | [theme-toggle.md](./components/theme-toggle.md)           | Self-contained dark/light mode switcher (DOM-based, no context required)                                     |
+| `LanguageSelector` | [language-selector.md](./components/language-selector.md) | Language picker wired to `LanguageContext` + `i18next` (pt-BR/en/es)                                         |
+| `XerticaLogo`      | [xertica-logo.md](./components/xertica-logo.md)           | Full horizontal Xertica logotype SVG                                                                         |
+| `XerticaXLogo`     | [xertica-xlogo.md](./components/xertica-xlogo.md)         | Compact X-mark logo variant                                                                                  |
+| `XerticaOrbe`      | [xertica-orbe.md](./components/xertica-orbe.md)           | Animated orb brand mark                                                                                      |
+| `XerticaProvider`  | [xertica-provider.md](./components/xertica-provider.md)   | Recommended app provider for theme, brand, language, API keys, assistant, layout, maps, tooltips, and toasts |
+
+### Shared Utilities
+
+| Component / Utility    | Doc                                                 | Purpose                                                             |
+| ---------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
+| `AppErrorBoundary`     | [error-boundary.md](./components/error-boundary.md) | Root-level error boundary — wraps entire app outside all providers  |
+| `PageErrorBoundary`    | [error-boundary.md](./components/error-boundary.md) | Route-level error boundary — wraps `<Routes>` / `<AuthGuard>`       |
+| `SectionErrorBoundary` | [error-boundary.md](./components/error-boundary.md) | Section-level error boundary — wraps data tables, charts, assistant |
+| `ErrorBoundary` (base) | [error-boundary.md](./components/error-boundary.md) | Raw class component with custom `fallback` prop                     |
+
+### Blocks (Rich Components)
+
+| Component     | Doc                                             | Purpose                                                                     |
+| ------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `AudioPlayer` | [audio-player.md](./components/audio-player.md) | Audio playback control bar with waveform, adapts to sidebar/assistant width |
+| `VideoPlayer` | [video-player.md](./components/video-player.md) | Video player with custom controls and floating support                      |
+
+---
+
+## Design Token Quick Reference
+
+Use semantic tokens for semantic/status contexts. **Never use raw hex values or `rgb()`/`hsl()` literals.**
+
+```
+Background:     bg-background          text-foreground
+Card surface:   bg-card                text-card-foreground
+Muted area:     bg-muted               text-muted-foreground
+Primary action: bg-primary             text-primary-foreground
+Secondary:      bg-secondary           text-secondary-foreground
+Destructive:    bg-destructive         text-destructive-foreground
+Border:         border-border
+Input border:   border-input
+Ring:           ring-ring
+```
+
+---
+
+## Import Pattern
+
+### Subpath Imports (v2 — Recommended for FSD/FDA projects)
+
+```tsx
+import { Button, Card, CardContent, Input, Badge } from 'xertica-ui/ui';
+import { Sidebar, Header } from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo } from 'xertica-ui/brand';
+import { XerticaAssistant } from 'xertica-ui/assistant';
+import { VideoPlayer, AudioPlayer } from 'xertica-ui/media';
+import { useLayout, useTheme } from 'xertica-ui/hooks';
+import 'xertica-ui/style.css';
+```
+
+### Root Barrel (backward compatible)
+
+```tsx
+import { Button, Card, CardContent, Input, Badge } from 'xertica-ui';
+```
+
+Icons are NOT included — use `lucide-react` separately:
+
+```tsx
+import { Home, Settings, LogOut } from 'lucide-react';
+```
+
+---
+
+## Critical Rules (Summary)
+
+1. **No raw HTML UI elements** — use `<Button>`, `<Input>`, `<Card>` etc., never `<button>`, `<input>`, `<div class="card">`
+2. **No raw SVGs** — always use `lucide-react` icons
+3. **No raw hex/rgb colors** — never use `#3b82f6`, `rgb(...)`, or `hsl(...)` literals. Use semantic tokens for semantic/status contexts; standard Tailwind utilities are acceptable for layout and non-semantic UI.
+4. **Wrap full apps in `<XerticaProvider>`** — import from `xertica-ui/brand`; recommended for shared services and synchronized layout
+5. **Import `xertica-ui/style.css`** — without it, components render without styles
+6. **Use `useLayout()`** — for sidebar state and width, never manage layout state manually
+7. **Wrap `<Routes>` in `<PageErrorBoundary>`** — prevents lazy-chunk failures from crashing the entire app
+8. **Wrap data sections in `<SectionErrorBoundary>`** — tables, charts, and the assistant panel must not crash the page
+9. **Use `useAuth()` for authentication state** — never pass `user` or `onLogout` as props to page components
+10. **Use `useTranslation()` for all UI strings** — never hardcode text in JSX; add keys to the appropriate file under `locales/<lang>/` (e.g., `locales/pt-BR/common.json`, `locales/pt-BR/pages/home.json`) instead
+11. **Use `useQuery` (React Query) for server data** — never `useState + useEffect + fetch` for data that comes from an API
+12. **Use Zustand for client UI state** — filters, toggles, and tab selections that don't come from a server
+
+For the full rule set, see [`docs/ai-usage.md`](./ai-usage.md) and [`docs/state-management.md`](../state-management.md).