WAI-ARIA Guide | Kalib Watson's Portfolio



I was hired at Jackson National Life to help facilitate the accessibility evaluation and remediation of their websites. I had previously worked for the company that had reviewed their website accessibility, and therefore already had a good understanding of their accessibility knowledge. After fully evaluating their site and creating a project process, I worked with Jackson’s Senior Web Developers to remediate the accessibility issues found. During this process, we discovered the need for a WAI-ARIA guide.


Jackson’s remediation process began with my outlining the issues found with Jackson’s site and indicating potential solutions to those issues. After creating a spreadsheet of these different issues and solutions, which was approved by the Web Accessibility Committee, I brought my findings to one of Jackson’s Senior Web Developers.

A spreadsheet of accessibility violations, each associated with a probable cause, correction methods, and resources to reference. In the search column we collected HTML classes or ids that were related to the issue.

The minimal information provided made the information difficult to understand for someone new to accessibility. This is completely fair, and was expected because the language I used was supposed to be a quick overview of the issues at hand, not a comprehensive account. I also saw this as an opportunity to introduce Jackson’s developers to accessibility language and concepts, so talking this through would be more useful anyway. After a one-on-one meeting where I went over the issues and solutions with my developer counterpart, we had a better understanding both of what was possible for Jackson’s site, and of why we were making these changes.

However, I didn’t just leave this senior developer to do the work. I made it a point to schedule regular weekly meetings where we could sit down and work through the changes being made, and ensure that those changes produced the appropriate results (I was currently the only one allowed access to screen reader software). This was due both to the Web Development team’s lack of accessibility knowledge, and because I wanted insight as to how these problems could be tackled in various ways. Even if we were simply adding a WAI-ARIA attribute to the page it wasn’t always straightforward based on Jackson’s technology stack.

When we began needing to use ARIA for solutions around changing content, it became clear that my Senior Developer counterpart was having trouble understanding the ARIA documentation without my in-person help. This made it difficult to progress our work, as I was only in the office two days per week (ah, the life of an intern). I asked why he was struggling to understand how to use ARIA, and he responded that the documentation organization made it difficult to find information on how to use ARIA. Even then, the documentation was often vague about how to use the technology.

These are actually the same complaints that I would likely have around the W3C documentation of ARIA if I was coming to the technology for the first time. The docs are not written as a guide for developers to use the technology, but more as an outline of what the technology is meant to do. The difference is that not many examples are given, and the more specific use case information is buried underneath paragraphs of spec information, making the docs hard to use for every day development, but great for learning everything about ARIA. (It’s worth mentioning that Mozilla writes wonderful WAI-ARIA docs, but they aren’t even close to explaining a majority of ARIA attributes.)

The WAI-ARIA docs page which shows documentation global states and properties, with a list of states and properties, which are linked to more detailed information on the state or property.

I quickly set out to hunt down useful WAI-ARIA guides, but found that many useful resources were dispersed. Someone had written a blog post about aria-live, and another had answered a Stack Overflow (an online community for programmers) question about aria-relevant, but no one had put together a comprehensive guide that was easy to read and applicable to every day ARIA use.

So, this is what I set out to do.

I began by parsing the WAI-ARIA W3C documentation and looking over the different kinds of ARIA attributes to understand the different kinds of functionality they provided. This way, I could separate the attributes into groups that developers could visit when creating functionality. The W3C does group ARIA attributes by Role, State, or Property, but the terminology used here isn’t always reflective of what front-end developers’ are attempting to create. Although not perfect, the groups I decided upon were Page Landmarks, Organizing and Relating Content, Content Updates and Alerts, Input Elements and Forms, and Custom Elements. These sections were meant to relate to the kinds of elements or functionality that developers would be building, so they could relate their current work to the relevant ARIA attributes.

I then had to decide how to organize information about the attributes themselves, and which attributes would be the most relevant. I didn’t necessarily want to include every attribute, because some are meant for very specific use cases (e.g. the separator role, which is only meant to be used if a separator is visible and also moveable and focusable). These very specific attributes would probably clutter the space for someone looking to simply watch for changes to a page.

Understanding Jackson’s development cycle and web products was essential to making this guide useful, as they don’t build very intricate web apps or fancy functionality. This is good for accessibility purposes because it keeps things simple, and it also means we can leave out those ARIA attributes that aren’t very commonly useful. It also meant that I could determine which pieces of information Jackson’s developers would probably want to see when looking for an ARIA attribute to use.

I decided to list out different information for roles than for states and properties. An element can only have one ARIA role, and it is set by writing role = <ARIA role> on the element. States and properties are attributes in themselves, and can have multiple values. An example of this would be the aria-live property, which can be set to assertive, off, or polite (e.g. aria-live = “assertive”). However, ARIA roles are the value for the attribute, such as the timer role, which would be set by writing role = “timer”. As such, when I explained a role in the ARIA guide I only listed the name and examples of use, instead of also having to explain attribute values.

What I was left with was a comprehensive guide to useful ARIA attributes for Jackson’s developers. I gave this information to the Senior Developer that I regularly worked with, and also to a few other developers who hadn’t used ARIA before to see if they thought it would be useful.

The overall feedback was that the guide was very helpful, and organized information in a way that made finding ARIA information much simpler. However, developers wanted to be able to jump between related ARIA attributes easily, so I connected these attributes by listing related ARIA attributes for each attribute description, and then linking these to the description of the related attributes.

Rows have two columns, a role name column, and an explanation column. Under the explanation column, related ARIA attributes are listed and linked to the respective attribute.

With the use of the guide, developers have been able to reference ARIA information without needing to ask me for clarification. I do enjoy answering questions about how to use ARIA, and sometimes do have to answer questions about the contextual use of an ARIA attribute, but this allows the project to continue when I am not available. It has also made this information available for others in the organization to view if they’re interested in learning more about accessible technologies.

The guide is now complete, so you may download the Word version of the ARIA GuideDownloads a word document if you're interested!


Throughout the development of this guide, not only was I able to greatly expand my knowledge of WAI-ARIA, but I was also able to explore different ways of applying ARIA to solve many problems. Doing this with a Senior Web Developer was a huge benefit, as I was able to see his process when figuring out a not-so-simple solution.

I was also able to make a big impact on my team through posting this guide in Jackson’s web development resources, as now developers can answer questions about ARIA when I might not be available. This both frees me to do more work and allows developers to progress through our accessibility check points when I’m not around.