The diagrams carried the argument, and screen readers got none of it
on this page
Every post on this site opens with a hero image. Before this one there were 37: 34 drawn as SVG diagrams, three photographs. The diagrams aren’t decoration. The particle post’s hero is two rows of particles, one fading and one stubbornly white, which is the whole bug in one picture. The mounts post’s hero is two folders, one drawn in dashes because Hugo had quietly stopped publishing it. I draw them so the point survives a skim.
Until this week, a screen reader got none of that. Not a thin description, not a filename read aloud. Nothing. On every post page the hero did not exist.
Here is how the old theme, Toha v4.16.0, put it on the page, from its layouts/_default/single.html:
<!--Hero Area-->
{{ $hero:= partial "helpers/get-hero.html" (dict "context" . "width" "1200x")}}
<div class="hero-area col-sm-12" id="hero-area"
style='background-image: url({{ $hero.RelPermalink }});'>
</div>
In a browser that is a 400 pixel band with the diagram across it. It rendered on every post, every build was green, and the site’s own check script, which fails a post for a missing hero and for a Markdown image with empty alt text (![]) in the body, passed all 37. It never looked at the hero, because the hero wasn’t an image in the body. It was a <div> with a style attribute. That is the part that makes this worth writing down.
A CSS background image is decoration by definition: it has no alt attribute, no accessible name, and nowhere to put one.
To a screen reader, a <div> with a background is an empty <div>. Nothing warns you, because nothing is wrong: it is valid HTML, valid CSS, and a perfectly ordinary way to put a banner behind a title. The only problem is that mine weren’t banners.
I should be precise about the count, because “every post” overstates it by one. The distro-hopping post puts its photo in the body as an ordinary Markdown image, so that one page had an alt sentence. 36 of 37 had nothing, and the one that did had it by an accident of layout rather than a decision. And it wasn’t only the theme. None of the 34 SVGs had a <title> of its own, and no post’s front matter had an alt sentence for its hero, so a theme that looked in all the right places would have come up empty on the same 36.
It went further than screen readers. Toha’s opengraph.html takes og:image from .Params.images or else from one site-wide card, and no post here sets images, so all 37 posts shared one picture in link previews. Most of the heroes couldn’t have been used anyway, because 34 of the 37 are SVG. X’s card docs put it in four words, “SVG is not supported”, and Facebook’s sharing guide lists JPEG, GIF and PNG as the only image types. For LinkedIn it’s an assumption: its help page gives a preview image a size and a ratio, and no file types. So the diagram at the top of each post was a picture that existed for exactly one audience, a sighted person in a browser, and for nobody else.
I had already decided to leave Toha, for a reason that has nothing to do with alt text. I tried restyling it in September and binned the attempt, and that build showed me the problem. Toha paints the active nav link, and any nav link you hover over, in the light accent (get-light-color('accent-color')) with !important, and none of its dark-mode rules for those links is !important, so none of them can win. Its two schemes share one teal, #0891b2, so you can’t see it until dark mode gets an accent of its own. Then the active link and the hover stay teal. At the time I blamed list links and pagination too, but Toha’s dark rules cover those. A new palette never fully takes, and restyling Toha means fighting it selector by selector.
So I built my own. Wheelhouse is a Hugo theme in Omarchy’s Osaka Jade palette, the one my desktop runs, laid out the way Hyprland tiles windows: content in windows with 16 pixel gaps, and the window that matters, the article, carrying the accent border like Hyprland’s active window. The palette came from git history rather than from my desktop, because Omarchy replaced Osaka Jade with Jade Horse on 25 October; the real values are themes/osaka-jade/colors.toml at the commit before that one. Its templates and stylesheet come to 1,103 lines. Not counting the scripts Cloudflare adds, a first visit to the home page now transfers 135 KB, where Toha’s took 883 KB; most of the difference is 420 KB of JavaScript that became 3.
None of that is why the hero works now. This is, from Wheelhouse’s layouts/single.html:
<figure class="hero">
<img src="{{ $l.RelPermalink }}"
{{- if ne $s.RelPermalink $l.RelPermalink }} srcset="{{ $s.RelPermalink }} {{ $s.Width }}w, {{ $l.RelPermalink }} {{ $l.Width }}w" sizes="(max-width: 968px) 100vw, 1000px"{{ end }} alt="{{ partial "hero-alt.html" $ }}"
{{- with $wh }} width="{{ index . 0 }}" height="{{ index . 1 }}"{{ end }} fetchpriority="high">
<div class="scan" aria-hidden="true"></div>
</figure>
An <img>, with an alt. The partial looks in three places in order: heroAlt in the front matter, then the alt of a Markdown image in the body whose source is the hero file (which covers the distro-hopping post with no change), then the SVG’s own <title>. If none of them has anything it emits alt="" and a build warning naming the post:
{{- if and (not $alt) (.Resources.GetMatch "hero.*") }}
{{- warnidf "wheelhouse-hero-alt" "%s: the hero has no alt text. Add heroAlt to the front matter, or a <title> to hero.svg." .File.Path }}
{{- end }}
Posts here are allowed exactly five front-matter keys, so for the 34 SVG heroes the cheapest route was the third one: a <title> as the first child of each <svg>, which is where SVG keeps its accessible name anyway and needs no key at all. The particle post’s now opens like this:
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 500">
<title>Two rows of particles: the intended row fades from white to nothing, the actual row stays fully white to the end. The colour (255, 255, 255, alpha): the fourth number was ignored.</title>
The 34 sentences were written from rendered contact sheets of every hero, not from the SVG source alone, with the numbers copied off the images. The two photo posts got heroAlt as a sixth key, allowed for photographs only, because a JPG has nowhere inside itself to keep a sentence.
Then the check script learned to look. postflight.sh now fails any hero with no alt text: a <title> for an SVG, heroAlt for a photo, or the hero already in the body. Run before any alt text went in, it reported 36 FAILs: the 34 SVG heroes and the two photos. After: 0, with the warning count unchanged at 16. The warning in the theme catches the same thing at build time, for any site built on it. I’ve learnt not to trust a note to carry a rule; this one is read by two scripts.
Link previews got the same treatment. Each SVG hero was rendered onto a 1200x630 card with headless Chromium, the diagram on the darkest background with an accent frame: 34 social.png files, 2.2 MB as lossless PNG, converted to JPEG at build. The theme picks a social.* file first, then a raster hero, then the site card, and the same alt sentence feeds og:image:alt.
Alt text gets read by eye too, when the image doesn’t load: the browser draws the sentence where the picture should be. Late in the build the hero’s box got a near-black background in both themes, to match the diagrams, and in the light theme that left dark text on near-black: 1.46:1, where text needs 4.5:1. A review caught it before it reached the site. The alt text now takes the dark theme’s text colour in both themes, 10.69:1.
Swapping the theme pushes 37 posts through a different renderer, and I wanted more than “it looks the same”. I built main in a git worktree as the baseline and compared three ways.
Content first. scripts/compare_posts.py takes Toha’s #post-content and Wheelhouse’s .prose, minus the meta line, title and tags Wheelhouse puts on top, the inline contents list, the newer and older links at the bottom and the # link beside each heading. It compares the words, headings, links, images with their alt text, the order of the inline formatting, and every code block character for character. An image counts as the original it links to, since the page shows a WebP copy of each PNG and JPEG.
Result: 37 posts, 0 differences, and one note. The note is about the three code excerpts in the Paul Newman Cup case study, which I’d moved to column zero so a phone doesn’t scroll sideways through blank space. The comparer strips the indentation a whole block shares before it compares code, and reports a block that only moved as a note, not a difference. One line re-indented inside a block still counts.
A zero needs testing, because a comparer that compares nothing also reports zero. So: real counts on one post (899 words, 5 headings and 2 code blocks on the Grafana post, in both builds), and one changed word in a copy, which it caught. The first mutation test was itself wrong. It replaced the first “stalled” in the file, and the first “stalled” was in the <meta> description, not the body, so the comparer rightly saw nothing. A word changed inside the post, it reported.
It earned its keep again later. When the theme gained a link on every heading, the comparer reported all 37 posts different. Every difference was a missing space: Toha’s minified HTML runs </h2><p> together, so the old text read “filesThe” where the new one read “files The”. The comparer now puts a space at every block boundary, the zero came back, and a changed word is still caught.
Then the pages. 188 addresses before, 111 after, and the 77 that went were Toha’s /posts/page/1/ to /4/, the /page/1/ stubs under /tags/, /categories/ and every tag and category, and /search/. Wheelhouse lists every post on one page and searches in a dialog, so all 77 get a 301 in static/_redirects: 72 static rules, one splat, two for search, every target checked to exist.
Then by eye: 12 pages at 390, 768 and 1440 pixels wide, in light and dark mode, 72 full-page screenshots, every one looked at. It caught a loss the counts couldn’t see. The Johnny Decimal post’s hero, which Toha showed whole in a 400 pixel band, came out 680 pixels tall, and on a 1440x900 screen the title didn’t start until 879 pixels down. It’s capped at 420 pixels now, and a taller photo shrinks to fit rather than being cropped, because its alt text describes the whole photo.
And one gotcha on the way that belongs in the same post: hugo --quiet hid a failed build. An {{ else with }} is only valid inside a with, not an if; the template failed to parse, Hugo wrote nothing, and --quiet printed nothing either. The old public/ sat there looking like a pass. Same shape as the hero: something that looked complete because nothing had checked it. Builds run without --quiet now.
Two things, and the second matters more.
If an image carries meaning, it is an <img> with alt text, or an SVG with a <title>, never a background. Backgrounds are for things you could delete without losing anything. That is the test, and it is quick: take the picture away and reread the post. If the argument still stands, it was decoration. If it doesn’t, it needs a sentence, and that sentence has to live somewhere a parser can find it.
The broader one is about where the check looks. My script checked alt text on images in the body because that is where images were supposed to be, and the one image on every page sat outside its field of view, in a style attribute it never read. The site had an alt-text rule and a script that enforced it, and they both missed the hero.
What on your site renders perfectly for you, and does not exist for anyone reading it another way?