The Clarity Design System has been focusing heavily on making accessibility improvements.

A Commitment to Accessibility

Jeremy Wilken
Aug 6 · 8 min read

Inclusivity and accessibility has always been part of Clarity’s DNA, and recently we’re reaffirming our commitment and investment.

Accessibility is a vital aspect of building applications, and we take our responsibility seriously as a design system to enable you to build accessible applications.

We’ve built a world-class accessibility team at VMware to review and identify gaps, problems, and suboptimal experiences for all users. The result is a list of many accessibility improvements and fixes that we are working hard to release for Clarity in the near term.

We’d like to share some of the most common types of issues we encountered, what we are doing to address them, and how you can do the same in your projects and applications. We firmly believe that these improvements are good for all users — not just those using assistive technologies to use our applications.

What did we find?

The mindset we had to adopt was focusing on how all users might engage with our components, and test it out with a number of different approaches like a screen reader and only using a keyboard. There were a few common issues we found in Clarity, and chances are good that your project might also have missed some cases. We’ll cover some of the big ones and share a bit about how you can address them in your applications as well.

Departure from expected HTML and ARIA semantics

Native HTML elements are generally well defined and understood by browsers and assistive technologies. However, HTML is also limited in its capabilities and component libraries like Clarity exist to enhance HTML’s capabilities. To that end, ARIA is the specification put together by the W3C about how applications and components should behave to adhere to accessibility principles.

When possible, we follow to standard HTML structure inside of components to avoid having to manually override and inform the browser about various ARIA semantics. For example, we use a semantic list using ul and li instead of non-semantic elements like div that are styled to look like a list.

Screenshot of the Clarity Tabs Overflow functionality, which is not a behavior defined by ARIA.

With Clarity, some of our components have features and functionality that go beyond what is defined by ARIA. One example is inside of our Tabs component. We support an overflow option that displays a button with a dropdown list of additional tabs, so that if there are many tabs some can be hidden in a dropdown menu. The problem is that ARIA has no concept defined for overflow tabs, and our implementation was inaccessible to screen readers.

It requires a lot of creativity, prototyping, and patience to address issues with departures from ARIA. It might require reworking the HTML structure, adding additional ARIA attributes, managing the focus manually, and/or handling keyboard navigation. For us to address these, we often spent a lot of time trying out various scenarios to see exactly what worked and what didn’t, in order to find the balance of best experience for all users, minimizing breaking changes, and creating the simplest solution.

Buttons without accessible names

Buttons should always include meaningful text so a screen reader can read it that aloud to the user and to help with all users understanding of a button’s purpose. Here is one such example of a button with only an icon inside, which causes the screen reader to simply state “You are on a button” without context.

<button class="btn btn-primary" type="button">
<clr-icon shape="close"></clr-icon>
Screenshot of Clarity Datagrid with example of icon buttons, such as the filter icon in the column headers and caret icons in rows.

One example from Clarity was in our Datagrid component where there are some icon buttons, such as the icon button for the filter dropdown and icon button for expanding the row.

To address this shortcoming, you can add text into the button itself or add ARIA attributes to inform screen readers what to say. This allows all buttons and interactive elements to have an accessible name. This can also happen to elements that are interactive (that have click handlers) but might not always be buttons (though they should be when possible).

<button class="btn btn-primary" type="button" aria-label="Close">
<clr-icon shape="close"></clr-icon>

Here we’ve added aria-label="Close" to the button, which addresses the core problem for screen readers. We are adding aria-label attributes or text inside of buttons in all of our interactive elements to ensure screen readers can announce clearly what these elements are and what they do. There are also additional ARIA attributes that we’ve applied in some cases where it makes sense to help describe a button, for example the aria-expanded is used to inform the screen reader about expanded or collapsed state of an element.

Focus management

For keyboard only users, managing focus is vital. We found a few cases where focus was lost to the body of the page or didn’t move appropriately with changing content. This leads to confusion for the keyboard user about where they are in the context of the page, and breaks accessibility expectations.

Example of original behavior for Datagrid focus, where it remained while the user interacts with the Datagrid
Example of updated behavior, where as the user interacts with the pagination, the focus moves back to the top of the Datagrid.

For example, as you navigate the pagination control in the Datagrid using a keyboard, the focus would remain on the next button while you changed pages. This problem is that keyboard users would have to move focus manually back to the top of the Datagrid to start reading the content.

