What alt text is, and why the list your scanner gave you is the wrong place to start

# What alt text is, and why the list your scanner gave you is the wrong place to start

Your accessibility scan came back this morning with a column headed images missing alt text, and somebody now has to fill in every row. Alt text is the sentence that stands in for the picture: a screen reader reads it aloud where the image sits in the reading order, and a browser prints it in the empty box when the file does not load.

That list is the cheap half of the job; the expensive half is the images your scan called clean. The fee table published as a screenshot, the poster carrying the date and the room number — each of those already has a sentence in the box, and nothing automated reports a sentence that is merely wrong. Then somebody emails asking for the fee schedule in a form they can read, and what you have to send them is a picture of a table.

WebAIM, the Section 508 training module, Microsoft's own guidance and the Government of Canada's accessibility toolkit all tell you what to write in that box, and they are right to. Not one of them says who writes it the next time a news post goes up on a Friday afternoon, which is the part that decides whether your site is still accessible in March.

Alt text is what your page says when the image is not there

You type it into the alt attribute of the image, and it does three jobs at once: it is announced in place of the picture, it is printed when the file fails, and it is the only text a search engine has about that image. Nothing else you fill in about an image does all three.

The requirement sits at the bottom of the standard rather than the top. WCAG 2.0 Success Criterion 1.1.1 Non-text Content is Level A — the lowest conformance level the standard has — and it asks that "all non-text content that is presented to the user has a text alternative that serves the equivalent purpose" (W3C (opens in a new window)). Ontario points at the same document: public websites and web content posted after January 1 2012 must meet WCAG 2.0 Level AA except for 1.2.4 (live captions) and 1.2.5 (pre-recorded audio descriptions), and that has applied since January 1 2021 to designated public sector organizations and to businesses and non-profits with 50 or more employees (ontario.ca (opens in a new window)).

So an empty box is a Level A failure — the kind nobody argues about in a complaint.

A caption, a tooltip and a file name are three other things, and none of them is alt text

The confusion is reasonable, because a CMS often puts all four fields on the same screen.

A caption is visible text under the picture, and everybody gets it, including the people reading the alt text. Writing the same sentence in both means a screen reader user hears it twice in a row.

The title attribute paints a tooltip when a pointer rests on the image. A keyboard user never triggers it and a phone has no pointer to rest, so whatever you put there reaches only part of your audience. W3C's own alt decision tree routes every case — informative, functional, decorative, text, complex — to the alt attribute, and never to title (W3C (opens in a new window)).

The file name is what gets read out when the alt attribute is missing altogether. That is how a screen reader user ends up listening to IMG_4032.jpeg, or to the name of the folder somebody dragged it out of.

Alt text is the one in the box marked alternative text, and it is the only one the standard's 1.1.1 is about.

Some images should say nothing, and you decide which ones on purpose

The standard makes room for images that carry nothing: "if non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology" (W3C (opens in a new window)). W3C's decision tree gives the mechanics in five words — "use an empty alt attribute" (W3C (opens in a new window)).

Empty is not the same as absent, and the difference is the whole point:

``html <img src="divider.svg" alt=""> <!-- skipped, silently, on purpose --> <img src="divider.svg"> <!-- announced as "divider dot S V G" --> ``

One of those is a decision. The other is a gap that a scanner will find and put on your list.

Where this goes wrong is when decorative becomes the box people tick for anything hard to describe. The test that settles it: if you deleted the image and the page still said everything it needed to say, it was decorative. If deleting it loses information, you owe that information to somebody who cannot see it.

The same photograph needs a different sentence depending on why you put it on the page

Three of your images, in the order you will meet them.

