Avatar

import { Avatar, AvatarSize, StatusIndicatorType } from '@wearables-ui-toolkit/mrbd';

type Person = {
  name: string;
  photoUrl?: string;
  isOnline: boolean;
};

export function PersonAvatar({
  person,
  onlineLabel,
}: {
  person: Person;
  onlineLabel: string;
}) {
  return (
    <Avatar
      src={person.photoUrl}
      alt={person.name}
      size={AvatarSize.MEDIUM}
      statusIndicator={person.isOnline ? StatusIndicatorType.ACTIVE : undefined}
      statusIndicatorLabels={{ [StatusIndicatorType.ACTIVE]: onlineLabel }}
    />
  );
}

<Avatar
  src={thread.participants[0].photoUrl}
  secondarySrc={thread.participants[1].photoUrl}
  alt={thread.title}
  size={AvatarSize.LARGE}
/>

<Avatar
  src={message.sender.photoUrl}
  alt={message.sender.name}
  badgeImageSrc={message.appIconUrl}
  size={AvatarSize.MEDIUM}
/>

import {
  Avatar,
  AvatarShape,
  AvatarSize,
  PlaceholderStyle,
  type IconSource,
} from '@wearables-ui-toolkit/mrbd';

export function AlbumArt({
  artworkUrl,
  albumTitle,
  fallbackIcon,
}: {
  artworkUrl?: string;
  albumTitle: string;
  fallbackIcon: IconSource;
}) {
  return (
    <Avatar
      src={artworkUrl}
      alt={albumTitle}
      size={AvatarSize.XLARGE}
      primaryImageShape={AvatarShape.ROUNDED_RECTANGLE}
      placeholderStyle={PlaceholderStyle.IMAGE}
      placeholderIcon={fallbackIcon}
    />
  );
}

.participants {
  display: flex;
  align-items: center;
  gap: var(--uit-spacing-small);
}

• CIRCLE — fully round primary surface, clipped with a circular radius.
• ROUNDED_RECTANGLE — smooth-corner (squircle) primary surface, clipped with a generated shape path.

• STANDARD — --uit-color-background-elevation2.
• SURFACE — --uit-color-background-surface.
• TRANSPARENT — --uit-color-background-flat.
• TRANSLUCENT — --uit-color-background-track.

• The root element reports role="img" with an accessible name built from alt, plus the label for statusIndicator when one is set, joined with a comma — for example "Ada Lovelace, Active Status".
• Pass a localized alt, and localized statusIndicatorLabels, rather than setting aria-label yourself; the component overwrites aria-label on the root.
• The badge subtree — including the status dot and any badge image — is hidden from assistive technology, so the status reaches screen readers only through the avatar’s accessible name. If a badge image carries meaning, put that meaning in alt or in the parent’s label.
• Placeholder and badge glyphs are decorative and are marked aria-hidden.
• When the avatar is decoration inside a labelled parent — a list row, a chip, a container header — let the parent own the accessible name. This avoids announcing the identity twice.

• Use real imagery for known people and for both halves of a known duo.
• Choose a semantic AvatarSize and let the component derive every metric.
• Use the built-in badge and status slots for supplementary meaning.
• Pass placeholderIcon so an avatar with no photo still reads as a subject.
• Supply a localized alt, plus localized status labels when the defaults do not fit the product.

• Let Avatar own clipping and its badge cutout; a second clipping element can obscure the built-in mask.
• Choose a status indicator or image badge because the slots are mutually exclusive.
• Pair statusIndicatorIcon with statusIndicator; the icon does not render on its own.
• Choose a supported AvatarSize and prevent stretching parents from resizing it. Width, height, and transform overrides bypass the component’s metrics.
• Prefer the built-in duo, badge, and stroke behavior over imitating it with stacked circles, borders, or positioned dots.