first commit

docs/ui/react/react-ui/src/components/aspect-ratio/aspect-ratio.variants.md

@@ -0,0 +1,55 @@
+# AspectRatio Variants (cva config)
+
+## Purpose
+
+`aspectRatioVariants` is the cva (class-variance-authority) configuration powering the `<AspectRatio>` outer wrapper. It is split from `aspect-ratio.tsx` into its own module so an ejected source copy under `npx shadcn@latest add @suaveplan/aspect-ratio` keeps the cva configuration in a dedicated file. Theme overrides flow through `useThemedVariants("AspectRatio")`.
+
+The cva is intentionally minimal — no axes, no parameters. Radix already constrains the inner box via inline `padding-bottom`, so the only chassis decision is the structural wrapper recipe (`relative w-full overflow-hidden`).
+
+## Features
+
+- Single class string: `relative w-full overflow-hidden`.
+- `relative` so embedded `absolute inset-0` children (iframes) anchor correctly.
+- `w-full` so the wrapper fills the parent width by default; consumers can override.
+- `overflow-hidden` so rounded corners on the wrapper clip embedded media cleanly.
+- NEVER carries a numeric `z-index` (stacking is managed by the surrounding overlay primitive).
+
+## Usage: Basic Example
+
+```ts
+import { aspectRatioVariants } from "@suaveplan/react-ui";
+
+const className = aspectRatioVariants();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { aspectRatioVariants, cn } from "@suaveplan/react-ui";
+
+export function CustomMediaTile() {
+    return (
+        <div
+            className={cn(
+                aspectRatioVariants(),
+                "rounded-2xl border-2 border-primary"
+            )}
+            style={{ aspectRatio: "16 / 9" }}
+        >
+            …
+        </div>
+    );
+}
+```
+
+## API Reference
+
+### `aspectRatioVariants(): string`
+
+Returns the chassis wrapper class string. No arguments — the variant config has no axes.
+
+## Implementation Notes
+
+- The cva exists primarily so a `ThemePlugin` may declare an override via `variantOverrides.AspectRatio` to swap the recipe (e.g. add `rounded-md` by default in a "soft" theme variant). When no theme override is registered, the base recipe is returned verbatim.
+- Per the shadcn skill rule, the cva NEVER assigns a numeric `z-index`. Radix's primitive does not portal the box, so stacking remains under the consumer's surrounding layout.
+- The cva does not include `block` because Radix's primitive renders an inline-styled `<div>` that already lays out as a block element.