# The Alt Text Metric: The Decorative Image Your Scanner Counts as a Failure

Source: https://complymetric.com/blog/2026-11-15-alt-text-metric-decorative-images.html

*Open any accessibility scanner report and the first number you see is usually the alt text count: hundreds of images flagged, most of them decorative. The number looks like a crisis and it is mostly a measurement problem. A decorative image with no alt attribute is a failure under WCAG 2.2 Success Criterion 1.1.1, Non-text Content, because the screen reader announces the file name instead of silence. A decorative image with an empty alt attribute, alt="", is correct, because the screen reader skips it. The difference is eleven characters, and the scanner counts both the same way unless you teach it the difference.*

## Empty alt is a decision, not an omission

The rule is simple and it is the one most teams get backwards. An informative image needs alt text that says what the image shows. A decorative image, a spacer, a background flourish, a stock photo that adds nothing to the content, needs an empty alt attribute so the screen reader skips it. An image with no alt attribute at all is neither: the screen reader does not know it is decorative, so it reads the file name, and the user hears "IMG\_4521.jpg" in the middle of a product description. The fix is not to write alt text for every image. It is to decide, image by image, which ones carry meaning and which ones do not, and to mark the decorative ones empty on purpose.

The WebAIM Million 2025 report keeps finding missing alt text among the most common detectable failures on the pages it scans, and the pattern behind the number is consistent: the failures cluster on images added by content teams, marketing banners, and product galleries, not on images added by developers. The developer's images usually have alt attributes, because the component requires one. The content team's images do not, because the CMS makes the field optional. The metric that matters is not the total count of flagged images. It is the share of images with no alt attribute at all, because those are the ones a screen reader user actually hears.

## Measure the right number

Stop reporting the raw count of images missing alt text and start reporting three numbers instead: images with meaningful alt, images with empty alt on purpose, and images with no alt attribute at all. The third number is the failure count. The second number is the proof that someone made the decision. A site with 500 decorative images marked alt="" and 12 images with no alt attribute is in better shape than a site with 50 flagged images and no empty alts at all, because the first site has a process and the second has a gap. [Empty links and buttons fail the same way](https://complymetric.com/blog/2026-11-10-empty-links-buttons-metric-webaim.md): the scanner counts them, and the count hides the real problem, which is that the control has no name at all. [The 24-pixel target size metric has the same shape](https://complymetric.com/blog/2026-11-13-target-size-metric-24px-wcag-2-5-8.md): a number that looks like a pass until you check what it actually measured.

## Make the CMS ask the question

The durable fix is in the content workflow, not in the code. Make the alt field required in the CMS, with three choices: describe the image, mark it decorative, or explain why it needs no description. A required field with a decorative option forces the decision at the moment the image is added, when the person adding it knows what it shows. A retroactive audit, run months later by someone who has never seen the images, can only guess. The audit will still find failures, because content teams change and fields get skipped, but the failures will be twelve, not five hundred, and twelve is a number a team can fix in an afternoon.

Run the scan, split the count into the three numbers, and fix the no-alt images first. The decorative images with empty alt are not failures. They are the evidence that the process works.

## Frequently asked questions

### What is the difference between missing alt and empty alt?

A missing alt attribute means the image has no alt at all, so the screen reader reads the file name. An empty alt attribute, alt="", tells the screen reader the image is decorative and to skip it. Missing alt is a failure under WCAG 2.2 Success Criterion 1.1.1. Empty alt on a decorative image is correct.

### Do decorative images need alt text?

No, they need an empty alt attribute. Writing a description for a decorative image makes the screen reader announce content that adds nothing, which is worse than silence. Mark it alt="" on purpose, so the decision is visible in the code.

### How should I measure alt text compliance?

Report three numbers: images with meaningful alt, images with empty alt on purpose, and images with no alt attribute at all. The third number is the failure count. A raw count of flagged images hides the difference between a site with a process and a site with a gap.

### Where do most missing alt failures come from?

From content added outside the development process: marketing banners, product galleries, and CMS uploads where the alt field is optional. Make the field required in the CMS, with a decorative option, so the decision happens when the image is added.