# Xertica UI — Compact Reference

> 97-component React design system. Tailwind CSS v4 + Radix UI + Lucide Icons. v2.5.3
> Full docs: llms-full.txt | Component index: llms.txt | Decision guide: docs/decision-tree.md

---

## CRITICAL RULES

```
NEVER  raw <button>/<input>/<select>  → use <Button>/<Input>/<Select>
NEVER  raw colors bg-blue-500         → use bg-primary, bg-muted, bg-destructive
NEVER  hardcoded radius rounded-lg    → use rounded-[var(--radius)]
NEVER  <h1>/<h2> for page headers    → use <PageHeader><PageHeaderHeading>
NEVER  manage sidebar state locally  → use useLayout() from xertica-ui/hooks
NEVER  render <Toaster> manually     → auto-injected by XerticaProvider
NEVER  icons from xertica-ui         → use lucide-react exclusively
NEVER  pass user/onLogout as props   → consume useAuth() from AuthContext
NEVER  useState+useEffect+fetch      → use useQuery (React Query) for server data
NEVER  hardcode UI strings in JSX    → use t('key') from useTranslation()
ALWAYS wrap full apps in <XerticaProvider> → shared theme, toasts, tooltips, layout
ALWAYS wrap <Routes> in <PageErrorBoundary> → prevents blank screen on chunk failures
ALWAYS wrap data sections in <SectionErrorBoundary> → tables/charts/assistant
ALWAYS import style.css at root      → import 'xertica-ui/style.css'
ALWAYS confirm destructive actions   → pair with <AlertDialog> before executing
```

---

## IMPORTS

```tsx
import { Button, Card, Input, Badge, Table,
         Dialog, AlertDialog, Select, Checkbox,
         Tabs, Sheet, Popover, Tooltip, Toast,
         PageHeader, PageHeaderHeading,
         Progress, Skeleton, Empty, ScrollArea,
         Separator, Form, Label, Textarea }      from 'xertica-ui/ui';

import { Sidebar, Header }                       from 'xertica-ui/layout';
import { XerticaProvider, XerticaLogo,
         ThemeToggle, LanguageSelector }         from 'xertica-ui/brand';
import { XerticaAssistant,
         generateDemoResponse }                  from 'xertica-ui/assistant';
import { VideoPlayer, AudioPlayer }              from 'xertica-ui/media';
import { useLayout, useTheme }                   from 'xertica-ui/hooks';
import 'xertica-ui/style.css';                   // once, at root only
```

---

## DESIGN TOKENS (always use these, never raw colors)

```
bg-background / text-foreground        page bg + body text
bg-card / text-card-foreground         card surface
bg-muted / text-muted-foreground       subdued bg + secondary text
bg-primary / text-primary-foreground   brand primary
bg-destructive                         danger/error
bg-accent / text-accent-foreground     hover states
bg-success / bg-info / bg-warning      semantic states
border-border                          standard borders
border-input                           form borders
--mobile-content-padding               horizontal padding on mobile < 768px (default 1.25rem)
```

## COLOR THEMES

```tsx
// Full preset — sets primary, sidebar, charts AND dark-mode surface hues
<XerticaProvider defaultColorTheme="blue">      // blue dark bg: #03050f
<XerticaProvider defaultColorTheme="violet">   // violet dark bg: #07040f
<XerticaProvider defaultColorTheme="rose">     // rose dark bg: #0f0305
<XerticaProvider defaultColorTheme="emerald">  // emerald dark bg: #030f08
<XerticaProvider defaultColorTheme="amber">    // amber dark bg: #0f0a03
<XerticaProvider defaultColorTheme="orange">   // orange dark bg: #0f0703
<XerticaProvider defaultColorTheme="xertica-original"> // indigo dark bg: #05050d (default)

// Custom hex primary only (dark surfaces stay neutral indigo)
<XerticaProvider primaryColor="#7C3AED">
```

---

## APP STRUCTURE

