Improve the Scrollable component accessibility

Open
#45,809 5 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
javascript

Research direction

Start with the Scrollable component's Storybook entry and reproduce the focus behavior in Firefox and a WebKit-based browser. Check how the component handles focus, focus styling, and accessible naming, then verify that keyboard users can reach and scroll the region and that screen readers receive an appropriate announcement.

Written by the indexing model from the issue text.

Description

[Focus] Accessibility (a11y)
Description

Browsers have different native behaviors when it comes to elements made scrollable with CSS overflow:

  • Firefox: the scrollable element is focusable.
  • Webkit-based browsers (Chrome, Safari, Opera, etc.): the scrollable element is not focusable.

For keyboard users, it is essential to be able to scroll a scrollable element to see all its content. When the element contains focusable elements, more or less users are able to make the element scroll by tabbing through the focusable elements. However, when the scrollable element does not contain focusable elements, there's no way for keyboard users to scroll. See for example the Keyboard shortcuts modal: https://github.com/WordPress/gutenberg/issues/41500

As said above, the underlying issue comes from different browsers behavior. Regardless, we should make sure keyboard users can always access the content of a Scrollable component.

There's a simple technique to remediate see this note by the Paciello group:

Short note on improving usability of scrollable regions
https://www.tpgi.com/short-note-on-improving-usability-of-scrollable-regions/

  • Add a tabindex=0 to include the scrollable element in the tab sequence for all browsers.
  • Add a clear focus style to the scrollable element.
  • This allows sighted keyboard users to move focus to the scrollable element and then use the arrow keys to scroll. Other native keyboard shortcuts e.g. Scrollbar, Shift+Scrollbar, Fn+Down arrow/Up Arrow work as well.
  • However, at this point, the element would be a silent tab stop for screen reader users. When tabbing to the scrollable element, nothing would be announced.
  • To remediate, an appropriate ARIA role and label need to be provided.

The Paciello group recommends to use role=region and an aria-label with a meaningful value. That seems fine to me, with a little drawback: an element with role=region and an aria-label becomes an ARIA landmark. As such, it will be listed by screen readers in the page landmarks. Ideally, landmarks should be used only to mark the main regions of a page. This seems a minor annoyance compared to the greater benefit users will get from being able to scroll.

By fixing the accessibility of the Scrollable component, we could also consider to re-use it in more places to fix issues like #41500.

Worth also mentioning the technique to make scrollable elements accessible is already used in Core, see for example https://core.trac.wordpress.org/ticket/49211

Step-by-step reproduction instructions
Scrollable Firefox
  • Repeat the test using any other Webkit-based browser, e.g. Chrome.
  • See the Scrollable element is not focusable (focus lands on the button within the Scrollable):
Scrollable Chrome
Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

Dominant language
JavaScript
Stars
11.8k
Forks
4.9k
Avg merge
1d 21h
Merged PRs (30d)
524

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from WordPress/gutenberg

All issues in WordPress/gutenberg

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.