# 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).