docsearch
docsearch copied to clipboard
Accessibility issues with v3 dialog
Description
Taking the vanilla v3 playground https://codesandbox.io/s/docsearchjs-v3-playground-z9oxj as an example, there's a few accessibility-related oddities and issues that should be corrected. There's likely more, but a few things that caught my eye right away:
Incorrect role/attributes on dialog
Once the search dialog appears, the container for the search currently has role="button" aria-expanded="true" aria-haspopup="listbox"
and is made focusable using tabindex="0"
.
The container should instead have role="dialog" aria-modal="true"
. It can't be a "button" because buttons can't then have focusable controls inside them.
While focus has been made to cycle/remain inside the dialog, it's still possible for a keyboard user to jump back out and into the underlying page (navigating/setting focus through the page behind the semi-transparent overlay) - for instance, using Alt+d
to set focus to the browser's address bar and then Tab
bing forward.
Likewise, the underlying page is still exposed to assistive technologies (i.e. screen readers). Using aria-modal="true"
most modern ATs will ignore anything outside of the dialog, but for older browser/AT combinations, you'd probably want to use aria-hidden="true"
on the underlying page (for this to work properly though, the modal container itself must live outside of the element that you've set to aria-hidden="true"
, otherwise it will be hidden as well - and aria-hidden
can't be overridden in a child element by using aria-hidden="false"
either).
Video using Chrome/NVDA on Windows: after opening the dialog, exit form entry mode (NVDA + Space
) then use reading keys (cursor keys) to navigate right back out of the dialog and into the underlying page, as it's still exposed to AT.
https://user-images.githubusercontent.com/895831/164896236-ea2780b2-a1d0-4543-ac76-6f90fbbbf0f7.mp4
One way to work around this would be to either use the new <dialog>
element (which takes care of most of these), or to use the inert
attribute and relevant polyfill https://github.com/WICG/inert
Incorrect role/attributes on the search input itself
The input in the dialog itself should have a role="combobox"
, aria-expanded="..."
(true/false depending on whether or not results are shown) and aria-autocomplete="list"
. See the Editable Combobox With List Autocomplete Example from the WAI-ARIA Practices 1.2 combobox pattern.
Focus lost/not managed when closing dialog
When the dialog is closed, focus is currently simply lost (document.activeElement
goes to body
). While browsers often try to compensate for this, it's not reliable. The end result is that once the dialog is closed, users are bounced right back to the very start of the document.
Video using Chrome/JAWS on Windows. Note how once dialog is closed, JAWS' reading position is essentially the start of the page again (the heading before the search button).
https://user-images.githubusercontent.com/895831/164896357-8460d20c-4408-4965-a1ae-31f0f210cddb.mp4
This can be particularly problematic if there's a lot of content preceding the search button, as the user will have to navigate through all that again before reaching the position they were at when they triggered the dialog.
Ideally, once the dialog is closed, focus should be moved explicitly back to the search button that triggered the dialog in the first place.
Low contrast text
Assuming these are the default colours that come with this dialog out of the box, they have exceedingly low contrast
"No recent searches": grey (--docsearch-muted-color
/ #969FAF
) on off-white/light grey (--docsearch-modal-background
/ #f5f6f7
) has a contrast ratio of 2.5:1
The various keyboard hints an "Search by": grey (--docsearch-muted-color
/ #969FAF
) on white (--docsearch-footer-background
/ #fff
) has a contrast ratio of 2.7:1
These all fall below the recommended 4.5:1 minimum threshold from WCAG 2.1 1.4.3 Contrast (Minimum)
Likewise the keyboard shortcut SVGs have exceedingly low contrast, which fails WCAG 2.1 1.4.3 Contrast (Minimum) for the text-based ones ("Esc", and "Ctrl/K" in the initial search dialog trigger), and WCAG 2.1 1.4.11 Non-text Contrast (3:1 minimum threshold) for the arrow/enter key ones.
This relates to #1014 , which points out many of the same problems in v2 version.
sadly, there seems to be complete lack of interest/radio silence here...
Hey there, sorry I've been pretty busy lately! I'll make sure to answer issues and PRs this week!
Thanks a lot for the contribution!
merci, @shortcuts ... if you need any further info etc, feel free to ping
Hello, I found another accessibility error.
In the modal, the search field has no accessible name It only has one placeholder ('search doc'), which is not robust enough. It also has an aria-labelledby which is linked to an svg. Which isn't good either.
I think it would be better to add an aria-label directly on the input field.
It could also be nice to allow a translation of the label as well as the placeholder as for the other buttons
thank you
Hey there, sorry I've been pretty busy lately! I'll make sure to answer issues and PRs this week!
Thanks a lot for the contribution!
Any update? It's sort of annoying with all those accessibility issues when DocSearch is used everywhere now on so many open source projects.