Peter Krautzberger · on the web

A MathJax extension for specifying the accessible name

Look at me writing two posts in a year! October is World Blindness Awareness Month, so let's solve one of the critical missing pieces for accessible equation rendering on the web! Am I exaggerating? Only a little.

Previously, I had mentioned an update on my work on the aria-tree walker (formerly known as mathjax-sre-walker, see also No. 209). While a longer piece on this may be warranted, let me focus on a closely related issue - fixing accessible names when necessary, a problem the walker solves in part.

Fantastic heuristics...

While heuristics can be useful (e.g., user agents dealing with invalid markup or Chrome's machine-learning-based image descriptions), it is always better to avoid them. Nobody likes a guessing game. This gets tricky however with content that cannot work without heuristics, e.g., equations.

To quote myself, equations are simply pretty terrible all around and not at all accessible (in the sense of web accessibility). So far, the best you can do is to use MathJax's accessibility extensions to leverage the incredible heuristics provided by Speech Rule Engine. All solutions around equations require heuristics and this is the best tool available.

And yet even with the best heuristics your content will still suck alot. Why? Because heuristics inevitably hit their limits and provide poor results in edge cases (and how quickly that happens is usually outside your control). Your advantage is that you have least something as opposed to nothing when a dictionary-based approach fails.

So what to do? If you cannot avoid heuristics, then the next best thing is to apply heuristics-based tools server-side; client-side heuristics should always be a last resort. Besides the obvious perks, you end up with a static bit of content that you can fix if necessary. Coming back to the aria-tree-walker, if you look at any of the examples in its docs and are unhappy with the accessible name of some part, you can simply edit it. Then it's fixed. That's a huge step forward. And yet.

... and where to fight them

Fixing accessibility issues can be hard. Even the best content might turn out to not work as expected or be facing an insurmountable bug somewhere along the way to the user, forcing you to work around things. Ideally, you can apply a fix at the source but often fixes in post-production are the only way. If your content requires heuristics, you now have two problems: you need a fix and you need to override the heuristics to prevent them from ignoring your fix. That's a lot to ask.

For Speech Rule Engine (and thus MathJax), this problem now has a first solution: my feature request from 2017 has been implemented and we now have support for aria-label. This means you can override the accessible name at the source and Speech Rule Engine will honor it. Even better, this can give you the best of both worlds: if you label a non-atomic expression, users will still be able to dive in and explore the heuristics-based version. That's in fact, nothing new - if you explore something labeled x squared you might come up against exponent 2 - but it's worth repeating as it is incredibly powerful for users.

At the source

Of course, having some internal markup facility makes things a bit more difficult for authors. Most likely they use better formats than MathML to feed into SRE's heuristics. If we cannot give authors control at the source (no, not that source), we can never hold them accountable. So let's solve this for MathJax's TeX input.

The repository mathjax-aria-label hosts a MathJax v3 extension for the TeX input providing a simple macro: \arialabel{}{}. The macro takes two arguments: the first argument becomes the value of the aria-label attribute on a wrapper around whatever the second argument becomes. This macro is of course most useful when used in other macros, either with a fixed name or with a constructed name (e.g., a small caps macro could do something like \arialabel{small caps #1}{#1}).

The repository has a small example on GitHub pages and below is a short recording of Orca reading the examples in Firefox.

I hope this gives a first idea of the kind of benefits this simple macro and the underlying technology can enable.


There's nothing wrong with using heuristic-based tools for accessibility purposes if you have no other recourse. Just make sure you can override the heuristics when they fall short. With equations, we just took a good step forward: authors are no longer coerced to rely on heuristics out of their control.

Reversely, authors can now fix such issues and so they should feel an obligation to do so. Authors can (and should) start thinking about how their own voice comes together in this beautiful medium we call the web.

This is a good thing. If we cannot give authors full control over their content, we will never reach the web's full potential.