Role and semantics
Section titled “Role and semantics”Without label, the icon is decoration: it carries aria-hidden="true" and screen readers skip it. With label, it gets role="img" and aria-label; screen readers read it as an image.
An icon inside a Button stays decorative; the control carries the name.
Keyboard
Section titled “Keyboard”| Key | Behaviour |
|---|---|
| Tab | Icon takes no focus; Tab moves past it. Icon has no keys of its own. |
None. Icon is not in the focus order and shows no focus ring. The SVG gets focusable="false", so it takes no focus in older browsers either.
Screen reader output
Section titled “Screen reader output”| Example | Announced |
|---|---|
<Icon name="check" /> |
Nothing is announced |
<Icon name="triangle-alert" label="Warning" /> |
“Warning, image” |
<Button startIcon={<Icon name="download" size="inherit" />}>Download</Button> |
“Download, button” (the icon is not announced) |
Keep label short and let it state what the icon means. If text next to the icon already gives that meaning, skip label; the same information would be read twice.
Contrast
Section titled “Contrast”The default, subtle, danger, success, warning and info tones have at least 3:1 contrast against their surfaces; the test in the tokens package checks these pairs on every build, for every brand and mode. The test uses the page surface (color-surface-default) for color-icon-default and the raised surface (color-surface-raised) for the others.
The brand, inverse and disabled tones are outside this test. disabled is only for disabled states and is exempt from contrast; for brand and inverse, the product team checks contrast against the surface they are used on.
WCAG 2.2
Section titled “WCAG 2.2”| Criterion | How Icon meets it | What the product team does |
|---|---|---|
| 1.1.1 Non-text content | Decorative icons are hidden; label names a meaningful icon. |
Give a label to every icon that carries information alone. |
| 1.3.1 Info and relationships | role="img" announces a meaningful icon as an image. |
Do not give an icon in a control a label; let the control carry the name. |
| 1.4.1 Use of colour | Tone only supports the meaning. | Do not express a state with icon colour alone; add text or a label. |
| 1.4.11 Non-text contrast | Six tones are tested at 3:1 against their surface. | Check contrast for brand, inverse and custom surfaces. |
| 4.1.2 Name, role, value | With label it has a name; without, it leaves the tree. |
Use IconButton for a clickable icon. |