No Icons Without Label
Every icon-only interactive control must expose an accessible name via aria-label, aria-labelledby, or visually-hidden text. Decorative icons inside a labeled control are exempt.
$ prime install @community/constraint-no-icons-without-label Projection
Always in _index.xml · the agent never has to ask for this.
NoIconsWithoutLabel [constraint] v1.0.0
Every icon-only interactive control must expose an accessible name via aria-label, aria-labelledby, or visually-hidden text. Decorative icons inside a labeled control are exempt.
Loaded when retrieval picks the atom as adjacent / supporting.
NoIconsWithoutLabel [constraint] v1.0.0
Every icon-only interactive control must expose an accessible name via aria-label, aria-labelledby, or visually-hidden text. Decorative icons inside a labeled control are exempt.
Target
- icon-only buttons
- icon-only links
- icon-only triggers (menu, toolbar, drawer)
Severity
critical
Values
- Required:
- Required:
- Forbidden: with no label
- Forbidden: aria-label='' (empty label)
- Forbidden: title='…' as the sole accessible name (title is not reliably announced)
Exceptions
- Decorative icons placed alongside visible text inside the same control (the visible text is the name; the SVG should be aria-hidden='true').
- Icons used in a static infographic with adjacent caption text and no interaction.
Approved Alternatives
- Tailwind:
<span class='sr-only'>Label</span>next to the icon for visually-hidden but assistive-tech-readable text. - Add aria-label directly on the
- Use aria-labelledby pointing to a hidden but persistent .
Enforcement
axe-core rule button-name and link-name. Storybook a11y addon. ESLint plugin jsx-a11y jsx-a11y/control-has-associated-label.
Loaded when retrieval picks the atom as a focal / direct hit.
NoIconsWithoutLabel [constraint] v1.0.0
Every icon-only interactive control must expose an accessible name via aria-label, aria-labelledby, or visually-hidden text. Decorative icons inside a labeled control are exempt.
Target
- icon-only buttons
- icon-only links
- icon-only triggers (menu, toolbar, drawer)
Severity
critical
Values
- Required:
- Required:
- Forbidden: with no label
- Forbidden: aria-label='' (empty label)
- Forbidden: title='…' as the sole accessible name (title is not reliably announced)
Exceptions
- Decorative icons placed alongside visible text inside the same control (the visible text is the name; the SVG should be aria-hidden='true').
- Icons used in a static infographic with adjacent caption text and no interaction.
Approved Alternatives
- Tailwind:
<span class='sr-only'>Label</span>next to the icon for visually-hidden but assistive-tech-readable text. - Add aria-label directly on the
- Use aria-labelledby pointing to a hidden but persistent .
Enforcement
axe-core rule button-name and link-name. Storybook a11y addon. ESLint plugin jsx-a11y jsx-a11y/control-has-associated-label.
Rationale
Screen readers announce icon-only buttons as 'button' with no name unless an accessible name is provided. Icon glyphs are opaque to assistive tech (the SVG path data carries no semantics). WCAG 2.2 SC 4.1.2 (Name, Role, Value) makes this a Level A failure — meaning these controls are completely unusable to a non-trivial population.
Source
prime-system/examples/frontend-design/primes/compiled/@community/constraint-no-icons-without-label/atom.yaml