first commit

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

@@ -0,0 +1,54 @@
+# Badge Variants
+
+## Purpose
+
+`badgeVariants` is the cva config that powers the `<Badge>` chassis component. It exposes a `variant` axis with four rungs (`default` / `secondary` / `destructive` / `outline`) that each pair a background colour with a matching foreground text colour, plus a transparent border for the three filled variants and a foreground-coloured border for the outline variant.
+
+The variants module is intentionally separate (`badge.variants.ts`) so an ejected source copy under `npx shadcn@latest add @suaveplan/badge` keeps the cva config in a dedicated file, mirroring the upstream shadcn convention.
+
+## Features
+
+- Single `variant` axis with four rungs (`default` / `secondary` / `destructive` / `outline`).
+- `transition-colors` + `motion-reduce:transition-none` so reduced-motion users see instant colour changes.
+- Focus ring scoped to the badge element so it works as a focusable target when wrapped in an anchor or button.
+- Hover state for filled variants (`hover:bg-{variant}/80`) — outline variant has no hover treatment because it is decorative.
+
+## Usage: Basic Example
+
+```tsx
+import { badgeVariants } from "@suaveplan/react-ui";
+
+const primary = badgeVariants();
+const secondary = badgeVariants({ variant: "secondary" });
+const danger = badgeVariants({ variant: "destructive" });
+const outlined = badgeVariants({ variant: "outline" });
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { cva } from "class-variance-authority";
+import { badgeVariants } from "@suaveplan/react-ui";
+
+const auditBadge = cva(
+    [badgeVariants({ variant: "outline" }), "uppercase tracking-wider"].join(" ")
+);
+```
+
+## API Reference
+
+### `badgeVariants(opts?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `"default" \| "secondary" \| "destructive" \| "outline"` | `"default"` | Colour treatment — primary fill, secondary fill, destructive fill, or transparent outline. |
+
+Returns the merged class string.
+
+## Implementation Notes
+
+- The default `variant` is `default` (primary fill) — overriding the default at the `defineVariants` level keeps the API consistent with every other chassis component.
+- The chassis intentionally does NOT expose a `size` axis because badges are typographic markers — they should match the size of the surrounding text. Larger / more emphatic markers should use `<StatusBadge>` (icon + colour combo) or compose a `<Badge>` inside a sized container.
+- `inline-flex items-center` is applied so badges can contain an icon + label without manual flex setup at the consumer level.
+- `rounded-full` produces the pill shape that distinguishes badges from buttons or chips.
+- The outline variant has `text-foreground` with a default `border` (no `border-{colour}`) so it picks up the active theme's border colour automatically.