Role and semantics
Section titled “Role and semantics”- The root carries
role="img"and is named witharia-label. The name is thenamevalue; a status follows in brackets: “User 1 (online)”. - When the name is empty the name is “Person” or “Company” (
ui.avatar.person,ui.avatar.company). - The picture has an empty
alt, so the name is not read twice. The initials and the status dot sit insiderole="img", so they are not read on their own. decorativemakes the rootaria-hiddenand removes its role and name. Use it only when the name is printed beside the avatar; the status is then not announced.Avatar.Groupis a namedgroup; the “+N” count hasrole="img"and the name “2 more”.
Keyboard
Section titled “Keyboard”Avatar is not interactive; it takes no tab stop and ignores keys. To make it clickable, put it inside a link or a button.
Avatar takes no focus. Inside a link, the focus ring belongs to that link.
Screen reader output
Section titled “Screen reader output”| Example | Read |
|---|---|
name="User 1" |
“User 1, image” |
name="User 1" status="online" |
“User 1 (online), image” |
name="" |
“Person, image” |
decorative |
Not read |
Group, max={3}, 5 people |
“Team, group”; three names; “2 more, image” |
The initials and the status dot are not read separately.
Contrast
Section titled “Contrast”Initials use the status tone tokens; they are at least 4.5:1 in every brand and mode (values computed from the bigbang and fixture output).
| Pair | Light mode | Dark mode |
|---|---|---|
color-status-neutral-foreground / color-status-neutral-background |
7.81:1 | 10.22:1 |
color-status-brand-foreground / color-status-brand-background |
7.53:1 | 9.13:1 |
color-status-info-foreground / color-status-info-background |
8.09:1 | 7.60:1 |
color-status-success-foreground / color-status-success-background |
6.51:1 | 8.03:1 |
color-status-warning-foreground / color-status-warning-background (lowest) |
6.46:1 | 8.58:1 |
color-status-danger-foreground / color-status-danger-background |
6.79:1 | 7.19:1 |
color-status-success-emphasis / color-surface-default (dot, lowest) |
4.86:1 | 6.15:1 |
color-text-default / color-surface-layer-2 (“+N” count) |
14.40:1 | 13.49:1 |
The status dot must reach 3:1 (WCAG 1.4.11); it is above 4.86:1 in every state. The dot colour never carries information alone: the offline dot is hollow and the state is written in the accessible name.
WCAG 2.2
Section titled “WCAG 2.2”| Criterion | How Avatar meets it | What the product team does |
|---|---|---|
| 1.1.1 Non-text content | The root carries the name; the picture’s alt is empty. |
Give the real, full name; use decorative when the name is printed beside it. |
| 1.3.1 Info and relationships | The status is part of the accessible name; the group has the group role. |
Give the group an aria-label. |
| 1.4.1 Use of colour | The offline dot is hollow; the state is written in the name. | When the status matters, write it as text beside the avatar. |
| 1.4.3 Contrast (minimum) | Initials are at least 6.46:1. | Do not change the fallback colours with className. |
| 1.4.11 Non-text contrast | The status dot is at least 4.86:1. | - |
| 2.5.8 Target size | Avatar is not a target. | If you make it clickable, keep the wrapping link above 24 px (the smallest avatar is 24 px). |