first commit

docs/ui/react/react-ui/src/components/sonner/sonner.variants.md

@@ -0,0 +1,63 @@
+# `sonner.variants`
+
+## Purpose
+
+Defines the `sonnerToasterVariants` cva slot for the chassis `<Sonner>`
+toaster host. Sonner manages its own stacking, animation, and visual
+treatment via CSS variables (`--toaster-*`); the chassis exposes a
+single empty cva slot so brand themes can inject incidental utility
+classes (safe-area padding, font-stack overrides) without forking the
+underlying library.
+
+## Features
+
+- Single registered cva: `sonnerToasterVariants` keyed `"Sonner"` so
+  `ThemePlugin.variantOverrides.Sonner` can layer brand utilities.
+- Zero default classes — sonner paints itself; the chassis adds
+  nothing by default.
+- Per Wave 3c finding #3, no `z-index` is layered on the host. Sonner
+  uses `position: fixed` with its own `--toaster-z-index` CSS variable.
+
+## Usage: Basic Example
+
+```ts
+import { sonnerToasterVariants } from "@suaveplan/react-ui/components/sonner/sonner";
+
+const className = sonnerToasterVariants();
+```
+
+## 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: {
+        Sonner: defineVariants("Sonner", "pt-safe-top px-2", {
+            variants: {},
+            defaultVariants: {},
+        }),
+    },
+};
+```
+
+## API Reference
+
+- `sonnerToasterVariants(): string` — resolves to the empty base class
+  by default. Returns a stable identity per call.
+
+## Implementation Notes
+
+The empty base intentionally communicates "no chassis-side styling"
+to consumers reading the source. Any future visual treatment (e.g.
+`role="region"`-style backdrops, custom safe-area padding for mobile
+notch devices, or font-stack overrides for non-Latin glyph coverage)
+belongs in the brand theme override or in a sibling cva slot, not on
+this base — sonner's painting must remain authoritative so updates
+to the upstream library do not silently regress the chassis. The
+override path is exercised by the chassis e2e suite, which mounts a
+brand theme and asserts that the `<ol data-sonner-toaster>` host
+carries the merged className.