Aria Label Required
Interactive elements that present no visible accessible name (icon-only buttons, icon-only links, image-only buttons) MUST carry a non-empty `aria-label` (or `aria-labelledby`, or visually-hidden text).…
$ aoe install @community/rule-aria-label-requiredProjection
Always in _index.xml · the agent never has to ask for this.
AriaLabelRequired [rule] v1.0.0
Interactive elements that present no visible accessible name (icon-only buttons, icon-only links, image-only buttons) MUST carry a non-empty aria-label (or aria-labelledby, or visually-hidden text). Without an accessible name, screen-reader users hear 'button' with no context.
Loaded when retrieval picks the atom as adjacent / supporting.
AriaLabelRequired [rule] v1.0.0
Interactive elements that present no visible accessible name (icon-only buttons, icon-only links, image-only buttons) MUST carry a non-empty aria-label (or aria-labelledby, or visually-hidden text). Without an accessible name, screen-reader users hear 'button' with no context.
Checks
- @community/check-aria-label-required
Applies To
@community/type-html-artifact
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Severity
critical
Severity Combination
icon-only button without aria-label → BLOCK (SC 4.1.2 Name, Role, Value)
icon-only link without aria-label → BLOCK (SC 2.4.4 Link Purpose)
aria-label is empty / generic ('button', 'icon') → BLOCK
aria-label present and descriptive → PASS
Failure Mode
Screen-reader users hear 'button' or 'image' with no purpose; voice-control users cannot say 'click X' because X has no name; the artifact fails WCAG Level A conformance.
Remediation
- Add a meaningful aria-label:
<button aria-label='Close dialog'>×</button>. - Prefer visually-hidden text for screen-reader-only labels:
<button><span class='sr-only'>Close</span><svg ...></button>. This survives translation tooling that ignores aria attrs. - For toggle buttons, include the state:
aria-label='Mute audio'plusaria-pressedrather than swapping the label string. - For decorative icons inside a labeled button, mark the SVG with
aria-hidden='true'so the icon does not double the announcement.
Exceptions
- Case: Decorative icon adjacent to text label
- Allowed When: The button already has visible text; the icon is decorative — mark
aria-hidden='true'on the SVG.
Loaded when retrieval picks the atom as a focal / direct hit.
AriaLabelRequired [rule] v1.0.0
Interactive elements that present no visible accessible name (icon-only buttons, icon-only links, image-only buttons) MUST carry a non-empty aria-label (or aria-labelledby, or visually-hidden text). Without an accessible name, screen-reader users hear 'button' with no context.
Checks
- @community/check-aria-label-required
Applies To
@community/type-html-artifact
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Severity
critical
Severity Combination
icon-only button without aria-label → BLOCK (SC 4.1.2 Name, Role, Value)
icon-only link without aria-label → BLOCK (SC 2.4.4 Link Purpose)
aria-label is empty / generic ('button', 'icon') → BLOCK
aria-label present and descriptive → PASS
Failure Mode
Screen-reader users hear 'button' or 'image' with no purpose; voice-control users cannot say 'click X' because X has no name; the artifact fails WCAG Level A conformance.
Remediation
- Add a meaningful aria-label:
<button aria-label='Close dialog'>×</button>. - Prefer visually-hidden text for screen-reader-only labels:
<button><span class='sr-only'>Close</span><svg ...></button>. This survives translation tooling that ignores aria attrs. - For toggle buttons, include the state:
aria-label='Mute audio'plusaria-pressedrather than swapping the label string. - For decorative icons inside a labeled button, mark the SVG with
aria-hidden='true'so the icon does not double the announcement.
Exceptions
- Case: Decorative icon adjacent to text label
- Allowed When: The button already has visible text; the icon is decorative — mark
aria-hidden='true'on the SVG.
Relations
related: [@community/rule-link-purpose-clear, @community/rule-button-type-explicit, @w3c/source-wcag-22] see-also: [@community/check-aria-label-required] validates-with: [@w3c/source-wcag-22]
Applies To
@community/type-html-artifact
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Severity
critical
Validates With
- @w3c/source-wcag-22
Severity Combination
icon-only button without aria-label → BLOCK (SC 4.1.2 Name, Role, Value)
icon-only link without aria-label → BLOCK (SC 2.4.4 Link Purpose)
aria-label is empty / generic ('button', 'icon') → BLOCK
aria-label present and descriptive → PASS
Failure Mode
Screen-reader users hear 'button' or 'image' with no purpose; voice-control users cannot say 'click X' because X has no name; the artifact fails WCAG Level A conformance.
Remediation
- Add a meaningful aria-label:
<button aria-label='Close dialog'>×</button>. - Prefer visually-hidden text for screen-reader-only labels:
<button><span class='sr-only'>Close</span><svg ...></button>. This survives translation tooling that ignores aria attrs. - For toggle buttons, include the state:
aria-label='Mute audio'plusaria-pressedrather than swapping the label string. - For decorative icons inside a labeled button, mark the SVG with
aria-hidden='true'so the icon does not double the announcement.
Exceptions
- Case: Decorative icon adjacent to text label
- Allowed When: The button already has visible text; the icon is decorative — mark
aria-hidden='true'on the SVG.
See Also
- @community/check-aria-label-required
Source
aoe-engine/examples/frontend-design/primes/compiled/@community/rule-aria-label-required/atom.yaml