Avatar component

The visual representation of a person or entity — photo with initials and generic-icon fallbacks, a size scale, optional presence indicator — plus the overlapping avatar group (face pile) with a "+N" overflow. Modeled after Atlassian Avatar / AvatarGroup. Used by comments, assignees, timelines, member lists, and topbars across Koder.

Status: v0.1.0 — Draft. Promoted from the Atlassian Design parity scan (metadocsstack #088). Source: https://atlassian.design/components/avatar/ + https://atlassian.design/components/avatar-group/

R1 — Content fallback chain

A single avatar resolves its content in strict priority:

  1. photo (when available + loaded);
  2. initials — 1–2 letters derived from the entity name (R5);
  3. generic icon — a neutral person/entity glyph when no name.

A broken/slow image falls back to initials, never a broken-image box.

R2 — Shape & size

  • Circle for people; rounded-square for non-person entities

    (teams, orgs, apps) — shape disambiguates kind.

  • Size is a token scale (xssmmdlgxl); initials and any

    presence dot scale with it. No arbitrary pixel sizes.

R3 — Presence indicator (optional)

  • A small status dot/ring (online / away / busy / offline) may overlay a

    corner. Status is conveyed by icon/shape + position, not color alone (WCAG 1.4.1); the dot reuses specs/components/badges.kmd geometry.

R4 — Deterministic initials background

The initials background color is derived deterministically from the entity id/name (stable per identity, identical across surfaces and renders) — never random per render. The palette comes from Verge tokens and meets text-contrast on the fill.

R5 — Avatar group (overlapping / face pile)

  • N avatars overlap left-to-right by a fixed token offset; stacking order

    is stable (deterministic, not render-order).

  • Beyond a max, collapse the remainder into a trailing "+N" counter

    avatar; activating it opens a list (specs/components/lists.kmd) / popover of the full set.

  • The group keeps a single, predictable reading order.

R6 — Accessibility

  • Each avatar has an accessible name = the entity's name; when the name is

    already adjacent (a comment header), the avatar image is decorative (alt="").

  • An avatar group announces its membership and overflow: "5 people: Ana,

    Bruno, Carla and 2 more".

  • The "+N" control is a real button (keyboard-focusable) that reveals the

    rest.

R7 — i18n

  • Initials derivation is locale-aware (handles multi-byte names, RTL,

    mononyms); never assumes "first letter of first + last word" universally.

  • "+N" / "N more" uses locale number formatting + ICU plural per

    specs/i18n/contract.kmd.

Não-escopo

  • Profile cards / hovercards (a separate surface that may contain an

    avatar).

  • Identityauth (`specsauth/oauth-flow.kmd`); avatar is presentation only.
  • Image upload/cropping (a product flow).