Real-time accessibility testing with Storybook

How Storybook 5.1 makes a11y easy

Alexander Wilson
Jun 5, 2019 · 5 min read

Making a website inclusive becomes more difficult the longer you put accessibility on hold. Auditing tools today provide helpful information at the page-level but don’t pinpoint violations at the component-level.

Storybook 5.1’s updated accessibility (a11y) addon makes it easy for you to QA accessibility by highlighting areas of improvement as you code. That helps developers ensure components meet accessibility standards before shipping.

This update was the result of amazing community collaboration. Development by Alex Wilson (me!). Prototyping and review by Arman Sargsyan. UX by Storybook designer Dominic Nguyen. This work builds on the addon contribution from Jaco Bovenschen.

Why accessibility?

Accessibility means all people, including those with disabilities, can understand, navigate, and interact with your app. Offline examples include wheelchair-enabled buildings, crosswalk signs with audible instructions. Online we provide alternative ways to access content such as using the tab key and a screen reader to traverse a site.

Making sites accessible is the right thing to do and in some locations, it’s been written into law. By designing for all groups of people, you have the opportunity to gain more potential users and create better experiences because more thought has gone into the user’s needs.

Storybook simplifies accessibility

Storybook is an open source platform that allows you to document, view and test many permutations of your HTML and CSS components within an isolated environment. Once this environment is set up, you can develop within Storybook with its use of hot-reloading and test those components with a number of the Storybook addons including viewport testing, unit testing, accessibility testing, and more.

The “A11y Addon” for Storybook runs on top of the Axe Accessibility Engine developed by Deque Systems. This is the same engine used by Google Lighthouse to test and score entire web pages.

Storybook allows users to choose their own subset of rules and features from the Axe API in their Storybook configuration. Axe provides many rules to pick from and there are options to include or exclude them by category type, each of which is based on one of the following accessibility standards: WCAG A, WCAG AA, Section 508, and Best Practice.

How to use the a11y addon

The addon displays three tabs: violations, passes, and incompletions. Axe defines “incomplete” as a rule state that “occur(s) when Axe can tell that a rule does not definitely pass, but cannot quite tell whether it definitely fails — in this case, it will gather some information that can be presented to a human for a decision”. Next to each tab is the number of rules that will be shown if the option is chosen. The default option shown is the violations tab.

Within the tabs, an accordion-like design is used to display each of the rules that have met the criteria. Upon clicking one of these accordion bars, information is displayed about that rule along with a link that contains in-depth information on the rule.

If you are interested in more fine-grained details about the results of the component being tested, a list of flagged elements, shown by selector path, are displayed under the rule information. In addition, a severity tag is attached to each element descriptor to indicate the urgency of a fix to be put in place.

With Storybook 5.1, a checkbox is located to the right side of each rule that enables you to highlight flagged DOM elements in the Storybook canvas.

Three different colors are used when highlighting these elements; green for passes, red for violations, and yellow for incompletions. However, only one type of rule is highlighted at a time.

Once you’ve pinpointed accessibility violations and incompletions, you can modify your code and use hot reloading. This initiates another a11y test run.

If you don’t want to leave the browser, change the DOM/CSS in your browser inspector and click the built-in “Re-run tests” button to view resultant changes.

That’s not all. A11y features a color blindness emulator for visual testing. The emulation is based on a filter that is applied to the component’s styles after a type of color vision deficiency is chosen from the drop down. Common deficiencies are provided including protanopia, protanomaly, deuteranopia, deuteranomaly, tritanopia, tritanomaly, achromatopsia, achromatomaly, and mono. This helps your team relate to user’s with disabilities in ways that wouldn’t have been possible before.

Use the a11y addon

No matter where your team is in the development process, it’s never too late to start thinking about accessibility. Storybook gives you a great way to manage, visualize, and measure a component’s adherence to common standards all while minimizing feedback loops with real-time validation.

👉 Read the install instructions here

Get involved

Storybook is maintained by incredible open source contributors and guided by a steering committee of top maintainers.

The A11y addon supports basic HTML and JavaScript, as well as the following frameworks: React, Vue, Angular, Polymer, Mithril, Marko, Riot, Svelte, Ember, and Preact. If you are interested in contributing, check out the Storybook on Github and create an issue or submit a pull request. Join us in the Storybook’s Discord chat.

Sign up to the mailing list to get Storybook updates in your inbox.


The UI development environment you'll ♥️ to use.