search

alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

Only wrap images with alt text in hyperlinks #366

Closed tombye closed 1 month ago

tombye commented 2 months ago

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 :)

tombye commented 2 months ago

Thanks @marcotranchino, great suggestions. Now rewritten to include them.