A more natural experience is to move the focus to the top of the content instead. The updated experience will move focus to the top of the Datagrid when the pages change, so the user can immediately access the new content rather than having to manually navigate around to find it.

The main challenges arose in cases where interacting with a component caused content to change (which is very common in applications), and we had to think critically about each interaction to ensure focus moved to the most logical place. There is no magic solution for these cases, as each interaction can be nuanced. They also can be difficult to identify unless you also try to use your application with a keyboard and screen reader.

Keyboard navigation

Users may expect certain keyboard combinations will work to move the focus or reading cursor around the screen, some of which require component creators to implement functionality to support that. This is particularly true of scenarios where ARIA doesn’t describe the functionality in question, or if you have used different markup than expected.

Our Tree View component will be enhanced to support arrow key navigation so you can navigate up, down, in, and out of a tree and its nodes quickly. While you could do this previously using the tab key, that could be laborious in cases where there are a lot of items to navigate. This is also a functionality defined by ARIA, but sometimes we have to evaluate and discover the best usability when ARIA doesn’t describe a particular behavior.

The challenge here is to avoid adding event listeners unless necessary to keep the application performant, as well as understanding what keyboard shortcuts are the expected behaviors. Some of them are well known shortcuts, such as the expectation that CMD+S on macOS or CTRL+S on Windows will save a file, while others might be ones that are unique to your component.

Announcing meaningful updates

We often display text and updates on the page, which sighted users can read without much problem but users with screen readers are unaware of. We can use the aria-live functionality to announce important information to a screen reader, kind of like an announcement that is made over the intercom of a store.

In our case, we have a challenge with alerts not being read out loud when the screen reader’s cursor is not in the alert, causing them to miss the information in the alert. We’re addressing this by adding aria-live with the content of the alert, which will inform the screen reader of this new content and read it out. The challenge is being sure you do this when appropriate, because it can be overwhelming if the screen reader is constantly reading updates when the user wants to do something.

Timeline and support policy

We’ve wrapped up our testing phase and have moved onto addressing the issues. Our goal is to address these issues in the coming months, well before 3.0 is scheduled. We expect to be through the high priority issues in the coming weeks.

Our plan is to ensure that all of the fixes we make are available in both Clarity 1.x and 2.x. Should there be any breaking changes required to solve a particular issue, we are committed to finding a way to make it opt-in.

If you are using a version of Clarity below 1.x, you should update to 1.x or greater to get these fixes and enhancements.

Should additional issues be discovered, we’ll continue to address them as part of our ongoing maintenance and support.

Applications are responsible for accessibility

As a design system, we are able to provide a lot of accessibility support out of the box. This helps make applications that use Clarity accessible to a certain degree, but there is still work to be done by the application to reach complete accessibility.

Applications are ultimately responsible for handling accessibility for everything they implement. In some cases, Clarity recommends certain patterns to ensure your integration is accessible.

For example, all form fields should have proper labels and Clarity is unable to provide them since applications control their form fields. Any best practices that we have adopted internally are best practices for applications as well.

Likewise, if you are loading content dynamically, announce the action that is happening and its outcome to the user. This is something custom for your application, though Clarity is building a loading indicator with proper support for you to use.

At the end of the day, applications still need to review and validate their design and implementations for accessibility.

Build for inclusivity

We hope that you are inspired to expand the abilities of your application so it better supports all users. There is much to learn and share, so if you learn something in your efforts, please share them back with the community. Together we can make a better environment for all users.

If you’re interested in helping us build the accessibility program at VMware, we’re hiring an Accessibility Operations Lead. Read more about the position here.

If you have any commentary about accessibility, feel free to comment below or reach out to us on our Twitter @VMwareClarity.

Clarity Design System

Clarity is an open source design system that brings together UX guidelines, an HTML/CSS framework, and Angular components. Visit our website here:

Thanks to Scott Mathis, Sheri Byrne-Haber, Cory Rylan, Jeeyun Lim, Jehad Affoneh, Grace Noh, and Bonnie Zhang

Jeremy Wilken

Written by

I talk to my devices. Host of Design for Voice podcast. Google Developer Expert for Assistant and Angular. Work on @VMwareClarity project.

Clarity Design System

Clarity is an open source design system that brings together UX guidelines, an HTML/CSS framework, and Angular components. Visit our website here:

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade