first commit

docs/ui/react/react-ui/src/components/theme-toggle/theme-toggle.variants.md

@@ -0,0 +1,64 @@
+# `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.