Regarding Accessibility in Gutenberg

There have been some important questions and concerns about accessibility in the upcoming new editor. First and foremost, it goes without saying that work on these areas is never finished and we can always go a step further in improving the experience for all users of WordPress. That is a big part of the project’s core mission. We need to continue to develop close feedback loops with different users interacting through their preferred tools to make sure what we build is relevant to their experiences.

A large amount of work and effort has gone in building mechanisms necessary to make the editor accessible for a wide user base, some of which will be highlighted in this post. For example, it is entirely possible right now to recreate the “demo post” that comes with the Gutenberg plugin using the keyboard. In many ways, these tools are better and more sophisticated than what we offer in the current editor.

There are bugs, of course, and rough edges to still address. From release to release these have been refined and iterated by many people and I want to thank all of them for their hard work. There are about 270 tickets closed specifically labeled “accessibility,” and around 90 more that remain open, so we still need your help. The goal is to make this experience as seamless as possible for all users, so if you are encountering an issue, please share it so it can be addressed.

Let’s go over some of the accessibility related capabilities that exist right now in the new editor…

The cropping is a bit too tight on the video and doesn’t show the “regions” in all its crystal clarity

Region Navigation

Gutenberg introduces a mechanism for navigating across the major regions of the application with a simple keyboard shortcut that cycles through them — header, content, sidebar, publish flow are included. A user can press “Control + `” or “Alt + Shift + n” (this can vary based on keyboard configuration) to focus the different areas at any time. This is an entirely new addition to WordPress with the hope of streamlining navigation without a pointer device.

Keyboard Shortcuts

There is a wide array of keyboard shortcuts available to help access different functionality. These are built in a way that can be extended and integrated in testing flows. A panel listing most of the shortcuts can be accessed from the menu at the top of the editor or by pressing “Ctrl + Alt + h”. Tooltips used throughout the application also display their corresponding shortcuts when available. They range from editor functionality (save, undo, etc), to formatting options (adding links, italics, etc), to inserting new blocks (just type “/” on a new line), to navigation and selection of blocks. Keyboard shortcuts are contextual to the OS and displayed as such in tooltips and menus.

(Note: All keyboard shortcuts listed are available in Windows. MacOS includes these shortcuts but with different combinations; see the keyboard shortcuts panel in Gutenberg to see them all.)

Block Navigation

The main mechanism for traversing blocks is using the arrow keys. There is also a Block Navigation panel that allows keyboard users to quickly navigate through blocks without having to tab through their controls or flow through their contents.

Slash Command and Insertion

It’s important to be able to add new blocks and manipulate them with ease without leaving the keyboard. There is a very convenient shortcut (“/”) to add new blocks. There are also shortcuts for adding a new block before or after the current block. If there are ideas on how to surface these better and contextually to users, please chime in!

Toolbar and Sidebar

Main block tools are grouped in the toolbar, while secondary actions are often deferred to the sidebar panel and both can be accessed through keyboard navigation. The sidebar can be toggled with a single keyboard command (“Shift + Command + ,“). The toolbar — whether it’s docked at the top of the block or at the top of the editor — can be accessed with “Alt + F10”. Using the arrow keys, all focusable areas of a block can be navigated to (including things like the optional caption field for an image or an embed, or the source of a quote).

High-Contrast Mode

We’ve worked hard to fix edge cases for users of high-contrast mode in Windows, to ensure users with vision issues that require high-contrast mode do not encounter bugs when using Gutenberg.


Gutenberg is built using JavaScript components that are published on NPM and these components can be re-used by third-party blocks. This presents the potential for raising the bar for accessibility across the ecosystem; when improvements are made to accessibility in Gutenberg, third-party blocks using our large list of components get these improvements without needing to update their code. This is a way to scale accessibility thinking beyond what can be controlled in core.

These components not only reduce the overhead of having to replicate UI controls and solutions, but also ensure consistency. Consistency is important so that learned behaviours can be transferred and interactions work as expected. Many of these components have built-in accessibility mechanisms, from things like containing focus within dropdown menus or modals, arrow navigation of menu items, to supporting and automatically assigning aria properties when possible. In combination with guidelines and tests, it can help ensure the editor and its extensions remain accessible to users beyond what core offers.

Helping the User Create Accessible Content

The editor also introduces helpful messages to the end user when using color combinations that might have contrast issues (it also takes font sizes into account for readability measurement) or when adding heading elements in the wrong order (like an h4 following an h2, for example). This is also a new addition that has the potential of both helping users learn and produce accessible content for their viewers, expanding WordPress’s commitment to web standards. These tools are also available for reuse by third-party developers in their own blocks.

Furthermore, the controlled nature of blocks means that the final HTML generated can remain semantic and accessible for viewers.


To speed up the process of content creation, there are quick formatting shortcuts that can be used when starting new lines. For example, using an asterisk followed by a space would automatically create a list block while using “##” would create a heading block.

Audible Messages

Included in the WordPress/a11y npm package is a speak function that allows developers to announce changes in the UI for users with visual impairments. Adding speech commands to a JavaScript-heavy application like Gutenberg ensures users with visual impairments have changes in the UI announced to them. Our speech utilities include the ability to specify how assertive the speech should be, so users are alerted to important UI changes immediately. (Example: sidebar settings change)

Aria properties are also used throughout the application to inform about the purposes and meaning of controls and actions. This is an ongoing process that has benefited tremendously from the help of people like @afercia with a lot of experience in testing with different screenreaders and their intricacies (JAWS and NVDA, MacOS VoiceOver). It’s also a good place to lend a hand if you are familiar with them.

Automated End-to-End Tests

We have the ability to run and automate a full editor session in a browser. Using this, we can test a sequence of operations with the keyboard and validate the results. This will allow the editor to continue to improve while making sure things remain accessible and don’t regress interaction-wise. As an example: we test Block Navigation entirely with the keyboard and no mouse controls to ensure it is fully usable by keyboard users. This hasn’t been a well communicated capability, but it’s a great area for contributors to get involved with.

Speaking of such tests, this is a fully automated test that replicates the “demo” post using keyboard commands:

This is an automated test. It’d be great to see more of these tests covering a wide range of interactions and real use cases

Current Issues and Improvements

The above is a partial picture of what is currently in place. There is still work to do, and I’m confident we’ll be able to get there together. The following are some of the pending bug fixes and ongoing improvements on multiple fronts, many of which are landing in the next releases:

There’s also work to be done in better exposing many of these tools to end-users, specially around non-obvious keyboard navigation commands.

Huge thanks to everyone that has tested and contributed issues related to accessibility. It helps tremendously.

All in all, there is a significant volume of accessibility-specific tools and functionalities included in the plugin that already surpass comparable capabilities in the Classic Editor. This was the result of the work of multiple people’s collaboration that I hope continues to evolve and improve. It hasn’t always been easy among the product challenges and the new technologies involved and we need to collaborate better — communication is something that we need to always nurture and foster.

— Thanks to @lonelyvegan for collaborating on this post and the ongoing work.