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

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 apps in `<XerticaProvider>`** — recommended for synchronized theme, toasts, tooltips, layout, assistant state, maps, and API keys.
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.
11. **Wrap `<Routes>` in `<PageErrorBoundary>`** — prevents lazy-chunk failures from showing a blank screen.
12. **Wrap data sections in `<SectionErrorBoundary>`** — tables, charts, and the assistant must not crash the page.
13. **Auth state from `useAuth()`** — never pass `user` or `onLogout` as props to page components; consume from `AuthContext`.
14. **Server data from `useQuery` (React Query)** — never `useState + useEffect + fetch` for API data.
15. **UI strings from `useTranslation()`** — never hardcode text in JSX; add keys to the appropriate file under `locales/<lang>/` (e.g., `locales/pt-BR/common.json` for shared labels, `locales/pt-BR/pages/home.json` for page strings).

## State Management & Auth

- [State Management Guide](docs/state-management.md): React Query, Zustand, AuthContext, `features/` slice pattern, decision tree.
- [i18n Guide](docs/i18n.md): i18next setup, `useTranslation`, locale files, language switching.
- **`useAuth()`** — `{ user, isLoading, login, logout }` from `AuthContext`. Must be inside `<AuthProvider>` (inside `<Router>`).
- **`useQuery`** — server state. Use hooks in `features/*/hooks/`. Swap `fetch*` in `features/*/data/mock.ts` for real API.
- **Zustand** — client UI state. Use stores in `features/*/store/`.
- **Provider stack**: `AppErrorBoundary > QueryClientProvider > XerticaProvider > Router > AuthProvider > PageErrorBoundary > Routes`.

## Error Boundaries

- [ErrorBoundary docs](docs/components/error-boundary.md): Full API, placement guide, AI rules.
- **`AppErrorBoundary`** — outermost; full-screen inline-styled fallback; catches provider crashes.
- **`PageErrorBoundary`** — wraps `<Routes>`; catches lazy-chunk failures and page render errors.
- **`SectionErrorBoundary`** — wraps data sections (table, chart, assistant); compact inline fallback.
- Import: `import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary } from '@/shared/error-boundary';`

## Component Reference — Shared Utilities

- [ErrorBoundary](docs/components/error-boundary.md): `AppErrorBoundary`, `PageErrorBoundary`, `SectionErrorBoundary`, `ErrorBoundary` (base class). Props: `onError`, `resetKeys`.

## 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`; 11 dashboard-ready wrappers: `ChartCard`, `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, and `GaugeChart` (pure SVG semicircle gauge with thresholds).
- [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): Recommended root wrapper. Initializes shared contexts and services.
- [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
--mobile-content-padding              horizontal padding for content on mobile (< 768px), default 1.25rem
```

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