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

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Values

• • Required:
• • Required:
• • Required: Search
• • 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.

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

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Values

• • Required:
• • Required:
• • Required: Search
• • 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.

Relations

related: [@community/constraint-accessibility-aa-minimum, @community/tool-axe-core, @community/check-focus-visible]

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.