# `theme-toggle.variants`

## Purpose

Cva slot for the chassis `<ThemeToggle>` icon-button. Mirrors the
shape of `<Button variant="outline" size="icon">` so the toggle reads
as a tertiary chrome control (the kind of button you put in a header
or sidebar, not the primary CTA).

## Features

- Single `ThemeToggle` slot keyed by the `mode` axis (`toggle` /
  `cycle` / `system-aware`). Currently every mode uses the same
  visual treatment; the axis is reserved so brand themes can layer
  per-mode tweaks (e.g. a wider button on the system-aware mode that
  carries an extra status indicator).
- Outline-button shape (border + background + shadow) so the toggle
  reads against any background colour.
- `motion-reduce:transition-none` so users with reduced-motion
  preference see an instant state swap rather than the colour fade.

## Usage: Basic Example

```ts
import { themeToggleVariants } from "@suaveplan/react-ui/components/theme-toggle/theme-toggle";

const className = themeToggleVariants({ mode: "toggle" });
```

## Usage: Advanced Example

```ts
import { defineVariants } from "@suaveplan/react-ui/variants";
import type { ThemePlugin } from "@suaveplan/react-ui";

const brandTheme: ThemePlugin = {
    name: "brand",
    tokens: { /* ... */ },
    variantOverrides: {
        ThemeToggle: defineVariants("ThemeToggle", "rounded-full p-0", {
            variants: { mode: { toggle: "", cycle: "", "system-aware": "w-12" } },
            defaultVariants: { mode: "toggle" },
        }),
    },
};
```

## API Reference

- `themeToggleVariants({ mode })`: returns the merged class string.

## Implementation Notes

The empty `mode` variants are intentional — the chassis ships ONE
visual treatment so the cross-mode UX feels identical across the
three modes. The axis is present at the cva level so brand themes do
not have to introduce their own discriminator when they want
per-mode treatment; they declare an override on
`themeToggleVariants` and continue to receive the chassis-managed
`mode` prop. Reserving the axis up-front also means consumers do not
have to re-declare the prop on a per-pack basis when a custom
treatment is needed: the override mechanism in the theme plugin
contract takes care of slotting the brand-specific variants into the
existing prop surface, so the consumer call site stays identical.