img-alt-quality
<img> alt text must be appropriate (manual review)
Flags <img> elements with non-empty alt text for human review of appropriateness, and says when the alt looks like a file name, a web address, a placeholder, an "image of" opening or is very long.
Applies to. Applies to <img> elements whose alt attribute is present and non-empty. The element must be included in the accessibility tree, and a role attribute resolving to presentation/none (its first token naming a known role, matched case-insensitively) takes it out of scope unless it is focusable, which restores its role. An <img> with no alt at all is img-alt-present's failure, and one with alt="" is img-alt-decorative's review.
Expectation. Human review is required to confirm that the provided text alternative is accurate and appropriate. Alt text that looks like something other than a description gets its own summary and hint: a file name (or alt equal to the image's own file name), a web address, only symbols (such as "★★★★☆"), a placeholder or generic word such as "image" or "TBD", an opening that says it is an image ("image of", "photo of"), or alt longer than 150 characters. Every finding is still cantTell: each of these can be right in context.
What a finding reports.
altSignal: what made the alt text look suspicious, on those findings only:file-name,url,symbols,placeholder,redundant-prefixortoo-long. Absent on a finding with ordinary alt text. When several apply, the first in that order is reported.length: the alt text's length in characters, ontoo-longonly.limit: the length above which alt counts as too long (150), ontoo-longonly.reasonCode:IMAGE_ONLY_CONTROL_CONTENTwhen the image is the only content of a link or button (no text and no other image in it), so its alt is the control's name (H30), withcontrolContentnaming the control's role (linkorbutton);TEXT_ALTERNATIVE_REVIEWotherwise.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<img src="chart.png" alt="image">
Non-empty alt is present, but "image" restates the element type instead of describing what the chart shows. The finding says the alt is a placeholder or a generic word (data.details.altSignal: "placeholder"), as it does for a file name, a web address, an "image of" opening or alt over 150 characters.
<img src="team.jpg" alt="Our support team at the 2025 meetup">
Ordinary alt text gets the general review: only a person can tell whether it describes the image well in context.
<img src="border.png" alt="">
Empty alt marks the image decorative; that's img-alt-decorative's question, not this rule's.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
IMAGE_ONLY_CONTROL_CONTENT
- Find the link or button the report names; the image is its only content, so its alt is the control's name.
- Read the alt text, then activate the control or check its destination to learn what it does.
- Decide whether the alt says what the control does ("Search", "Home"), not what the image looks like.
Pass. The alt text states the control's purpose or destination.
Fail. The alt text does not say what the control does, for example a file name, address, generic word or symbols, which fails WCAG 1.1.1 (H30, F30).
TEXT_ALTERNATIVE_REVIEW
- Find the image the report names and read its alt text (the report gives the reason it looked suspect, if any).
- Look at the image and its context, and ask what it shows that matters to the page.
- If the text alternative only names the image, as is common for charts and diagrams, the details may be given elsewhere: in a caption, text or a table next to it, or a link beside it. That counts only if a screen reader user can find it from the image and it gives everything the image shows.
- Decide whether the alt says what matters, or names the image while that description gives the rest; a file name, web address or generic word such as "image" does neither.
Pass. The alt text conveys what the image shows that a user needs, or it names the image and a description a screen reader user can reach from it gives the rest.
Fail. Neither the alt text nor a description reachable from the image conveys the image's content (for example the alt is a file name, address or generic word), which fails WCAG 1.1.1 (F30).