[IMAGE SLOT 1 — BLOCKED. Real screenshot required, Gate A: a real staff-directory row from a shipped project, or koval.dev's own, showing the headshot beside the name and title. No stock.]

A headshot in a staff directory, with the person's name printed beside it:

``html <img src="j-tremblay.jpg" alt=""> ``

Nothing. The name is already on the page in text, and repeating it in the alt attribute makes a screen reader announce the same person twice.

[IMAGE SLOT 2 — BLOCKED. Real screenshot required, Gate A: an actual event poster published as a JPEG on a real site, details legible — the kind of file a department sends to the web team on a Thursday.]

An event poster uploaded as a JPEG, with the date, the time and the room number printed inside it:

``html <img src="open-house-poster.jpg" alt="Open house, Thursday November 6, 6 to 8 pm, Room 214."> ``

Every word that matters is now readable. Better still, put the date, the time and the room in the page text and let the poster go to alt="" — then the details can be searched, copied into a calendar and read at any size.

[IMAGE SLOT 3 — BLOCKED. Real screenshot required, Gate A: the koval.dev header logo as it actually renders, with the markup beside it.]

A logo in the header that links to the homepage:

``html <a href="/"><img src="logo.svg" alt="Koval.dev home"></a> ``

Not "logo". Not "company logo". When an image is the whole of a link or a button, the alt attribute has to say where it goes or what it does, which is what W3C's decision tree asks for on the functional branch.

The standard sets no character limit, and the number everybody repeats is not from it

You will be told 125 characters. The Government of Canada's toolkit says to "keep it short and simple like a tweet (125 characters maximum)" (a11y.canada.ca (opens in a new window)) and Level Access says to "aim for 125 characters or less" (levelaccess.com (opens in a new window)). Both were published by people who know the subject. Neither figure appears in Success Criterion 1.1.1, which sets no length at all.

Treat length as a symptom rather than a rule. If your sentence needs a second sentence, the image is carrying information the page ought to carry in text — where anyone can search it, translate it and paste it into an email. A long alt attribute is usually the signal that the wrong thing got published as a picture.

A chart, a logo, an icon and a screenshot of a table are four different problems

• A chart or a graph. Write the finding, not the furniture. Microsoft's own guidance puts it bluntly: describing a chart as "a bar chart showing sales over time", it says, "would not be useful to a blind person" (Microsoft (opens in a new window)). W3C routes complex images the same way: "include the information contained in the image elsewhere on the page" (W3C (opens in a new window)). Numbers into a table under the chart; the alt attribute names the chart and points at it.
• A logo. The organization's name. If it links home, where it goes.
• An icon sitting beside its own text label. alt="". The label already speaks. An icon that is the only thing inside a button gets the action instead — "Search", never "magnifying glass".
• A screenshot of a table, a form or a fee schedule. This one is not an alt text problem wearing a disguise. If the only copy of your fee schedule is a PNG, the attribute is not where that belongs — rebuild it as text and let the picture go decorative.

Your scanner reports the empty boxes; it cannot read the sentences you filled in

Run axe or WAVE or Lighthouse and you get every missing attribute in seconds, which is worth having. On my own site in September, axe-core 4.13.0 across all 23 routes returned zero violations for alt text. What that measured is that every image has an attribute. It says nothing whatsoever about whether the sentences inside them are any good, and I would not quote it to you as if it did.

No scanner can. WebAIM states the limit plainly: "although technology is getting better at recognizing what an image depicts, algorithms alone cannot understand what an image means within the context of the overall page" (WebAIM (opens in a new window)).

That applies with force to the automatic descriptions now offered inside every editor. The United States government's own Section 508 training tells its readers to "avoid using default or AI-generated alt text, since these descriptions usually do not communicate the actual purpose of the image" (Section508.gov (opens in a new window)). Microsoft, which ships one of those generators, tells you to delete the note its own tool leaves behind — "Description generated with high confidence" — before the document goes out (Microsoft (opens in a new window)).

That boundary is where a free afternoon stops and an audit starts — what the free route finds, and what it misses.

Template images are written once; content images are written every week, by whoever published them

Split your list in two before anybody starts typing.

Template images are the ones the build put there: the logo, the icon set, the background bands, the map on the contact page. They are a small fixed set, they are decided once, and correcting one of them corrects every page it appears on.

Content images are the ones your organization publishes: the news post, the poster, the headshot, the thumbnail on a PDF. They arrive at the speed your team works, they are chosen by people who have never read a success criterion, and the alt text box in most CMS forms is optional — so on a deadline it is empty. This is the half that comes back, and it comes back whether or not you remediated perfectly in January. It is also why keeping a site compliant is a standing job rather than a project.

[GATE A — BLOCKED. Interview question 1. The occasion: the last site where he was handed a list of images with no alt text — what he did first, and how much of the list collapsed once the template images were separated out. Counted, in honest units, no invented percentage.]

[GATE A — BLOCKED. Interview question 2. Who ended up writing the alt text for the content images on that site — him, or the people publishing the pages — and what that changed afterwards. This is the paragraph the whole section rests on and it is currently an assertion.]

Where the machine pass is fine, and what I will not do with it

An automatic description run over a photo library is a useful first draft, and on a site whose images are nearly all decorative it gets most of the way there. If your site has a dozen images and changes twice a year, you do not need a system for this at all — write the dozen sentences, read them again next year, and spend the budget on something that moves.

What I will not do is run a generator across an image library, hand the output back as remediation and call the standard met. It would pass a scanner. It would pass while telling your reader that the fee schedule is a photograph of a document.

[GATE A — BLOCKED. Interview question 3. The refusal, with its cost: the last image, or class of images, he told somebody he would not write the alt text for, and what he proposed instead. Voice rule 4 — the piece needs the boundary in his own words, not a generic one.]

The person who chose the image is the only person who knows why it is on the page. That is not a delegation of the hard part; it is where the hard part actually lives.

If your scan has produced a spreadsheet nobody can prioritize, the first useful move is separating the rows that repeat from the rows that matter. That is the opening hour of an audit, and it is the part that decides how long the rest of it takes — what an AODA audit involves and what it costs.