```tsx
// main.tsx
import './i18n';                      // initialize i18next BEFORE any component
import 'xertica-ui/style.css';

// App.tsx — canonical provider stack
import { AppErrorBoundary, PageErrorBoundary } from './shared/error-boundary';
import { QueryClient, QueryClientProvider }    from '@tanstack/react-query';
import { XerticaProvider }                     from 'xertica-ui/brand';
import { BrowserRouter as Router }             from 'react-router-dom';
import { AuthProvider }                        from './app/context/AuthContext';

const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: false } },
});

export default function App() {
  return (
    <AppErrorBoundary>                   {/* catches provider/context crashes  */}
      <QueryClientProvider client={queryClient}>
        <XerticaProvider>
          <Router>
            <AuthProvider>              {/* must be inside Router              */}
              <PageErrorBoundary>       {/* catches lazy-chunk + page errors   */}
                <YourRoutes />
              </PageErrorBoundary>
            </AuthProvider>
          </Router>
        </XerticaProvider>
      </QueryClientProvider>
    </AppErrorBoundary>
  );
}
```

## AUTH

```tsx
// Inside <AuthProvider> — no props needed on page components
import { useAuth } from './app/context/AuthContext';

const { user, isLoading, login, logout } = useAuth();
// isLoading: true while localStorage is being read (prevents flash redirects)
// login(email, password): boolean — returns false on empty credentials
// logout(): clears session + navigates to /login
```

## STATE MANAGEMENT

```tsx
// Server state → React Query (features/*/hooks/)
import { useTeamMembers } from '../features/home';
const { data: members = [], isLoading } = useTeamMembers();

// Client UI state → Zustand (features/*/store/)
import { useDashboardStore } from '../features/home';
const progress = useDashboardStore(s => s.progress);

// To connect to a real API — edit ONLY the fetch function in features/*/data/mock.ts:
export async function fetchTeamMembers() {
  return fetch('/api/team/members').then(r => r.json()); // ← swap this line
}
```

## I18N

```tsx
import { useTranslation } from 'react-i18next';
const { t } = useTranslation();
return <h1>{t('home.welcome')}</h1>;   // keys in locales/pt-BR/pages/home.json (and matching en/, es/ folders)

// Change language (also persists to localStorage):
import { useLanguage } from 'xertica-ui/hooks';
const { setLanguage } = useLanguage();
setLanguage('en');   // → i18n.changeLanguage('en') + localStorage
```

## ERROR BOUNDARIES

```tsx
import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary }
  from './shared/error-boundary';

// Root (catches provider crashes — inline-styled, no Tailwind needed):
<AppErrorBoundary onError={Sentry.captureException}>…</AppErrorBoundary>

// Route (catches lazy-chunk failures):
<PageErrorBoundary resetKeys={[location.pathname]}>
  <Suspense fallback={null}><Routes>…</Routes></Suspense>
</PageErrorBoundary>

// Section (isolates table/chart/assistant errors):
<SectionErrorBoundary><TeamDataTable /></SectionErrorBoundary>
```

---

## PAGE STRUCTURE (every page must follow this)

```tsx
import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui/ui';

export function MyPage() {
  return (
    <>
      <PageHeader>
        <PageHeaderHeading>Title</PageHeaderHeading>
        <Button>Primary Action</Button>
      </PageHeader>
      <div className="p-6 space-y-6">{/* content */}</div>
    </>
  );
}
```

---

## LAYOUT SYSTEM

```tsx
import { useLayout } from 'xertica-ui/hooks';

const { sidebarExpanded, sidebarWidth, toggleSidebar,
        assistenteExpanded, toggleAssistente } = useLayout();

// Content container must offset for sidebar:
<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
```

---

## MOST-USED COMPONENTS

### Button — 9 variants
```tsx
<Button variant="default">Save</Button>
<Button variant="destructive">Delete</Button>   // always pair with AlertDialog
<Button variant="outline">Cancel</Button>
<Button variant="ghost" size="icon" aria-label="Settings"><Settings /></Button>
<Button asChild><Link to="/page">Go</Link></Button>  // router navigation
```

### Card
```tsx
<Card>
  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
  <CardContent>Content</CardContent>
  <CardFooter><Button>Action</Button></CardFooter>
</Card>
```

### Input + Label (form field)
```tsx
<div className="space-y-2">
  <Label htmlFor="email">Email</Label>
  <Input id="email" type="email" placeholder="you@company.com" />
</div>
```

### Dialog
```tsx
<Dialog>
  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
    <DialogBody>Content</DialogBody>  {/* scrollable */}
    <DialogFooter><Button type="submit">Save</Button></DialogFooter>
  </DialogContent>
</Dialog>
```

