Initial Commit

packages/ui/react/react-ui/src/components/avatar/avatar.variants.md

@@ -0,0 +1,55 @@
+# Avatar Variants
+
+## Purpose
+
+`avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>` ride alongside as sub-component cvas). The root `Avatar` exposes a `size` axis with four rungs (`sm` / `default` / `lg` / `xl`) using Tailwind's `size-*` shorthand so width and height stay in lockstep — this prevents the off-by-one ratio bugs that arise when consumers set width and height independently.
+
+## Features
+
+- Single `size` axis with four rungs (`sm` 32px, `default` 40px, `lg` 48px, `xl` 64px) using Tailwind `size-*`.
+- `rounded-full` applied at the root so the surface is always circular regardless of children.
+- `overflow-hidden` clips images that would otherwise leak past the circular edge.
+- `<AvatarImage>` uses `aspect-square h-full w-full object-cover` so portrait / landscape sources crop centrally.
+- `<AvatarFallback>` uses `bg-muted text-muted-foreground` with `uppercase tracking-wider` so user initials read clearly.
+
+## Usage: Basic Example
+
+```tsx
+import { avatarVariants } from "@suaveplan/react-ui";
+
+const small = avatarVariants({ size: "sm" });
+const default_ = avatarVariants();
+const xl = avatarVariants({ size: "xl" });
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { cva } from "class-variance-authority";
+import { avatarVariants } from "@suaveplan/react-ui";
+
+const ringedAvatar = cva(
+    [avatarVariants({ size: "lg" }), "ring-2 ring-primary ring-offset-2"].join(
+        " "
+    )
+);
+```
+
+## API Reference
+
+### `avatarVariants(opts?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` | Diameter — uses Tailwind `size-*` to set width and height together. |
+
+### `avatarImageVariants()`, `avatarFallbackVariants()`
+
+No options — single canonical class strings.
+
+## Implementation Notes
+
+- The chassis uses `size-*` (Tailwind 3.4+) rather than separate `w-*` / `h-*` classes so the avatar's diameter changes in lockstep with the image dimension. This avoids the historical bug where consumers set `w-10 h-12` and produced an ellipse instead of a circle.
+- `AvatarFallback`'s `bg-muted` background reads as a low-contrast surface that does not compete with the image; the muted-foreground initials are scaled at `text-sm` so even the `xl` size renders the initials at a comfortable read size.
+- The `relative` positioning on the root container is required by Radix's image-loading state machine — Radix toggles `<AvatarImage>` opacity via inline styles that depend on the parent's positioning context.
+- `shrink-0` on the root prevents the avatar from shrinking inside flex parents (e.g. inside an `<AvatarGroup>` row or a list item with limited horizontal space).