Avatar
Identity marker for a user or entity — a circle at radius.full with its own avatar.bg, avatar.text, and avatar.border silhouette. It shows a photo, initials, or the system user glyph. An avatar identifies; it never acts.
Sizes
The box rides its scales one step light — an avatar is denser than a control at the same nominal size. sm arrived with its consumer, the group stack below.
| Example | Size | Modifier | Box | Usage |
|---|---|---|---|---|
| JV | Small | --sm | size.icon.lg | Group stacks, inline mentions, dense rows |
| JV | Medium | ds-avatar | size.control.sm | The default — table cells, list rows, nav chrome |
| JV | Large | --lg | size.control.md | Profile headers, detail panes |
Surface separation
The dedicated fill and hairline preserve the circle on every standard host surface. On a colored region, put ds-on-surface on the host so Avatar and other surface-valid components inherit that hue's paired context.
Content forms
Exactly one form per instance, by fixed precedence — image, then initials, then the i-user fallback; initials arrive as one or two uppercase characters from the author, never derived or transformed by the component. The photo fills the box at cover fit under the circle's own radius; the fallback glyph rides the icon scale one step light.
| Example | Form | Part | Roles | Usage |
|---|---|---|---|---|
 | Image | __image | radius.full | A photo exists — always preferred |
| JV | Initials | — | control.bgtext.secondary | A name exists, no photo |
| Icon fallback | — | size.icon.smtext.secondary | No photo, no name — the empty rendering |
Group
Overlapping identity stack — its own component (ds-avatar-group) composed of plain avatars: who is involved when listing every name would dominate the row. The gap is a true cutout, not a painted ring — a border.medium crescent masked out of each covered avatar so it shows any surface in both modes — with a constant space.1-5 overlap, the first avatar painting on top (relevance order and paint order agree), a trailing +N chip stating arithmetic, never an identity, and one collective name (role="group" + aria-label) over decorative children.
| Example | Size | Children | Gap | Usage |
|---|---|---|---|---|
| Small | --sm | border.mediumtransparent | The workhorse — table cells, list rows | |
| Medium | ds-avatar | border.mediumtransparent | Cards, detail headers |
Usage notes
An avatar is identity, not a control.
| Verdict | Rule |
|---|---|
| Do | Treat the avatar as decorative next to a visible name — empty alt on the image, aria-hidden="true" on initials and icon forms; standing alone it carries the identity via alt or aria-label. |
| Do | Keep a group to one size, small preferred — a stack runs one size down from the avatars around it — showing three to five before cutting the rest to the count chip. |
| Do | Use the medium avatar as-is in owner and actor table cells — the Table contract already points here; no table-specific sizes. |
| Don’t | Make the avatar or the group interactive — no hover, focus, or click affordance; a clickable avatar or facepile is a wrapper’s job, and expanding the stack is host/L2 behavior. |
| Don’t | Repurpose the i-user fallback for arbitrary glyphs or brand marks — it is component chrome, always aria-hidden. |
| Don’t | Mint per-instance colors — the circle uses its dedicated Avatar roles and the active surface context, never identity-specific decoration. |
| Don’t | Rebuild the stack from loose avatars with hand-tuned margins — the ring and overlap are the contract’s geometry. |