# ThemeToggle — Xertica UI

A self-contained light/dark mode toggle button that operates directly on the `document.documentElement` class list.

---

## Import

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

---

## Usage

### Basic (icon only)

```tsx
<ThemeToggle />
```

### With label text

```tsx
<ThemeToggle showLabel />
```

### Size and variant variants

```tsx
<ThemeToggle size="sm" variant="outline" />
<ThemeToggle size="lg" variant="default" />
```

---

## Props

| Prop        | Type                                | Default   | Description                                       |
| ----------- | ----------------------------------- | --------- | ------------------------------------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'`              | `'md'`    | Controls the button and icon size                 |
| `variant`   | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Visual style of the underlying `<Button>`         |
| `showLabel` | `boolean`                           | `false`   | Whether to show "Modo Claro" / "Modo Escuro" text |
| `className` | `string`                            | `''`      | Additional CSS classes                            |

---

## Behavior

- On click, the component toggles the `dark` class on `<html>`.
- Initial state is read from `document.documentElement.classList` on mount.
- Does **not** persist to localStorage or any global state — use a shared state or `localStorage` listener at the app root level if persistence is required.
- Fully operates without any context provider.

---

## Placement Guidelines

The component is typically placed in one of two locations:

1. **Sidebar footer** — always visible regardless of current page
2. **Header actions** — adjacent to the user avatar menu

---

## AI Rules

> [!IMPORTANT]
>
> - **Do not create manual dark-mode toggles** — always use `<ThemeToggle>` from the library.
> - **One per layout shell** — do not render multiple instances simultaneously, they will conflict.
> - **No provider needed** — this component is self-contained and works anywhere in the React tree.