In one paragraph
Elements with role img or a supported image-role alias need an appropriate accessible name when they communicate information. A role makes a semantic promise; it does not turn arbitrary descendant text into a reliable name. Describe the graphic using a supported naming mechanism, or use a different treatment for decoration. Inspect the computed accessibility output and preserve any necessary interactive structure.
Why it matters
An image role can group glyphs, CSS artwork, or several elements into one graphic. That can be useful for a static rating or icon, but users need its meaning rather than just an image announcement. A four-star graphic might communicate a rating, not the literal names of four Unicode characters.
The role can flatten descendant semantics. Do not apply it to a container whose child links or controls must remain independently operable. A short name is also not a complete equivalent for complex chart data or a detailed diagram.
Role vocabulary and support evolve. The source rule recognises img and image; newer alias definitions and browser support should not be described as universally identical. Use an implementation appropriate to supported clients and distinguish a draft specification from a stable interoperability guarantee.
How WebAuditOS evaluates this finding
The supplied role-img-alt rule inspects applicable visible non-SVG elements with its recognised image roles, excluding native element types handled by other checks. Supported ARIA labels, labelled-by references, or title fallback can satisfy its name paths. Plain descendant text alone does not satisfy its documented test.
Serious impact maps to high severity. It does not determine whether a role was appropriate, whether the label is truthful, or whether complex information is equivalent. A name-presence result is not a complete image or interaction audit.
How to fix it
- Identify the element's purpose in context: static rating, decorative icon, meaningful status, complex graphic, or interactive group. Do not choose a role merely because a component visually contains artwork.
- For a single informative graphic, provide a concise accurate name. An illustrative static rating is:
<span role="img" aria-label="Rated 4 out of 5">★★★★☆</span>Use actual rating data and keep updates aligned. This example is not a star-selection input; an editable rating needs an appropriate interactive pattern.
- When visible explanatory text already exists, consider a correct aria-labelledby relationship. Keep referenced IDs unique and ensure the resulting name identifies this graphic rather than another repeated instance.
- For decoration, keep equivalent meaning in the surrounding interface and avoid redundant announcements. Hiding the sole content of an otherwise unnamed button is not a valid decorative treatment.
- Use a native img with appropriate alt when that is the natural content format. SVG, object, and image-map elements have their own naming and alternative mechanisms; do not force every type into this rule's pattern.
- Supply additional accessible detail for complex information. A brief image name can identify a chart while adjacent text or data communicates the needed values and conclusions.
- Inspect computed names and keyboard behaviour in actual rendered components. Names can be overridden by ARIA precedence, missing IDs, or conditional output. Test dynamic and responsive variants.
- Rescan the relevant state and manually assess accuracy and equivalent meaning. A generic label such as Icon can clear a naming test without helping anyone understand the content.
What the fix can break
An image role can erase useful descendant relationships. Do not use it as a convenient wrapper around a functional widget.
Repeated component IDs can attach the wrong text to every graphic. Use instance-safe generation or a suitable direct label.
Avoid translating technical role or attribute tokens while localising human-readable names. Keep the accessible message in the content's language and the vocabulary valid.
Questions
Does visible text inside role=img automatically name it?
Not under the supplied name-from-author checks. Use an appropriate explicit naming relationship and inspect the computed result.
Should every decorative glyph receive a name?
No. Avoid redundant announcements when its meaning is already supplied appropriately elsewhere.
Does a short label replace chart data?
Not when the omitted detail is necessary to understand the information. Provide an appropriate equivalent.
Which related checks help?
Review SVG alternatives, image alt, and the automation limits guide.
What severity does this get in the report?
High. An axe finding takes its severity from the impact axe reports for the element that failed, and the report maps critical and serious to high, moderate to medium, minor to low. This rule is declared serious in axe-core, so a failure arrives as high.