Only wrap images with alt text in hyperlinks

[tombye]

What’s changed

This introduces a guard against images with no alt text, choosing to only wrap them in hyperlinks, the default behaviour now, when found.

My Ruby is basic at best but I looked at the method we're overwriting from the Red Carpet HTML renderer and copied across its interface more exactly, to make it clear where the alt_text variable comes from.

The difference in what users see is minimal. The hyperlinks don't have any special styles, like display: block so nothing is different with how they are laid out on the page (both the <a> and <img> tags default to display: inline).

Identifying a user need

When we wrap images in hyperlinks, we make the image's alt text their only content. If those images have no alt text, they are effectively empty links.

This means they have no accessible name if queried by an accessibility API:

https://w3c.github.io/html-aam/#img-element-accessible-name-computation

...so it'll be up to the screen reader talking to the accessibility API to guess. By testing with the Voiceover, NVDA and JAWs, I screen reders, I found this ends up being the file name, which can't be relied on to explain the image. All in all, this behaviour breaks the non-text content success criterion from WCAG 2.2:

https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html

This issue is recorded here:

https://github.com/alphagov/tech-docs-gem/issues/355

Notes for reviewers

Please check my Ruby code! My skills with Ruby are basic at best :)