Accessibility: aria region around skiplink is superfluous

[timveld]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

In issue #6252, an aria region with the label "skip to main content" was placed around the "skip to main content" 'skiplink' which appears at the top of every docusaurus-generated page.

This was done in response to automated accessibility testing tools reporting that all page content should be contained in an aria region.

I agree that the skiplink should be contained in an aria region, but creating a dedicated aria region for the skiplink is a regression from a screen reader user's perspective.

Aria reagions are used to divide the page into multiple blocks of content in order to facilitate easy navigation between such blocks of content by screen reader users. Note that I say blocks, not single elements. If a page were cluttered with regions containing only one or two elements, the value of using aria live regions (i.e. the ability to quickly skip a lot of clutter and 'skim' the page on a high level) is quickly lost.

More importantly, superfluous regions (particularly those with long labels) contribute to information overload which is a major issue when working with a complex website using a screen reader. To understand the problem I'll quote my screen reader's speech output:

• No region: "link skip to main content"
• With region: "skip to main content region link skip to main content [line break] out of region"

In summary: this region not only doubles the number of words I have to listen to, but also introduces a line break to my "view" of the page.

Long story short:

• The dedicated region around the 'skip link' should be removed
• The skip link should be placed in the banner region

Reproducible demo

No response

Steps to reproduce

Use any docusaurus-generated page with a screen reader

Expected behavior

Skiplink is contained within the aria banner region

Actual behavior

Skiplink has a dedicated aria region, complicating navigation and causing screen readers to read a lot of superfluous information

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

cc @JoshuaKGoldberg @BenDMyers The reasoning here makes a lot of sense to me but would love to hear your ideas on this.

[BenDMyers]

Agreed this region is superfluous, and would lead to unnecessarily cluttered announcements when users navigate to it with a screenreader.

Doing a quick Google to see if there's recommendations for where the skip link should go and which roles it should have turns up a few interesting results:

Rule Description
It is best practice to contain all content excepting skip links, within distinct regions such as the header, nav, main, and footer.

—Deque University's All page content must be contained by landmarks rule

Some automated accessibility testing tools may warn that the skip link element is not inside a landmark. This warning does not apply to skip links, so you can ignore it. Do not wrap the skip link in a <nav> region, or move it inside the header.

—GOV.UK Design System skip link component, with more discussion in a GitHub issue

2. For users who DO use a landmark tool to navigate the page, wrapping the skip-link in a navigation landmark of it's own is probably overkill:

• If a user wants to find the main content, they can use their landmark tool to find the <main role="main"> region directly. They don't need the skip-to-main-content link at all.
• The idea that a user will look for a "skip-to-main-content" region, just in order to find a skip-to-main-content link inside, sounds absurd.
• So the extra landmark region isn't a useful destination in it's own right; it just bloats the list of landmarks.
• For screen reader users who make mixed use of the skip-link and landmark regions, the skip-link is still easy to find at the top of the page. JAWS and NVDA provide a keyboard commands to return to the top of the page. (Not sure about the other screen readers.)
• The skip-to-main-content link can be found using the screen reader's "list all links" functionality. It'll be at the start of the list.

That's why I don't think the skip-link warrants a landmark region of it's own.

You could make a case for moving the skip-link inside of the existing <header role="banner">, but if someone uses their landmark tool to jump backwards to the header content, they probably aren't looking for the skip-link.

—Andrew MacPherson in an issue filed against Drupal, articulating much the same as @timveld

Given that Deque and GOV.UK Design System in particular advise against having skip links in landmarks, I'm inclined to remove the region and have the skip link be a direct child of body, without putting it in any other regions.

Note: This isn't a neutral decision free of impact. While the experience will likely be better for screenreader users, the skip link not being in a landmark will get flagged as a false positive on every Docusaurus site. This may cause churn in organizations with accessibility auditing practices that involve automated testing, and this could lead to more issues being filed against the Docusaurus project.

[slorber]

Thanks

Honestly, I don't have the a11y skills to understand what should be done here 😅
I'd be tempted to be pragmatic and bias toward what actual screen reader users want, but is there a consensus among screen reader users and a good variety of screen reader software?

Considering this was only added recently and only @JoshuaKGoldberg reported it, we shouldn't get too many reports 🤞

---

Maybe we could also reach out to Axe and see what they think of this case?

https://dequeuniversity.com/rules/axe/4.1/region

It is best practice to contain all content excepting skip links, within distinct regions such as the header, nav, main, and footer.

excepting skip links: so I guess the Axe rule shouldn't apply here, but maybe they can't detect this edge-case properly? 🤔

[BenDMyers]

I'm definitely on the side of favoring real experiences over automated tools.

I've been diving into issues on the axe-core repo since my last comment, and it seems like axe-core already tries to intuit which links are skip links and exempt them from the regions rule as is. I think their heuristics generally depend on the skiplinks having an in-page fragment for an href. I'm not entirely sure why @JoshuaKGoldberg got a warning about this, but I wonder if the fallback hash changes from #6411/#8204 since might have made it so Docusaurus skiplinks would now pass Axe checks if revalidated. If so, that's a major vector of automated accessibility scans you wouldn't have to worry about.

Chances are, other non-Axe automated accessibility scanning tools might still flag this as false positives, but I think the churn would be much less since Axe is so popular.

[JoshuaKGoldberg]

Ah yes I just reported #6252 originally because aXe was reporting. It sounds like my report was erroneous - that I should have reported a false positive to aXe.

[Josh-Cena]

Accepting a PR from whoever is confident about what to change 😄

[timveld]

Interesting discussion.

Most screen reader users will not notice the difference between the skiplink being "on its own" or in the header region. And I see no strong objective ground (in WCAG or elsewhere) for favoring one option over the other. So I think we just have to make a design choice.

Looking at other websites, most websites put the skiplink "on its own" (e.g. gov.uk, microsoft.com). Deque.com does put it in the header, but they seem to be an exception to the generally accepted best practice. This is all the more dubious given the quote from Deque university mentioned above, which includes the words "excepting skiplinks".

As this confusion is the result of Deque's rule and their apparent inconsistent application of that rule, I agree with the suggestion of asking Deque for their input. Therefore, I will contact Deque and ask them to reply in this thread (or I will summarize the reply I get from them here).

[slorber]

Thanks @timveld, we appreciate your inputs on a11y issues :)