Avatar component

components specs/components/avatar.kmd

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.

When this spec applies

Primary triggers

All triggers

Component — Avatar

Status: v0.1.0 — Draft. Promoted from the Atlassian Design parity scan (meta/docs/stack #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 (xs/sm/md/lg/xl); 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).
  • Identity/auth (specs/auth/oauth-flow.kmd); avatar is presentation only.
  • Image upload/cropping (a product flow).

References