Role and semantics
Section titled “Role and semantics”Badge is a plain <span> with no role of its own; its text is read together with the content around it. Status is never shown by colour alone, and the text carries the meaning on its own.
Keyboard
Section titled “Keyboard”| Key | Behaviour |
|---|---|
| Tab | Badge takes no focus; Tab passes over it. Badge has no keys of its own. |
None. Badge is not in the tab order and shows no focus ring. If an action is needed, use a Button instead of a Badge.
Screen reader output
Section titled “Screen reader output”The text of the Badge is read in the flow with the content around it. An icon passed with startIcon is aria-hidden, so it is not read.
| Example | Read as |
|---|---|
<Badge tone="success">Approved</Badge> |
“Approved” |
<Badge tone="warning" startIcon={...}>Pending</Badge> |
“Pending” (the icon is not read) |
A screen reader only says the status. If the row does not make clear what it belongs to, give context with a table header or aria-describedby. If the status changes while the page is open and people need to hear it, update a separate aria-live region, not the Badge.
Contrast
Section titled “Contrast”Text and background reach at least 4.5:1 in every tone, variant, brand and mode. The values were computed from the token output of the bigbang and fixture brands with the WCAG relative luminance formula: foreground on background for subtle, on-emphasis on emphasis for bold. A test in the token package checks this on every build.
Light mode
| Tone | subtle (lowest over brands) |
bold (lowest over brands) |
|---|---|---|
neutral |
7.81:1 | 6.63:1 |
brand |
7.53:1 | 6.17:1 |
info |
8.09:1 | 6.50:1 |
success |
6.51:1 | 5.03:1 |
warning |
6.46:1 | 4.72:1 |
danger |
6.79:1 | 5.63:1 |
Dark mode
| Tone | subtle (lowest over brands) |
bold (lowest over brands) |
|---|---|---|
neutral |
10.22:1 | 7.14:1 |
brand |
9.13:1 | 8.09:1 |
info |
7.60:1 | 5.88:1 |
success |
8.03:1 | 7.45:1 |
warning |
8.58:1 | 8.00:1 |
danger |
7.19:1 | 6.15:1 |
WCAG 2.2
Section titled “WCAG 2.2”| Criterion | How Badge meets it | What the product team must do |
|---|---|---|
| 1.3.1 Info and relationships | The text is real text; the icon is decorative and aria-hidden. |
If the row does not make clear what the status belongs to, give context with a table header or aria-describedby. |
| 1.4.1 Use of colour | Colour only supports the text; the text carries the status. | Do not leave the text meaningless (“Status”); name the status. |
| 1.4.3 Contrast (minimum) | At least 4.5:1 in every tone, variant, brand and mode; the token test checks it. | Do not set colours with className; they fall outside the token test. |
| 1.4.11 Non-text contrast | The subtle border is decorative; the status is in the text, not the border. |
Do not give the border meaning. |
| 1.4.12 Text spacing | Height is fixed (16 or 20 px); text may overflow if text spacing is enlarged. | Check the screen with enlarged text spacing, especially at size sm. |
| 4.1.2 Name, role, value | Not interactive, so no role is needed; the text is enough. | Do not add role or tabIndex to a Badge. |