Alt text is writing

I ran a client’s site through an accessibility checker last month because they got slapped with an ADA lawsuit and they panicked. ~340 images and every single one had an alt attribute. No errors on that check so we’re good, right?

Then I read them.

alt="image". alt="photo". alt="IMG_2214". alt="banner". The company name verbatim, a few dozen times. And one, on the careers page, that said alt="alt text here"

The checker can only count

This is the bit I hadn’t properly understood until recently. An automated check can tell you the attribute is present. It can’t tell you the attribute is any good, and no tool is ever going to, because to do that it would have to answer “what is this picture for,” and that’s not a property of the image. It’s a property of the page the image is sitting in.

So the audit was measuring the one thing that was easy to measure, and the client had scored full marks on it, and the site was no more usable than it had been the day before.

I’d been doing the same thing, honestly, just more neatly. I had “alt text is for blind people” filed as a fact somewhere early on in my journey and I’d never gone any further with it. Which meant I filled the attribute in the way you fill in a form: correctly, dutifully, and without any thought about who reads it.

The same image, three different alts

The thing that actually shifted it for me is that alt text isn’t a description of the image. It’s a description of the image’s job on this page. Same file, different page, different alt, and sometimes no alt at all.

team.html

<!-- team page: her name is in the heading right next to it -->
<img src="alex.jpg" alt="">

<!-- speaker list: the photo is the only thing telling them apart -->
<img src="alex.jpg" alt="Alex">

<!-- write-up of the talk where what she's doing is the whole point -->
<img src="alex.jpg" alt="Alex on stage, pointing at a slide of a flowchart">

HTML

The first one looks like a mistake and it’s the one I’ve gotten pushback on. But if the name is in an <h3> two inches away, then putting the name in the alt as well means a screen reader user hears it twice for no reason, and you’ve made the page worse in the name of doing accessibility.

So the question isn’t what the image looks like. It’s what the image is doing.

The question isn't what the image looks like. It's what the image is doing.

Which is a judgment about the page, made by someone who understands why that photograph is there. Hold that thought, because it’s most of the point of this post and I’ll come back to it.

Empty is fine, missing is not

Related, and worth separating out because the difference is two characters and the outcomes are opposite.

I’d assumed for years that omitting it was the polite version of not knowing. It isn’t. It’s the loudest possible way of not knowing.

Bad alt text

A few patterns I keep finding:

Keyword stuffing. Somebody has read that alt text counts for SEO, so the photo of the office is alt="web design agency San Diego web design services San Diego web designer". This is the one I find genuinely irritating, because it isn’t ignorance. It’s a decision to take a feature that exists for one group of people and spend it on something else, and the cost lands entirely on that group. I don’t think anyone doing it has pictured a person listening to it.

Length. Alt text is read aloud in a linear stream and you cannot skim it. If your alt is a paragraph, you’ve built a trap that a sighted reader can glance past in half a second and a screen reader user has to sit through. My rough rule is a sentence, maybe two. If it needs more, then the information is too important to hide in an attribute, and it belongs in a caption or in the prose where everybody gets it, which is nearly always the better page anyway.

Saying “image of”. The screen reader already announces that it’s a graphic, so alt="Image of a dog" comes out as image, twice. Just describe the thing.

Charts. This is the one I’m worst at. alt="Sales chart" is useless, and a chart is hard because the data is the content and the picture is just one rendering of it. What I’ve landed on is that if the chart is worth including, its finding is worth writing down: sales grew in every region except the northeast. Put that in the paragraph. Put the numbers in a table if they matter. The alt then only has to say what kind of picture it is.

Logos that are links. The logo in the header is usually wrapped in a link to the homepage, which makes the alt the accessible name of that link. So it isn’t “logo,” and it certainly isn’t the tagline. It’s where the link goes.

Let the writers write

Here’s the actual argument, and it took me the whole audit to work out.

On most projects, alt text is written by whoever is touching the template. Which is me, at six in the evening, with no idea why that particular photograph was chosen or what it’s meant to be doing. I am comfortably the worst-placed person on the project to write it. The designer picked the image and knows what it’s for. The copywriter wrote the paragraph sitting next to it and knows what the section is arguing. I’m just the one who happens to be in the CMS at the time.

So on the last two projects I’ve moved it. There’s now a column in the same spreadsheet the headings and body copy live in, labeled “alt text,” and it gets filled in by the same person who fills in everything else who on both projects was an actual writer. It came back better than anything I’ve ever written, on the first pass, and I contributed nothing to that except moving a field.

It also means it gets reviewed because everything else in that document gets reviewed. Nobody has ever reviewed my alt text. Nobody has ever reviewed anyone’s alt text, as far as I can tell, which is a strange thing to be true of copy that ships on every page.

Clients, amiright?

You can win this for the pages you hand over and lose it for every page after because the client uploads images through the CMS forever and you’re not there.

And the CMS is not helping. The media library in WordPress gives you four boxes: title, caption, alt text, description. Three of them are lightly documented and one of them is prefilled with the filename, and I’ve watched a perfectly capable person put a sentence in the wrong box while I was in the room explaining it. If the field is optional it’s empty, and if it’s required it says “image,” and both of those are the interface working as designed.

The best I’ve managed is small. I relabel the field as a question, “What does this picture say? If it’s just decoration, leave this blank,” and put one line of help text underneath. That has done more than the training session did, which is either a nice lesson about interface design or a slightly depressing one about training sessions.

I suspect this is a whole post of its own, actually. There’s a category of thing where I do the work properly and then hand over an upload field that quietly undoes it, and images are only the most obvious case.

Anyway

Over 300 images with their accompanying alt attributes, no errors, and a page that reads out as “image, image, banner, IMG-underscore-2-2-1-4.”

It’s not a compliance task and it’s not really a development task. It’s a few words of copy per page, written by someone who knows what the picture is doing there, and the reason it’s bad everywhere is that we keep filing it under the wrong job title.

Go and read yours. Not run a checker over them, read them. It takes ten minutes and I’d put money on at least one of them saying “banner.”