Avatar accessibility

WCAG 2.1 AA requirements

Image alt text

• AvatarImage accepts an alt prop. Always provide a meaningful name (e.g., the person's full name), not a description of the image.
• If the avatar is purely decorative (e.g., next to a visible name), set alt="" so screen readers skip it.

Fallback

• AvatarFallback renders with aria-hidden because the image's alt text (or the adjacent visible name) is the accessible label. The initials are a visual cue only.
• If no AvatarImage is present and the avatar is the only representation of the user, ensure an aria-label is set on the Avatar wrapper.

Contrast

• Fallback text (initials) against the bg-muted background must meet 4.5:1 contrast in both light and dark themes.
• When using custom className overrides on fallback colours, verify contrast manually.

Focus

• Avatars are not interactive by default. If you make an avatar clickable (e.g., linking to a profile), wrap it in an <a> or <button> with a descriptive aria-label.

Audit checklist

• alt text on AvatarImage matches the entity name
• Decorative avatars use alt=""
• Fallback text meets 4.5:1 contrast
• Clickable avatars have an accessible label and focus ring