# Avatar

> A person or entity at a glance — a photo, or initials when there is none.

- **Level**: atom · **Status**: stable · **Role**: content
- **Import**: `import { Avatar } from "@rrios-forge/ui/atoms/avatar";`
- **Source**: `packages/ui/src/atoms/avatar`

Image-with-fallback identity primitive. Composes `@radix-ui/react-avatar` so the fallback shows while the image loads (and stays if the image errors). `alt` is required; pass `alt=""` only when the avatar is decorative and the surrounding text already names the entity.

## Use it for

- Avatar / badge / separator / icon → `Avatar` / `Badge` / `Separator` / `Icon`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` `xl` | `md` | Ergonomic scale, in three families (control, text, container). |
| `kind` | — | `person` `entity` | — | What an avatar stands for — a person (round) or an entity such as a workspace or brand (rounded square) (ADR-039). |
| `shape` | — | `circle` `rounded` | — | Geometry, where geometry is the meaning. |

## Stories

- [Playground](/?path=/story/components-atoms-avatar--playground) · frame: `/iframe.html?id=components-atoms-avatar--playground&viewMode=story`
- [Sizes](/?path=/story/components-atoms-avatar--sizes) · frame: `/iframe.html?id=components-atoms-avatar--sizes&viewMode=story`
- [Kinds](/?path=/story/components-atoms-avatar--kinds) · frame: `/iframe.html?id=components-atoms-avatar--kinds&viewMode=story`
- [With image](/?path=/story/components-atoms-avatar--with-image) · frame: `/iframe.html?id=components-atoms-avatar--with-image&viewMode=story`
- [Fallback](/?path=/story/components-atoms-avatar--fallback) · frame: `/iframe.html?id=components-atoms-avatar--fallback&viewMode=story`
- [Group](/?path=/story/components-atoms-avatar--group) · frame: `/iframe.html?id=components-atoms-avatar--group&viewMode=story`

## Decisions that name it

- ADR-013 — PageShell: mobile-nav polymorphism
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).