first commit

docs/ui/react/react-ui/src/components/status-badge/status-badge.variants.md

@@ -0,0 +1,55 @@
+# StatusBadge Variants
+
+## Purpose
+
+`statusBadgeVariants` is the cva config that powers the `<StatusBadge>` chassis component. It exposes a `status` axis with five rungs (`success` / `warning` / `error` / `info` / `neutral`) that each pair a translucent background, matching border colour, and a foreground tint that meets WCAG AA against the surface background. The variants module is intentionally separate so an ejected source copy keeps the cva config in a dedicated file.
+
+`StatusBadge` is a **suaveplan-only addition** — shadcn does not ship a `status-badge` registry item upstream (per Wave 3a's reconciliation finding #7).
+
+## Features
+
+- Single `status` axis with five rungs (`success` / `warning` / `error` / `info` / `neutral`).
+- Translucent backgrounds (`bg-{colour}-500/10`) with matching borders (`border-{colour}-500/30`) so the badge reads as a marker, not a button.
+- Dark-mode foreground compensation via `dark:text-{colour}-300`.
+- `transition-colors` + `motion-reduce:transition-none` so reduced-motion users see instant colour changes.
+- `gap-1` baked in so the chassis-injected icon spaces correctly from the label.
+
+## Usage: Basic Example
+
+```tsx
+import { statusBadgeVariants } from "@suaveplan/react-ui";
+
+const success = statusBadgeVariants({ status: "success" });
+const warning = statusBadgeVariants({ status: "warning" });
+const error = statusBadgeVariants({ status: "error" });
+const info = statusBadgeVariants({ status: "info" });
+const neutral = statusBadgeVariants();
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { cva } from "class-variance-authority";
+import { statusBadgeVariants } from "@suaveplan/react-ui";
+
+const blockquoteStatus = cva(
+    [statusBadgeVariants({ status: "info" }), "italic"].join(" ")
+);
+```
+
+## API Reference
+
+### `statusBadgeVariants(opts?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `status` | `"success" \| "warning" \| "error" \| "info" \| "neutral"` | `"neutral"` | Semantic colour pair driving background, border, and foreground. |
+
+Returns the merged class string.
+
+## Implementation Notes
+
+- The default `status` is `neutral` so a `<StatusBadge>` without an explicit status renders as a muted marker (matching the conservative-default convention used elsewhere in the chassis).
+- Translucent backgrounds are `/10` opacity so the badge tints rather than dominates the surrounding surface; `border-{colour}/30` provides a distinct edge without competing visually.
+- Dark-mode foreground tints use `text-{colour}-300` rather than `text-{colour}-700` because the `bg-{colour}-500/10` overlay reads darker on the dark theme's elevated surface.
+- The icon spacing is handled at this level via `gap-1` so the chassis component does not need a separate flex wrapper.