aria-label is a letdown
One in three aria-label implementations have likely issues
Sob. There’s unfortunately nothing specific to Wagtail here – aria-label is very easy to incorrectly use, and it’s nothing new that aria-label can be considered a code smell (do read that article). But here are the figures for Wagtail sites’ homepages specifically!
- Missing visible text (not always an issue but very likely): 21% of uses of the attribute
- Starts without visible text (meaning extra fun for voice control software users): 23% of uses
- Disallowed for role: 4% (possibly harmless, or indicative of a bigger issue)
- Overrides visible text: 32% of uses
All in all, 34% of aria-label uses we reviewed are likely incorrect (🥲)
If you’re interested in the methodology, check out the aria-label extraction script and the raw data: aria-label problems in the wild - Wagtail websites.
Problem patterns
A lot of people have already written excellent articles about the issues, here are a few great ones:
There are a ton of preferable alternatives. First off, considering whether a visible label could be used instead. Maybe the need for invisible labels is a sign of overuse of icons, so a design smell, rather than code issue? A visible label will be the same for all users. And it’s just plain HTML. Consider this bit from the WebAIM Million project:
“Home pages with ARIA present averaged 34.2% more detected errors than those without ARIA”
Hazarding a guess, in the case of aria-label I expect we arrived here because developers strive to meet SC 2.4.9 Link Purpose (Link Only) with aria-label, and generally make the experience better for screen reader users, without awareness of the limitations of the different accessible name techniques – and without enough understanding of how those techniques impact users of other assistive technologies.
👉️ That’s why I say aria-label is a letdown: its use comes from good intentions but the results fall way short.
What it means for Wagtail
Our accessibility team spends a lot of time making sure Wagtail implementers out there have access to good information, but perhaps there’s a need for more? This could take the form of:
- A revamped accessibility considerations docs page, perhaps with links to common HTML issues?
- Building linting for Django Templates and Jinja to detect those common issues?
- Considering more opinionated rules as part of our ideas for accessibility checks enhancements?
Whatever the ideal solution is in a given scenario, collectively we need to tackle those problems. Make sure we come up with good answers when discussing icons-heavy designs, and that we can advise when pondering an aria-label field inside a CMS. Challenge yourself and your coworkers to see if you can build something without invisible labels for buttons and links?
Bonus points for those who made it this far: here’s what the Wagtail page editor would look like if we kept our design as-is but swapped all icon-only buttons to use their aria-label:
