Content clarity

Why it matters

A screen reader announces alt text, link text and button labels out loud, often stripped of the surrounding page. When a visitor pulls up a list of every link on the page, which is a normal way to navigate, a page full of “here”, “more” and “read on” becomes unusable. An image whose alt text reads “image1.jpg” or “banner” is announced as exactly that.

WCAG covers this under 1.1.1 Non-text Content and 2.4.4 Link Purpose (In Context). Both are Level A. Automated rule engines can only check that alt text and link text exist. Whether the words are meaningful is a judgement call, which is why this check exists.

What gets checked

• Image alt text. The image itself is looked at alongside its alt text, so the two can be compared. Decorative images that are correctly marked as decorative are left alone.
• Link text. Judged together with the link’s destination, so a short label that is accurate for where it goes is accepted.
• Button labels. The visible text, or the accessible name when the button is icon-only.

Product names, page names, brand names and short-but-accurate alt text all count as descriptive. The check is deliberately biased towards passing: when a label is borderline, it is left alone rather than flagged.

How the score is calculated

Not everything on the page reaches the model. Images, links and buttons are inventoried as the page is scanned, up to the first 60 of each. Every image worth comparing is then judged, while link and button names are filtered first: a name that names its own destination, or that is one of the conventional labels a site cannot avoid - Home, Sign in, Search, Next - is passed without a model call. Only the empty, one- and two-character and “click here”-shaped names are sent to be judged.

The score is the share of what was actually judged that came back descriptive:

So a page where 40 items were judged and 6 of them were flagged scores 85. Nothing is weighted by severity, and the score is not blended into your accessibility score. It sits beside it as a separate number.

On a full-site crawl the site-wide figure is the average of the per-page scores, counting only pages where something was actually checked. Pages with no images, links or buttons to judge get no score rather than a zero, and the score is hidden entirely rather than shown as 0 when nothing on the page could be checked.

Repeated template images, such as the same product-tile pattern across a catalogue, are sampled rather than all judged: a couple per template, reported as one group, with the number of images sharing it shown on the finding: up to three per template are actually looked at. On very image-heavy pages an overall cap applies on top of that, and the most suspicious alt text is judged first so it is never crowded out.

What a good score looks like

• 90–100. Healthy. Expect a handful of flagged items on any real site; chase them when convenient.
• 70–89. Worth a pass. Usually one repeated pattern, such as a product tile or an icon button used site-wide, accounting for most of the flags.
• Below 70. A systemic problem. Typically auto-generated alt text from a CMS or filenames used as alt text. Fixing the template that produces them usually moves the score a long way in one change.