### AlertDialog (destructive confirmation)
```tsx
<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

### Table (CRUD list)
```tsx
<Table>
  <TableHeader>
    <TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow>
  </TableHeader>
  <TableBody>
    {items.map(item => (
      <TableRow key={item.id}>
        <TableCell>{item.name}</TableCell>
        <TableCell><Badge variant="success">{item.status}</Badge></TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>
```

### Toast (via sonner)
```tsx
import { toast } from 'sonner';

toast.success('Saved!');
toast.error('Failed to save');
toast.info('Processing...');
// Never render <Toaster> — auto-injected by XerticaProvider
```

### Select
```tsx
<Select onValueChange={setValue}>
  <SelectTrigger><SelectValue placeholder="Choose..." /></SelectTrigger>
  <SelectContent>
    <SelectItem value="a">Option A</SelectItem>
    <SelectItem value="b">Option B</SelectItem>
  </SelectContent>
</Select>
```

### Sidebar
```tsx
import { Sidebar }   from 'xertica-ui/layout';
import { useLayout } from 'xertica-ui/hooks';
import { useNavigate, useLocation } from 'react-router-dom';

function AppSidebar({ user, onLogout }) {
  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
  return (
    <Sidebar
      expanded={sidebarExpanded}
      onToggle={toggleSidebar}
      width={sidebarWidth}
      navigate={useNavigate()}
      location={useLocation()}
      routes={[
        { path: '/home', label: 'Home', icon: Home },
        { path: '/settings', label: 'Settings', icon: Settings },
      ]}
      user={user}
      onLogout={onLogout}
    />
  );
}

// Sub-items (children) — desktop: ChevronRight opens a lateral DropdownMenu
//                       mobile:  ChevronRight expands items inline (accordion)
navigationGroups={[{
  id: 'main', label: 'Principal',
  items: [{
    path: '/dashboard', label: 'Dashboard', icon: BarChart,
    children: [
      { path: '/dashboard/overview', label: 'Visão Geral', icon: BarChart },
      { path: '/dashboard/reports',  label: 'Relatórios',  icon: FileEdit },
    ],
  }],
}]}
```

### Header
```tsx
import { Header } from 'xertica-ui/layout';

<Header
  breadcrumbs={[{ label: 'Home', href: '/home' }, { label: 'Settings' }]}
  user={user}
  onLogout={onLogout}
/>
```

### Empty state
```tsx
<Empty>
  <EmptyIcon><FileX className="size-12 text-muted-foreground" /></EmptyIcon>
  <EmptyTitle>No results</EmptyTitle>
  <EmptyDescription>Try adjusting your filters.</EmptyDescription>
  <EmptyAction><Button>Clear filters</Button></EmptyAction>
</Empty>
```

### StatsCard (dashboard KPI)
```tsx
<StatsCard
  title="Total Users"
  value="12,430"
  trend={8.2}
  icon={<Users className="size-4" />}
/>
```

---

## QUICK COMPONENT SELECTION

| Need | Use |
|---|---|
| User must confirm before proceeding | `AlertDialog` |
| Form or detail view in overlay | `Dialog` |
| Wide form from the side | `Sheet` |
| Mobile overlay from bottom | `Drawer` |
| Anchored interactive panel | `Popover` |
| Short hover hint | `Tooltip` |
| Rich hover preview | `HoverCard` |
| Ephemeral message | `toast()` (sonner) |
| Persistent inline message | `Alert` |
| Loading state | `Skeleton` |
| No data | `Empty` |
| Multi-step flow | `Stepper` |
| Tab switching | `Tabs` |
| Collapsible FAQ/list | `Accordion` |
| Single expandable | `Collapsible` |
| Date input | `Calendar` + `Popover` |
| Numeric range | `Slider` |
| One of many options | `RadioGroup` or `Select` |
| On/off setting | `Switch` |
| Multi-select list | `Checkbox` group |
| Search/filter | `Search` or `Command` |
| Row actions | `DropdownMenu` |
| Right-click actions | `ContextMenu` |

---

## FORM PATTERN (react-hook-form + zod)

```tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';

const schema = z.object({ name: z.string().min(2) });

function MyForm() {
  const form = useForm({ resolver: zodResolver(schema) });
  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField control={form.control} name="name" render={({ field }) => (
          <FormItem>
            <FormLabel>Name</FormLabel>
            <FormControl><Input {...field} /></FormControl>
            <FormMessage />
          </FormItem>
        )} />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  );
}
```