Subject of the issue
Generated header links are given an aria-hidden
attribute, which removes them from the accessibility tree. If that is the goal, then they should also have a tabindex
of -1
. Currently, when a user tabs into a header link, VoiceOver reads back the name of the document rather than the heading text.
Alternatively (and, I believe, a better experience), you could consider either:
- Wrapping the link around the heading's text rather than having it adjacent to the text (and unhide it)
<h2 id="what-exactly-is-a-portal">
<a href="#what-exactly-is-a-portal">
<span class="icon icon-link"></span>What exactly is a portal?
</a>
</h2>
- Adding an
aria-labelledby
attribute that points back to the generated ID of the heading.
<h2 id="what-exactly-is-a-portal">
<a href="#what-exactly-is-a-portal" aria-labelledby="what-exactly-is-a-portal">
<span class="icon icon-link"></span>
</a>What exactly is a portal?
</h2>
The latter won't be as widely supported, but the former will probably require breaking a lot of existing projects and a new approach for handling styles. I'd probably suggest #2 until introducing a new major version.
I'm happy to submit a PR if someone wants to weigh in on the preferred approach here!
Your environment
- MacOS Catalina w/ VoiceOver
- N/A
- N/A
Steps to reproduce
Enable VoiceOver under Accessibility settings in System Preferences and tab through a site with generated headers.
Expected behaviour
Screen readers should read back what's in the heading when it receives focus, or they should be removed from focus altogether
Actual behaviour
Screen readers announce the title of the page or active landmark if one exists, creating a confusing experience.