# Branding — Xertica UI

The branding system in Xertica UI provides tools for applying, customizing, and switching the visual identity of an application — including color themes, logos, language, and dark/light mode.

---

## Brand Components Overview

| Component          | Import             | Purpose                                                 |
| ------------------ | ------------------ | ------------------------------------------------------- |
| `XerticaProvider`  | `xertica-ui/brand` | Root provider for all brand, theme, and layout contexts |
| `ThemeToggle`      | `xertica-ui/brand` | Self-contained dark/light mode switcher                 |
| `LanguageSelector` | `xertica-ui/brand` | Standalone language dropdown (pt-BR / en / es)          |
| `XerticaLogo`      | `xertica-ui/brand` | Full horizontal Xertica logotype SVG                    |
| `XerticaXLogo`     | `xertica-ui/brand` | Compact X-mark logo variant                             |
| `XerticaOrbe`      | `xertica-ui/brand` | Animated orb brand mark                                 |

---

## Color Theme System

### How It Works

Xertica UI uses CSS custom properties (design tokens) for all colors. The theme is applied by injecting token values at `:root` and `.dark`. Tailwind v4 maps these tokens via `@theme inline`.

```
tokens.css → :root { --primary: ...; --background: ...; }
           → .dark { --primary: ...; --background: ...; }
           → @theme inline { --color-primary: var(--primary); }
           → Tailwind utilities: bg-primary, text-foreground, etc.
```

### Available Theme Presets

The CLI (`npx xertica-ui@latest init` or `npx xertica-ui@latest update-theme`) offers multiple color presets. Each preset defines a complete set of tokens for both light and dark modes.

### Customizing Colors Programmatically

Use `useBrandColors` to read and modify brand colors at runtime:

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

function BrandCustomizer() {
  const { colors, setBrandColor } = useBrandColors();

  return (
    <div className="space-y-2">
      <label>Primary Color</label>
      <input
        type="color"
        value={colors.primary}
        onChange={e => setBrandColor('primary', e.target.value)}
      />
    </div>
  );
}
```

Changes are applied immediately as CSS variables on `:root`.

---

## Dark / Light Mode

### `ThemeToggle`

A self-contained button that toggles between light and dark mode. Does not require any context provider — it reads and writes `document.documentElement.classList` directly.

```tsx
import { ThemeToggle } from 'xertica-ui/brand';

// Place in Header actions or Sidebar footer
<ThemeToggle size="sm" />;
```

**Props:**

| Prop        | Type                   | Default | Description            |
| ----------- | ---------------------- | ------- | ---------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`  | Button size            |
| `className` | `string`               | —       | Additional CSS classes |

### `useTheme` Hook

For programmatic theme control:

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

function ThemeController() {
  const { theme, setTheme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>Mode: {theme}</button>;
}
```

> **Note**: `useTheme` requires `<XerticaProvider>` in the tree. `ThemeToggle` works without any provider.

---

## Language Selector

### `LanguageSelector`

A standalone dropdown for switching the UI language preference.

```tsx
import { LanguageSelector } from 'xertica-ui/brand';

// Typically placed in PageHeader or Sidebar footer
<LanguageSelector />;
```

The selected language is persisted in `localStorage` under `xertica_language`. Access the current value via `useLanguage()`:

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

function MyComponent() {
  const { language, availableLanguages, isMonolingual } = useLanguage();
  // language is `string` (e.g. 'pt-BR', 'en', 'fr') — the set is runtime-configurable
}
```

The set of available languages is configured at runtime via the `availableLanguages` prop on `<XerticaProvider>` (defaults to `pt-BR`, `en`, `es`). See [`docs/i18n.md`](../i18n.md) for the full extension API. When only one language is configured, the `LanguageSelector` auto-hides.

---

## Logo Components

### `XerticaLogo`

Full horizontal logotype. Use in the Sidebar header or login page.

```tsx
import { XerticaLogo } from 'xertica-ui/brand';

<XerticaLogo className="h-8" />;
```

### `XerticaXLogo`

Compact X-mark variant. Use when space is limited (collapsed sidebar, favicon-like contexts).

```tsx
import { XerticaXLogo } from 'xertica-ui/brand';

<XerticaXLogo className="w-8 h-8" />;
```

### `XerticaOrbe`

Animated orb brand mark. Use as a decorative element or loading indicator.

```tsx
import { XerticaOrbe } from 'xertica-ui/brand';

<XerticaOrbe size={64} />;
```

---

## `XerticaProvider`

The root provider that initializes all brand, theme, layout, and service contexts. Must wrap the entire application once.

```tsx
import { XerticaProvider } from 'xertica-ui/brand';
import 'xertica-ui/style.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <XerticaProvider>
      <App />
    </XerticaProvider>
  </React.StrictMode>
);
```

`XerticaProvider` initializes:

- `ThemeProvider` — dark/light mode
- `LanguageProvider` — language preference
- `BrandColorsProvider` — brand color tokens
- `LayoutProvider` — sidebar and assistant state
- `AssistenteProvider` — AI assistant context
- `ApiKeyProvider` — API key management
- `GoogleMapsLoaderProvider` — lazy Maps API loading
- `TooltipProvider` — Radix tooltip context
- `Toaster` — Sonner toast notifications

**Props:**

| Prop                  | Type        | Default      | Description                                 |
| --------------------- | ----------- | ------------ | ------------------------------------------- |
| `children`            | `ReactNode` | _(required)_ | Application content                         |
| `googleMapsApiKey`    | `string`    | —            | Google Maps API key (activates Maps loader) |
| `initialApiKey`       | `string`    | —            | Pre-set Xertica API key                     |
| `initialGeminiApiKey` | `string`    | —            | Pre-set Gemini API key                      |

---

## CSS Token Structure

The complete token set is defined in `tokens.css` (generated by the CLI). Key token groups:

```css
:root {
  /* Colors */
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --destructive: 0 84.2% 60.2%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 221.2 83.2% 53.3%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;

  /* Chart colors */
  --chart-1: 221.2 83.2% 53.3%;
  --chart-2: 142.1 76.2% 36.3%;
  --chart-3: 47.9 95.8% 53.1%;
  --chart-4: 280.1 65.3% 60%;
  --chart-5: 24.6 95% 53.1%;

  /* Sidebar */
  --sidebar: 222.2 84% 4.9%;
  --sidebar-foreground: 210 40% 98%;

  /* Shape */
  --radius: 0.5rem;
  --radius-button: 0.375rem;
}
```

---

## AI Rules

> [!IMPORTANT]
>
> - **`XerticaProvider` is required once**: Place it at the root of your application. Never nest multiple `XerticaProvider` instances.
> - **Never use raw hex/rgb colors**: All colors must use semantic tokens (`bg-primary`, `text-destructive`, `border-border`). Raw values like `#3b82f6` or `rgb(59, 130, 246)` are forbidden.
> - **`ThemeToggle` is self-contained**: It does not need `useTheme` or any context. Use it directly in any component without provider requirements.
> - **Logo sizing via `className`**: Size logo components using Tailwind height/width classes (`h-8`, `w-8`). Do not use `width`/`height` HTML attributes.
> - **Language is preference only**: `LanguageSelector` stores a preference. The library UI renders in Portuguese regardless. Implement your own i18n logic using the `language` value from `useLanguage()`.