first commit

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

@@ -0,0 +1,52 @@
+# Empty Variants
+
+## Purpose
+
+`emptyVariants` is the cva config that powers the `<Empty>` chassis component (with `emptyHeaderVariants`, `emptyMediaVariants`, `emptyTitleVariants`, `emptyDescriptionVariants`, and `emptyContentVariants` for the sub-components). The root `Empty` exposes a `size` axis with three rungs (`sm` / `default` / `lg`) that control vertical breathing room — `sm` for tight surfaces (drawers, compact cards), `default` for typical empty states, `lg` for full-page empties.
+
+## Features
+
+- Single `size` axis with three rungs (`sm` / `default` / `lg`) on `emptyVariants` — controls gap and padding in lockstep.
+- `<EmptyMedia>` renders a `size-12 rounded-full bg-muted` circle so the icon / illustration sits naturally on the surface.
+- `<EmptyTitle>` is `text-lg font-semibold leading-none tracking-tight`; `<EmptyDescription>` is `text-sm text-muted-foreground max-w-prose` for readability.
+- `<EmptyContent>` is `flex flex-wrap items-center justify-center gap-2` so action buttons stack on narrow viewports.
+
+## Usage: Basic Example
+
+```tsx
+import { emptyVariants } from "@suaveplan/react-ui";
+
+const sm = emptyVariants({ size: "sm" });
+const default_ = emptyVariants();
+const lg = emptyVariants({ size: "lg" });
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { cva } from "class-variance-authority";
+import { emptyVariants } from "@suaveplan/react-ui";
+
+const fullScreenEmpty = cva(
+    [emptyVariants({ size: "lg" }), "min-h-[60vh]"].join(" ")
+);
+```
+
+## API Reference
+
+### `emptyVariants(opts?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Vertical breathing room — controls gap + padding. |
+
+### Sub-component cvas
+
+`emptyHeaderVariants()`, `emptyMediaVariants()`, `emptyTitleVariants()`, `emptyDescriptionVariants()`, `emptyContentVariants()` — no options.
+
+## Implementation Notes
+
+- The `size` axis affects only `gap` and `p` on the root container. Sub-component cvas have no axes because their relative spacing is consistent across all empty-state sizes.
+- `<EmptyMedia>` uses `bg-muted text-muted-foreground` so any lucide icon child inherits the muted foreground colour automatically. Consumers wanting a coloured media slot override at the call site (`<EmptyMedia className="bg-emerald-500/10 text-emerald-600">`).
+- `<EmptyDescription>` uses `max-w-prose` so long descriptions wrap at a comfortable read width rather than spanning the full container.
+- `<EmptyContent>` uses `flex-wrap` so action buttons stack vertically on narrow viewports rather than overflow horizontally.