When I first started working at Qualtrics two years ago, we were a team of 16 UX designers, and no one was really talking about software accessibility or inclusive design. Today, our team has grown to more than 40 talented designers who talk about and design with accessibility in mind every day. Getting here has been an adventure, and I’d like to start sharing some of the processes and tools I’ve created to help our team design more accessible software.

The process that has made the greatest impact on building an accessibility-focused culture on our team is adding accessibility information to all of our design documents. Each design that is handed from our team to our engineering counterparts includes things like keyboard behaviors, labels, and semantics. This exercise improves product accessibility, but it also helps our design team build the muscles required to think about accessibility and disability-centered scenarios earlier in the design process. In the article below, you’ll find the basic guidelines we use for documenting accessibility in our design files.

Why document accessibility?

Documenting accessibility along with your regular design specs is a powerful way to communicate the importance of accessibility to product teams. It allows teams to have conversations about accessibility, and ensures that our experience for people who use assistive technology is thoughtful, intentional, and consistent. Designers are perfectly positioned to specify many of the things that are critical to an accessible experience like labels and page hierarchy.

Documenting accessibility is also an incredibly effective way to learn about accessibility, and can even be a stepping stone toward practicing true inclusive design. Designers who are equipped with the skills to document accessibility are able to see potential accessibility issues much earlier in the design process. In my work, I have observed that designers who define accessibility in their work are more likely to design with disability in mind from the very beginning of the design process. They are also more likely to advocate for accessibility in all aspects of their work.

How to document accessibility

In general, accessibility design documentation can be covered in two steps: defining keyboard behavior, and specifying semantic labels that can be understood by assistive technology. Separating these two pieces is helpful because it reduces complexity of design documents, and it helps us think through a broader range of scenarios beyond just screen reading.

Note that this documentation does not include some other important aspects of accessibility like sufficient color contrast, or making sure that content can be resized appropriately. These things should be covered by an inclusive design process that considers these requirements from the outset of the project.

Defining keyboard behavior

All interactive elements on the page should be accessible by keyboard. The key word here is interactive. So things like buttons, links, menus, and tooltips need to be keyboard accessible. Things like text and images that are not interactive do not need to be keyboard accessible. The following process is a good starting point for figuring out basic keyboard functionality:

1. Start simple. Start by adding all interactive elements to a tab loop that run from left to right and top to bottom on the page. It is also helpful to check out any existing keyboarding patterns in your product and make sure to apply those. Consistency is key to an accessible experience, and we want to make sure that we’re not deviating from the rest of the product unless it’s necessary.
2. Evaluate the order of elements. Does the tab order make sense? Does it provide any unnecessary difficulty for completing core tasks on the page? If the order feels wrong, consider whether it can be fixed by changing the layout of elements on screen (recommended), or if the tab order might need to be changed programmatically. Make sure to consider how interacting with elements on the page might change the tab order. For example, if you have a progressive disclosure UI, new items that appear should appear after the disclosure trigger so that they are discoverable to assistive technologies.
3. Evaluate the overall experience. Does the simplest solution feel like a good experience? Are there too many tab stops that might prevent someone from accomplishing core tasks? If the latter is true, consider how you might improve your solution by adding things like arrow key functionality or keyboard shortcuts (see a basic guide to common keyboarding patterns here).
4. Document keyboard behavior for any custom elements. If you have custom UI pieces that are not native HTML or an accessible component from a design system, you will need to document individual keyboard behaviors for each of them. Look at the WAI-ARIA authoring guidelines to see if a common pattern, or a combination of common patterns, can be applied to your custom elements.

Keyboard behavior is important for many people including people who simply prefer to navigate with a keyboard (e.g. “power users”). Note that keyboard behavior is separate from screen reader behavior. Someone who uses a screen reader might still use tab loops and keyboard shortcuts to navigate quickly to interactive elements, but screen readers have the added ability to focus on non-interactive elements. If you try to document both experiences simultaneously, you might find the task to be daunting. It is often easiest to separate keyboarding behavior from the semantics required by screen readers in order to create design documentation that is easier to understand.

Specifying semantic labels for assistive technology

The next piece of accessibility documentation involves categorizing and labeling components so that they can be understood by assistive technologies like screen readers. Your goal should be to provide information to assistive technology that is detailed enough for someone to understand what an on-screen element is and how they might interact with it. You can begin to do this by taking each element of your page and documenting the following:

1. Type: What type of thing is this?
2. Label: What is the name of this thing?
3. States & values: Does this thing have other properties that are critical to understand?

Type: What type of thing is this?

The type of an element is intended to give people using assistive technology enough information to know how something works. For example, if a screen reader focuses on a list of selectable options of type radio button group, the end user will understand that they can only select one option in the group. They will also infer they they can use arrow keys to change selection.

It is helpful to consider type as a promise. By assigning a type, we are promising people using assistive technology that something behaves in a certain way. It is critical that we assign types that accurately reflect what is on screen. For a list of common types and expected behaviors for each of them, WAI-ARIA Authoring Practices is a great place to start.

Focus on the output, not the implementation.

Specifying semantics can feel like walking a fine line between user experience and technical implementation. Always remember that your job as a designer is to focus on the output, and not the implementation. I don’t recommend that designers add ARIA (Accessible Rich Internet Applications) tags to their designs unless they are writing the code themselves. I won’t go into detail about ARIA here, but it is important to know that using ARIA incorrectly can overwrite native accessibility information and unintentionally cause a worse experience for people who use assistive technology. Therefore, it is important that developers consider carefully whether to implement ARIA or not in different situations. As a designer, you should focus on the pieces of information that are important for someone using assistive technology to understand, and lean on your engineering partners to figure out the best way to do this in code.

Label: What is the name of this thing?

Labels are intended to help users understand more information about what an element is or does. There are many elements that have visible labels already associated with them (e.g. most buttons have visible text on them that act as their label). Other elements, like icon buttons, don’t have an implicit label, and need to have an accessible label defined. In these cases, a label can be something that is only understood by assistive technology, or it can be visible elsewhere on the page. Labels can be complex, but the following tips can help with the majority of cases:

Tip 1: Try to find a visible label before adding an invisible one. In this example, we use a heading that is already on the page instead of writing a new label for the recent projects list. This improves localization since visible text is typically localized whereas hidden text is easily forgotten.

Adding whether or not a label is already visible will help developers know that they can refer to an existing piece of text rather than writing a new string into the code.

Tip 2: All labels on the page should be unique and specific. In this example, there are multiple action menus on one page, so we use the project title in the label so that someone using assistive technology can differentiate between them more easily.

Tip 3: Don’t repeat the component’s type in the label. This will cause assistive technologies to seem to read out the type twice (e.g. “search button button”)

States & values

Often, there are other properties that are important to understanding an element on screen. For example, a toggle button not only has a type and a label, but it also has a state: on or off. This information is critical to allowing someone to understand and use the element, so we should document these pieces of information as well.

Checkboxes have a checked or unchecked state, which needs to be communicated to assistive technologies

A quick note on design systems

Having an accessible design system is incredibly valuable, and reduces the time it takes to document accessibility. If using accessible components, many keyboard behaviors and semantics can be inherited and do not need to be re-defined in each spec. I recommend against re-defining these properties because that can leave a lot of room for error and misinterpretation. If a component is documented incorrectly, accessibility behaviors might get overwritten during implementation, causing a lack of consistency across a product.

Thank you for reading!

I hope this guide is helpful in your accessibility journey. If you try any of these practices, let me know how it goes in the comments below or find me on twitter.