How We're Improving Accessibility on PSPDFKit for Web

At PSPDFKit, we value inclusion and building solutions that can be used by everyone. Our efforts in this regard have resulted in increased awareness and adoption of inclusive language within the company, as well as accessibility improvements across our products, such as PSPDFKit for iOS and PSPDFKit for Android.

In the past, we’ve talked about how we build accessible modals on PSPDFKit for Web. And now, our two latest major releases of PSPDFKit for Web — 2020.5.0 and 2020.6.0 — feature UI accessibility improvements. In this blog post, I’ll outline some of the main areas our efforts have been focusing on, with examples of particular UI elements that we’ve been reworking.

Improved Support for Screen Readers on Browse Mode

On Windows, screen readers such as NVDA and JAWS can operate on two main modes:

• Browse (or virtual cursor) mode: The screen reader intercepts certain keystrokes instead of propagating them to a webpage, allowing users to more easily read content without necessarily relying on focusable elements of the page. This mode features a “virtual cursor,” which can be moved around the page using certain keyboard commands that are part of the screen reader configuration.

• Focus (or forms) mode: Keystrokes are not intercepted by the screen reader and instead are propagated to a webpage as usual. Users can fill out form inputs or tab through focusable elements and the screen reader will adjust accordingly and announce the current state of the interaction.

There’s a W3C standard called WAI-ARIA, or simply ARIA, that defines a set of HTML attributes to adjust the semantic and accessibility descriptions of the contents of an HTML document. Within ARIA, there’s a role known as application. It tells assistive technology (AT) to avoid intercepting keystrokes as it would on a regular document, since the underlying content makes heavy use of custom interactions and widgets outside of a regular DOM structure.

The PSPDFKit for Web main canvas UI — where the spreads of pages are laid out and where you can draw and position different annotations — is one example of a collection of widgets and custom interactions that aren’t part of a regular DOM structure. However, our toolbars are made out of semantic native HTML elements that are widely supported by AT. For this reason, we’ve taken special care to only use the application role on subtrees of our DOM structure where it makes sense. In turn, this allows for regular use of screen readers in browse mode elsewhere in the viewer UI.

Interaction with Dropdowns

Dropdowns are an essential part of the PSPDFKit UI, but what seems to be a simple form control can be deceptive. A dropdown can be part of a composite widget such as a combobox, listbox, or menu.

In the following video, you can see how interacting with one of the main toolbar dropdowns with both the keyboard and a screen reader — in this case, VoiceOver on macOS — worked on previous versions of PSPDFKit for Web.

Hear how when the focus is set on the freeform highlight button, VoiceOver announces the following: “Freeform Highlight, button. You are currently on a button, inside of a Menu pop-up combo box.”

This might be confusing for screen reader users, as having a button inside of a combobox is not usual. According to the WAI-ARIA specification, a combobox is: “A composite widget containing a single-line textbox and another element, such as a listbox or grid, that can dynamically pop up to help the user set the value of the textbox.”

In our case, there’s no textbox present, and the freeform highlight button doesn’t expand the list of available options. The button that expands the list of available options is the one following the freeform highlight button in the focus order, which VoiceOver announces as: “Ink tools, toggle menu, menu pop up, button. You are currently on a button, inside of a Menu pop-up combo box.”

Again, this button, which is the one that toggles the list of available ink tools, is announced as part of the same combobox.

Another confusing aspect of the previous implementation of PSPDFKit for Web was a bug that resulted in an incorrect first announcement of the amount of available dropdown items when the dropdown was expanded. This was followed by a second announcement (when first using the arrow keys to navigate) with the correct number of items. Additionally, using the Space key once the desired option was focused didn’t apply the change; only the Enter key worked.

At the end of the video, you can also hear that VoiceOver incorrectly reads “Line” when the desired option is selected.

The video below demonstrates the updated version of this interaction.

Now the first button (in this case, the drawing button) is announced as a toggle button, since it toggles whether or not the drawing button is activated. Furthermore, when the focus is on the ink tools button, you can observe that it’s also announced as a toggle button. The combobox role was replaced with WAI-ARIA menu semantics following the recommendations outlined in the WAI-ARIA Authoring Practices document.

ℹ️ Note: There’s a limited amount of scenarios where using the menu ARIA role makes sense. One such example is that of highly interactive applications, like PSPDFKit or Google Docs, which have menus that resemble those of native desktop applications. Check out this thorough article by Heydon Pickering in which different menu implementations are outlined and the different roles to use on each case are mentioned.

With our latest changes, when the dropdown menu is expanded, the screen reader announces the currently selected option, and on each Up/Down, the selection is updated and properly announced. Pressing the Space key now also works to activate the selected option and make the screen reader announce that the menu is now collapsed.

Navigation through Responsive Groups

On smaller screens, some toolbar items are hidden under what we call a responsive group, and instead, a single item is shown on the main toolbar. Once a responsive group item is activated, the toolbar transitions to display only the items in the responsive group.

In the video above, which demonstrates the former implementation, once the annotations button is activated, the focus is still placed on it. Tabbing through the toolbar doesn’t work as expected, since the focus is moving through the remaining items of the toolbar, which are now hidden, instead of those in the responsive group.

