Functional Image Alt
An <img> that is the sole content of a <button> or <a> element must have alt text describing the action the control performs, not the visual appearance of the image, so screen readers announce an actionable label (WCAG S…
$ aoe install @community/rule-functional-image-altProjection
Always in _index.xml · the agent never has to ask for this.
FunctionalImageAlt [rule] v1.0.0
An that is the sole content of a
Loaded when retrieval picks the atom as adjacent / supporting.
FunctionalImageAlt [rule] v1.0.0
An that is the sole content of a
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Rule
// Question to answer: "What does this button/link DO?" not "What does this image SHOW?"
// ✅ Functional — describes the action
<a href="/"><img src="logo.svg" alt="Go to homepage" /></a>
<button type="submit"><img src="search-icon.svg" alt="Search" /></button>
<a href="/cart"><img src="cart.svg" alt="View shopping cart" /></a>
// ❌ Describes image content, not action
<a href="/"><img src="logo.svg" alt="Company logo" /></a>
<button><img src="search-icon.svg" alt="Magnifying glass icon" /></button>
// ✅ Icon + visible text: alt="" (empty) — the visible text provides the accessible name
<button><img src="cart.svg" alt="" /> View cart</button>
Severity
block
Verification
For every inside a
Tools
- axe-core
- lighthouse
Loaded when retrieval picks the atom as a focal / direct hit.
FunctionalImageAlt [rule] v1.0.0
An that is the sole content of a
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Rule
// Question to answer: "What does this button/link DO?" not "What does this image SHOW?"
// ✅ Functional — describes the action
<a href="/"><img src="logo.svg" alt="Go to homepage" /></a>
<button type="submit"><img src="search-icon.svg" alt="Search" /></button>
<a href="/cart"><img src="cart.svg" alt="View shopping cart" /></a>
// ❌ Describes image content, not action
<a href="/"><img src="logo.svg" alt="Company logo" /></a>
<button><img src="search-icon.svg" alt="Magnifying glass icon" /></button>
// ✅ Icon + visible text: alt="" (empty) — the visible text provides the accessible name
<button><img src="cart.svg" alt="" /> View cart</button>
Severity
block
Verification
For every inside a
Tools
- axe-core
- lighthouse
Relations
related: [@community/rule-aria-label-required, @community/check-aria-label-required, @community/rule-informative-image-alt]
Rationale
Screen readers announce the alt attribute as the button or link name. 'Logo of company' inside a link tells a blind user nothing actionable; 'Go to homepage' does. The alt text substitutes for the image in the context of what the control does — it is the accessible name of the control, not a caption.
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Rule
// Question to answer: "What does this button/link DO?" not "What does this image SHOW?"
// ✅ Functional — describes the action
<a href="/"><img src="logo.svg" alt="Go to homepage" /></a>
<button type="submit"><img src="search-icon.svg" alt="Search" /></button>
<a href="/cart"><img src="cart.svg" alt="View shopping cart" /></a>
// ❌ Describes image content, not action
<a href="/"><img src="logo.svg" alt="Company logo" /></a>
<button><img src="search-icon.svg" alt="Magnifying glass icon" /></button>
// ✅ Icon + visible text: alt="" (empty) — the visible text provides the accessible name
<button><img src="cart.svg" alt="" /> View cart</button>
Severity
block
Verification
For every inside a
Tools
- axe-core
- lighthouse
Source
aoe-engine/examples/frontend-design/primes/compiled/@community/rule-functional-image-alt/atom.yaml