Avatar

1import { Avatar, AvatarStack } from '@/ui/Display'23<Avatar name="Ada Lovelace" src={user.avatarUrl} size="md" status="online" />45<AvatarStack people={reviewers} max={4} size="sm" />67// The fallback chain IS the component. A broken-image icon must never reach8// the screen, and it is the browser's default for a failed src.9function Avatar({ name, src, size }: AvatarProps) {10  const [failed, setFailed] = React.useState(false)11  const showImage = src && !failed1213  return (14    <span role="img" aria-label={name} className={cls(size)}>15      {showImage ? (16        <img src={src} alt="" onError={() => setFailed(true)} />17      ) : (18        initials(name) || <UserIcon aria-hidden />19      )}20    </span>21  )22}2324// Names do not split reliably. "van der Berg", "李", a mononym — take the25// first grapheme of the first and last parts and accept one character.26function initials(name: string) {27  const parts = name.trim().split(/\s+/).filter(Boolean)28  if (parts.length === 0) return ''29  const first = [...parts[0]][0] ?? ''30  const last = parts.length > 1 ? ([...parts[parts.length - 1]][0] ?? '') : ''31  return (first + last).toUpperCase()32}3334// Colour aids scanning; it is never the identity. Two people will collide.35function hue(name: string) {36  let h = 037  for (const ch of name) h = (h * 31 + ch.codePointAt(0)!) % VIZ_COLORS.length38  return VIZ_COLORS[h]39}

<!-- With an image: the name is the alt text, never "avatar". -->
<span class="ds-avatar ds-avatar--md">
  <img src="/u/ada.jpg" alt="Ada Lovelace" />
</span>

<!-- Initials: role="img" with a label, because "A L" identifies nobody. -->
<span class="ds-avatar ds-avatar--md" role="img" aria-label="Grace Hopper"
      style="--avatar-bg: color-mix(in oklab, var(--p-viz-3) 22%, transparent)">
  <span aria-hidden="true">GH</span>
</span>

<!-- Beside the name, the avatar is duplication: hide it. -->
<div class="ds-row">
  <span class="ds-avatar" aria-hidden="true"><img src="/u/ada.jpg" alt="" /></span>
  <span>Ada Lovelace</span>
</div>

<!-- Presence needs a text equivalent. -->
<span class="ds-avatar">
  <img src="/u/ada.jpg" alt="Ada Lovelace" />
  <span class="ds-avatar__status" data-status="online">
    <span class="sr-only">Online</span>
  </span>
</span>

<!-- One announcement for the group, not six. -->
<span class="ds-avatar-stack" role="img"
      aria-label="Ada, Grace, Alan and 3 others">…</span>

.ds-avatar {
  position: relative;
  display: inline-grid;
  place-items: center;
  flex: 0 0 auto;
  border-radius: 999px;              /* circles are people */
  /* An alpha tint, so the same avatar lifts off a card and a drawer as
     readily as off the page. Mixing toward a surface token freezes it at one
     rung and inverts everywhere else. */
  background: var(--avatar-bg, var(--ds-layer-active));

  /* The hue identifies the person from the FILL. Read as text it measures
     3.9-4.4:1 across the eight, because the viz ramp is tuned for fills. */
  color: var(--ds-fg);
  font-weight: 600;                  /* initials are small and need it */
  overflow: hidden;
  user-select: none;
}

/* Rounded squares are organisations, repositories and projects. */
.ds-avatar--square { border-radius: var(--radius-md); }

/* Scales with the avatar rather than stepping, so 20px and 56px read as the
   same component. */
.ds-avatar { font-size: calc(var(--avatar-size) * 0.4); }

.ds-avatar img {
  inline-size: 100%;
  block-size: 100%;
  object-fit: cover;                 /* never squash a non-square photo */
}

/* The ring separates the dot from an unpredictable background. */
.ds-avatar__status {
  position: absolute;
  inset-block-end: 0;
  inset-inline-end: 0;
  inline-size: calc(var(--avatar-size) * 0.28);
  block-size: calc(var(--avatar-size) * 0.28);
  border-radius: 999px;
  box-shadow: 0 0 0 2px var(--ds-surface);
}
.ds-avatar__status[data-status='online'] { background: var(--ds-success); }
.ds-avatar__status[data-status='away']   { background: var(--ds-warning); }
.ds-avatar__status[data-status='busy']   { background: var(--ds-danger); }

/* A third of overlap: enough to read as a group, enough to stay separable. */
.ds-avatar-stack { display: inline-flex; }
.ds-avatar-stack > * + * { margin-inline-start: -33%; }
.ds-avatar-stack > * {
  box-shadow: 0 0 0 2px var(--ds-surface);
  /* First on top, so reading order matches visual order. */
  position: relative;
}