# 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).