Writing Alt Text That Passes a Manual Review, Not Just axe

Run an automated accessibility scanner against most product pages and it will tell you the images “pass.” Put a screen reader on the same page and you’ll often hear something very different: alt="IMG_04521.jpg", alt="image", or a product photo whose alt text is just the words “product image” repeated forty times down a category grid. The scanner isn’t wrong, exactly — it’s answering a narrower question than the one that actually matters.

Quick answer: Automated tools like axe-core check whether an <img> has some text alternative (an alt attribute, aria-label, or aria-labelledby) — not whether that text is accurate, useful, or appropriately concise. WCAG 2.1’s actual requirement (Success Criterion 1.1.1, Non-text Content) is that the text alternative “serves the equivalent purpose” of the image — a bar that presence-checking alone can’t verify. Closing that gap is a manual review task, not something you can automate away.

This article covers technical accessibility practice, not legal advice — it explains what WCAG 2.1 AA requires for alt text and how to meet it, not whether your specific site carries legal risk.

What axe-core’s alt text check actually does

axe-core’s image-alt rule — the one that fires when an image is missing a text alternative — looks for one of a specific set of conditions: an alt attribute, an aria-label, an aria-labelledby reference, or a role="presentation"/role="none" marking the image as decorative. If any of those is present (and not just whitespace), the rule passes. That’s the whole check. The rule’s own source doesn’t — and structurally can’t — evaluate whether the string inside alt="" describes the image, because “does this text accurately describe this picture” isn’t a question a DOM parser can answer. That’s true of every automated accessibility tool, not a defect specific to axe.

This is why a site can have zero axe violations on alt text and still fail actual screen reader users. alt="image" passes. alt="DSC_20260315_142.png" passes. alt="Product image product image" pasted across an entire category page by a CMS export template passes, every single time, because the attribute is non-empty.

The scale of the underlying problem is well documented even before you get to the quality question. The WebAIM Million 2026 report, an annual automated scan of the top one million home pages, found that 53.1% of home pages had at least one image with missing alternative text, and 16.2% of all images sampled had no alt attribute at all. Nearly half of those missing-alt images were inside links — meaning a screen reader user tabbing to them hears nothing that identifies where the link goes. That’s the presence problem. The quality problem — alt text that exists but doesn’t help anyone — sits on top of it and doesn’t show up in that kind of scan at all.

The three questions that actually determine correct alt text

The W3C’s own alt text decision tree reduces this to a small number of real questions, and getting the category right matters more than wordsmithing the description:

• Is the image purely decorative (a background flourish, a divider, a stock photo that adds no information beyond what nearby text already says)? Give it alt="" — not a missing attribute, an empty one. That tells assistive technology to skip it silently. A missing attribute, by contrast, can leave a screen reader falling back to the filename or the linked URL to try to be helpful — which is worse than saying nothing at all, per WebAIM’s own guidance on this exact failure mode.
• Is the image functional — is it the only content inside a link or button? Then the alt text describes what happens when it’s activated, not what the image looks like. A magnifying-glass icon that opens search gets alt="Search", not alt="magnifying glass icon".
• Is the image informative — does it convey content a sighted user gets that a non-sighted user otherwise wouldn’t? Then it needs a real, brief description of the meaning it conveys, not a caption of its visual composition.

WCAG 2.1’s Success Criterion 1.1.1 backs this with an explicit list of what counts as a failure, not just a pass/fail on presence — including using “text alternatives that are not alternatives,” and the W3C’s own understanding document names filenames and placeholder text as the textbook example. An attribute that’s technically populated with img_4521.jpg still fails the actual standard, even though it will pass axe.

What a manual review catches that a scanner never will

This is the part of an audit that’s genuinely a human task, not a corner we’re cutting on automation. A person operating a real screen reader through a site catches things like:

• Decorative images marked as informative, cluttering navigation with noise — every icon and divider narrated on a page that’s already long enough to navigate by keyboard.
• Product photos with generic or repeated alt text (“Product image,” “Item photo”) across an entire grid, which is functionally the same as no alt text for anyone trying to tell products apart by ear.
• Images of text — a promotional banner or a size chart rendered as a single image — where the alt text summarizes the graphic’s vibe (“Sale banner”) instead of including the actual text a sighted shopper reads (“20% off orders over $75, code SAVE20, ends Sunday”).
• Functional images with descriptive-instead-of-functional alt text — a trash-can icon on a cart line item labeled alt="trash can" instead of alt="Remove item from cart", which tells a screen reader user what the icon looks like but not what pressing it does.
• Redundant alt text next to visible captions — an image whose full description already appears as a caption directly below it, so the informative alt text should actually be empty (alt="") to avoid saying the same thing twice.

None of these trip an automated rule, because in every case the alt attribute is present and non-empty. The failure is about whether that content does its job — judging that requires a person who understands both the image and what a screen reader user needs to hear.

A practical checklist before you ship

For each image on a page, in order:

1. Decide the category first — decorative, functional, or informative. Most bad alt text comes from skipping this and describing the image regardless of its role.
2. Decorative → alt="". Not omitted, not a single space — an explicit empty string.
3. Functional (icons, linked thumbnails, buttons) → describe the action or destination, not the appearance.
4. Informative → describe the meaning, briefly. WebAIM’s guidance puts this at a few words to a short sentence. Skip “image of,” “picture of,” and filenames — they add length without adding information.
5. Images of text → include the actual text. A screen reader user should get the sale terms or size-chart values, not a description of the graphic containing them.
6. Read every image in the order a screen reader would announce them, out loud, before calling it done. This one step catches the repeated-generic-text and wrong-category problems faster than anything else here.

FAQ

Does axe-core (or WAVE, or Lighthouse) check whether alt text is accurate? No. These tools check for the presence of a text alternative — an alt attribute, aria-label, or equivalent — not its content. Whether that text actually describes the image is outside what any automated DOM-based tool can evaluate.

What’s the difference between a missing alt attribute and alt=""? A missing attribute leaves assistive technology without a defined text alternative at all, which can cause it to fall back to less helpful information like a filename. alt="" is a deliberate, correct signal that an image is decorative and should be skipped silently. They are not interchangeable, even though both can look identical in a rendered page.

How long should alt text be? Long enough to convey the image’s content or function, no longer — WebAIM’s guidance suggests a few words up to a short sentence for most images, reserving longer descriptions for genuinely complex images like charts, where the fuller explanation belongs in nearby page content rather than crammed into the attribute itself.

An automated scan is a starting point, not a finish line

An axe-core pass on alt text tells you every image has something in the attribute — it doesn’t tell you whether that something is useful. Quietramp’s audits pair the automated scan with a real manual pass: a person operating the page by keyboard and screen reader, checking exactly the kind of category and quality issues a scanner structurally can’t see. See a real sample report or check pricing — $890 one-time, $99/month for ongoing re-checks after fixes ship.

---

This is educational content about technical accessibility practice, not legal advice. Meeting WCAG 2.1 AA does not guarantee legal compliance with the ADA or any other law. Consult qualified counsel for legal risk questions.

This article was drafted with AI assistance and reviewed by a person for accuracy before publication.