Multiple subsequent Tab keystrokes are required for reaching the close button of the responsive group. When we activate it, the focus moves to the end of the main toolbar, making it confusing to navigate through the viewer.

Let’s compare this to the new version.

When the responsive group is activated, the focus is automatically set on the first item of the responsive group. In this case, it’s the drawing toggle button. Notice how the screen reader announces “Annotations, web dialog.” This is because we’re adopting a non-modal dialog to make AT users aware of which responsive group they’re currently navigating. This is also useful when navigating away from the responsive group while it’s open; when you navigate back to it, the screen reader reminds you of which responsive group is currently open.

Additionally, since AT users expect the Escape key to close dialogs, support for it has been added as well, as shown in the video. When the responsive group is closed, focus is restored to the item that initially activated it.

Navigation through Annotation Toolbars

Previously, using the keyboard to navigate through the annotation toolbar items posed some inconveniences. The icon for each annotation property control — which on smaller-width devices serves as a button to activate its responsive group — shouldn’t be focusable on desktop. However, users were able to focus on these items by using the keyboard and activating the item, which caused the responsive group to appear even on desktops and large devices. After closing the responsive group, the focus got lost and it was necessary to guess one’s way back to the annotation toolbar.

Notice how before, when the focus was set on the opacity dropdown button, VoiceOver initially announced “Opacity, group,” and after pressing Tab a second time, “Opacity, button, Opacity, group.” Due to a bug, two Tab key presses were required to navigate through each annotation property button.

On our latest update, the icon for each property is no longer focusable, so now the focus is initially set on the color radio group, and the arrow keys are used to change the currently selected color.

Above, notice how the opacity button now only has a single tab stop, and now the current value of the property is announced (100 percent in this case), along with its state (collapsed or expanded). The blend mode dropdown has also been changed to work better with the keyboard and AT. Now, when the new value is selected, the screen reader announces that the button is collapsed again, and it also announces the new selected value.

Navigation through Annotation Responsive Groups

The same problems we observed in the main toolbar responsive groups were also present in the annotation responsive group.

Above, notice how once a responsive group is opened, the keyboard focus isn’t moved, so we’re still able to navigate through the visibly hidden buttons while the screen reader announces them. After tabbing forward for a while, we finally reach the responsive group. But once again, when the close button is activated, the focus isn’t correctly restored to the original button that activated the responsive group.

To fix this, non-modal dialog semantics were added to the responsive groups to aid AT users. Now, when an individual annotation responsive group is activated, the focus is correctly placed on the first item of the responsive group. The Escape key now also works to close the dialog and restore the focus to the previous item accordingly.

Improved Assistive Technology Announcements

We tested and identified different areas where improvements were needed for better AT support. Using VoiceOver on macOS and iOS, NVDA on Windows, and TalkBack on Android, we’ve identified some areas that could do with some adjustments to name, role, and value.

Let’s use the color dropdown as an example. The video below shows how macOS VoiceOver used to announce it.

When the focus is on the color dropdown, VoiceOver announces “Toolbar tools, toggle menu, menu pop up, button” rather than using a descriptive name for that particular control. Once the list is expanded, the bug regarding the available options is also present, and when one option is selected, “18” is incorrectly announced by the screen reader.

Here’s how it works after making some changes.

Now, as soon as the focus is placed on the color button, the screen reader announces its name (“Color”), role (“list box pop up collapsed, button”), and value (“Black”) accurately. When the list is expanded, each option is announced along with its position, and once a selection is made, the screen reader announces that the pop-up has been collapsed, but this time it announces the updated color.

Color Contrast

We designed the UI and our default light and dark themes with the goal of achieving WCAG 2.1 Level AAA conformance for text contrast and at least AA conformance for icons.

If you’re customizing the PSPDFKit appearance, please consider contrast ratios and use tools such as the Firefox Accessibility Inspector, CCA, or the WebAIM Contrast Checker to ensure proper support for all of your users’ needs.

Further Improvements

We’ve been also working on improving how annotations can be created solely using the keyboard and without the intervention of a pointing device.

You can place a comment marker annotation without using a pointer device by activating the comment toolbar item using the Enter or Space keys, entering the comment body, and then using the arrow keys to position the comment on the desired spot on the page. You can also add the Shift modifier key to move the annotation in higher steps.

It’s also possible to create text and note annotations this way. In the case of those annotations, you can use the Shift + Enter key combination to finish editing the text content, and then proceed to position the new annotation at the desired spot.

Additionally, our accessibility strings are localized for all of our built-in languages so that AT can properly parse and read out their contents.

Finally, the roles of multiple elements of our UI were adjusted to better comply with the WAI-ARIA specification and to convey more meaningful information for all users — especially while they’re navigating through the page contents, annotations, and comment threads using the keyboard, screen readers, and other AT.

Final Thoughts

Continuous improvement is one of our Core Values at PSPDFKit. This includes giving priority to accessibility issues, and our internal practices are constantly adjusted to identify these issues more quickly. As developers, it’s our responsibility to be aware of the needs of our users and ensure that our products don’t exclude groups of people.

We hope you’ll enjoy the improved experience of PSPDFKit for Web, and please don’t hesitate to reach out to us at [email protected] if you have any accessibility concern that you’d like to share with us.