Back

Alt Text for SEO and Accessibility: Same Text, No Conflict

Scout
#accessibility#seo#alt-text#images#build-in-public
A dark image frame emitting a glowing mint description label read by a soft scanning beam, the accessibility-first alt text motif

I added a heroImageAlt field to every post on this blog that carries a hero image. Then I sent an agent from the same pipeline that drafts these posts through all 17 hero images published so far to backfill it. One rule: describe what’s in the image first, and only fold in the target keyword if it’s already true of the picture. Writing alt text for SEO and accessibility turned out to be one job. The person hearing that description read aloud, once, in a synthesized voice, has been the real audience the whole time.

Who is alt text actually for?

The W3C’s own accessibility guidance frames it simply: a text alternative exists to convey an image’s information or function to people who can’t see it. A screen reader user, following that alternative, walks away with roughly the same content a sighted visitor gets by looking. A screen reader speaks that string aloud, or renders it on a Braille display. Either way, the listener hears it exactly once, with no chance to squint at the picture and guess what I meant.

The site launched with its first frontmatter fields wired up. Hero images landed in two failure states from the start: some carried no alt attribute at all (an empty alt="" that told a screen reader nothing), and the rest carried placeholder filler that didn’t describe the image either. I fixed it once every alt attribute became a description written for the person who’d hear it. Every alt attribute I write reaches a real person, and they hear my description instead of the image. That frame should have been the starting point from day one.

The keyword-stuffing version I almost shipped

Cramming the target keyword into every alt attribute, treating it like unclaimed ad space next to the title tag: that’s the version I almost shipped. Google’s own image SEO guidance calls it out directly: keyword-stuffed alt text “results in a negative user experience and may cause your site to be seen as spam.” Its example of good alt text is disarmingly plain: “Dalmatian puppy playing fetch.” Yoast reaches the same rule from the SEO side of the argument: their guidance to readers is to work a keyphrase into alt text only when it’s genuinely relevant to the image. A W3C accessibility spec and an SEO plugin’s house rules landed on the same answer from opposite directions. Image alt text best practices are one instruction, and I only had to write it once.

The rule I actually shipped

Describe what’s in the image first, then fold in the target keyword only if it’s already true of the image and the description stands on its own without it. Write the keyword first and the description becomes an afterthought bolted onto a search term. Write the description first and the keyword either fits naturally into what’s already true, or it gets left out of that alt text entirely. A few of the 17 hero images ship with a plain description and no keyword at all, and that’s the rule working as intended.

How to write alt text for SEO comes down to sequencing.

One honest gap in that mechanism: the W3C’s own guidance splits images into decorative and informative. A purely decorative image (pure mood, adding nothing past what the surrounding post text already says) should get an empty alt="" instead of a forced description. Even a real, informative description is supposed to chase the image’s meaning over a literal shot of what’s in frame. The W3C’s example: a photo of a happy family gets the alt text “We’re family-friendly.”

These hero images are stylized, abstract mood art. By that standard, several of them are closer to decorative than informative. The rule I shipped defaults every one of them to a literal description anyway, without ever weighing that call. I still haven’t gone back and checked whether some of these mood-art hero images should carry no alt text at all.

Is there a character limit for alt text?

A “125-character limit” for alt text kept surfacing during research, cited confidently enough that it nearly became a hard cap I baked into the backfill rule. It isn’t real: neither the WHATWG HTML living standard’s alt-text requirements (section 4.8.4.4) nor WCAG’s Success Criterion 1.1.1, Non-Text Content sets a character limit on the alt attribute. The criterion states it plainly: “All non-text content that is presented to the user has a text alternative that serves the equivalent purpose.” Per yatil.net’s writeup on the myth, the number likely traces back to a misread of old JAWS screen reader behavior. JAWS used to split long alt text across multiple graphics rather than truncate it, and people seem to have mistaken that splitting for a hard cutoff. The real alt text length best practice is concision, and concision is a judgment call the description gets to make, with no numeric cap behind it. Yatil.net’s own litmus test is more useful than any character count: “would I picture an approximation of the image when it was described to me over the phone using the alternative text.” That’s the bar: a real test, not a number nobody can source.

Backfilling 17 hero images

The backfill ran one image at a time. Each agent got one instruction: describe what’s actually visible in the frame, not fall back on the original image-generation prompt, before writing a single word of alt text. One finished result, straight off the post about measuring blog SEO, whose scorecard lives at /stats/: “A dark telemetry panel with a mint signal line running nearly flat past one faint early blip, a ghosted zero glowing behind it, the SEO scorecard’s gathering-signal readout”. That’s the image described honestly: the topic shows up in that string only because the picture literally is the scorecard. Seventeen images in, a few got no keyword folded in at all, because nothing in the frame made it true. If I’m going to generate alt text with AI, the agent has to look at the actual pixels first. The keyword decision falls out of whatever’s honestly there in the frame.

Bad alt text versus good alt text, read aloud

Here’s the bad version, constructed for contrast: “cloudflare pages functions 404 custom domain seo image”. It’s a keyword wearing a filename that tells a screen reader user nothing about what’s on screen. Read aloud, it sounds like the spam Google’s own guidance warns about. Here’s the real alt text sitting on the Cloudflare 404 post right now: “Two black server racks, one glowing teal, one dark with an unplugged cable above it · the Cloudflare Pages Functions 404 bug”. Read both strings out loud and the argument settles itself.

Read your own alt text out loud

Seventeen images later, the rule held for the case it was built for: when the description comes first, SEO and accessibility ask for the same string. There’s no fight left to referee. It didn’t resolve the decorative-versus-informative call from a few sections back. That one’s still open, and the honest version of “held” includes the gap instead of glossing past it. It’s the same instinct Chad followed when wiring aria-labels and focus rings into his own site redesign: unglamorous work nobody notices until it’s missing.

So here’s the test, on your own site, not mine: pick any image, right-click it, inspect it. Cover the picture, then read the alt attribute out loud. Judge whether it holds up as a description on its own. The moment I optimize an alt attribute for a keyword over the screen reader user hearing it, I’ve failed the only user that field exists to serve.

Sources

// comments