This is a guide on how to test accessibility on Gutenberg. This is a living document that can be improved over time with new approaches and techniques.
Getting started
Make sure you have set up your local environment following the instructions on Getting Started.
Keyboard testing
In addition to mouse, make sure the interface is fully accessible for keyboard-only users. Try to interact with your changes using only the keyboard:
- Make sure interactive elements can receive focus using Tab, Shift+Tab or arrow keys.
- Buttons should be activable by pressing Enter and Space.
- Radio buttons and checkboxes should be checked by pressing Space, but not Enter.
If the elements can be focused using arrow keys, but not Tab or Shift+Tab, consider grouping them using one of the WAI-ARIA composite subclass roles, such as toolbar, menu and listbox.
If the interaction is complex or confusing to you, consider that it’s also going to impact keyboard-only users.
Screen reader testing
According to the WebAIM: Screen Reader User Survey #8 Results, these are the most common screen reader and browser combinations:
| Screen Reader & Browser | # of Respondents | % of Respondents |
|---|---|---|
| JAWS with Chrome | 259 | 21.4% |
| NVDA with Firefox | 237 | 19.6% |
| NVDA with Chrome | 218 | 18.0% |
| JAWS with Internet Explorer | 139 | 11.5% |
| VoiceOver with Safari | 110 | 9.1% |
| JAWS with Firefox | 71 | 5.9% |
| VoiceOver with Chrome | 36 | 3.0% |
| NVDA with Internet Explorer | 14 | 1.2% |
| Other combinations | 126 | 10.4% |
When testing with screen readers, try to use some of the combinations at the top of this list. For example, when testing with VoiceOver, it’s preferable to use Safari.
NVDA with Firefox
NVDA is a free screen reader for Windows and the most popular one.
After installing it, you can activate NVDA by opening the app as you would do with other programs. An icon will appear on the System Tray where you have access to more options. It’s recommended to enable the “Speech viewer” dialog so it’s easier to demonstrate what’s being announced by NVDA when you take screenshots.
While in the Gutenberg editor, with NVDA activated, you can press Insert+F7 to open the Elements List where you can find elements grouped by their types, such as links, headings, form fields, buttons and landmarks.
Make sure the elements have proper labels and prefer to navigate through landmarks and then use Tab and arrow keys to move through the elements within the landmarks.
VoiceOver with Safari
VoiceOver is the native screen reader on macOS. You can enable it on System Preferences > Accessibility > VoiceOver > Enable VoiceOver or by quickly pressing Touch ID three times while holding the Command key.
While in the Gutenberg editor, with VoiceOver activated, you can press Control+Option+U to open the Rotor and find more easily the different regions and elements on the page. This is also a good way to make sure elements are labelled correctly. If a name on this list doesn’t make sense, it should be improved.
Prefer to select a region or another larger area to begin with instead of individual elements on the Rotor so you can better test the navigation within that region.
Once you find the region you want to interact with, you can use Control+Option plus right or left arrow keys to move to the next or previous elements on the page. Then, follow the instructions that VoiceOver will announce.