How to test the accessibility of your components with Storybook

A decorative image with the quote “How to test the accessibility of your components with Storybook”

Storybook

You can see the code in the project repository on my GitHub profile.

To go faster and streamline the process, I’ve used create-react-app, a tool to quickly generate a new single-page application. I’ve been trying to work only with Typescript for quite some time, so I preferred to use that configuration when creating the application.

$ npx create-react-app a11y-storybook --template typescript

After having created my application, which will serve as a component library, the next step is to add Storybook to the project. For this I will use the Storybook CLI to install it with a single command.

$ npx sb init

This command will install all the necessary dependencies, add to my package.json file the necessary scripts to run storybook, create a default configuration for storybook in the hidden ./.storybook folder, and add some test components as examples. You can find those components in the ./src/stories folder. Once everything has been installed and configured, I can run Storybook.

$ npm run storybook

A new instance of your predefined browser will open and you will be able to view Storybook with the test components added during installation.

You can read more about this whole process in the official Storybook documentation.

Creating the components

  • ColorContrast.tsx A component with color contrast errors.
  • CustomRole.tsx A component with a role that does not exist.
  • HeadingOrder.tsx A component with heading element order errors.
  • NoAltImage.tsx A component with an image without alternative text.
  • NoTextButton.tsx A component with a button with no text inside.
  • TabIndex.tsx A component with a tabindex greater than zero.

Let’s see how we can test the accessibility of the components with Storybook.

Accessibility addon

$ npm install @storybook/addon-a11y --save-dev

After that I add it to the addons list in the file ./.storybook/main.js

./.storybook/main.js

module.exports = {
stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
addons: [
"@storybook/addon-links",
"@storybook/addon-essentials",
"@storybook/preset-create-react-app",
"@storybook/addon-a11y",
],
}

With these two steps we will have added the addon-a11y in our project and we will be able to see the results when we run Storybook.

$ npm run storybook

Testing accessibility in Storybook

When executing Storybook you will see that next to the Controls and Actions panel, the Accessibility panel will now appear. If you access this panel, you will see the results of the tests organized in three tabs. In the first tab, violations, a list of accessibility vulnerabilities found in the component will be displayed. Each element of that list can be expanded and show more information about the vulnerability, degree of severity, … etc, as well as a link to the documentation compiled by Deque in its Dequeuniversity so you can read more about the vulnerability, the violated rule, and how to fix it.

In the second tab, passes, you will see a list of the rules that Axe considers to have passed the tests successfully, and in the third tab, incomplete, you will see a list of what Axe defines as incomplete rules. That is to say, they have not passed the tests successfully, but they cannot say if they have really failed. In this case, Axe provides more information for you, as a developer, to decide how to react to those rules.

A screenshot of the Storybook addon “addon-a11y” showing vulnerabilities in a React component
A screenshot of the Storybook addon “addon-a11y” showing vulnerabilities in a React component

To the right of the panel you can activate a checkbox, highlight results, so Storybook highlights on the screen the elements that are violating the accessibility rules. Three different colors will be used for each of the panels: green for tests passed successfully, red for vulnerabilities, and yellow for incomplete ones.

A screenshot of the Storybook addon “addon-a11y” showing vulnerabilities in a React component, which is highlighted and dotted on the screen
A screenshot of the Storybook addon “addon-a11y” showing vulnerabilities in a React component, which is highlighted and dotted on the screen

Emulating vision deficiency in Storybook

A screenshot of the Storybook addon “addon-a11y” showing the vision deficiency emulator
A screenshot of the Storybook addon “addon-a11y” showing the vision deficiency emulator

I have added an additional component, ColorImage.tsx, which displays an image with multiple colors to test this emulator. By emulating different vision deficiencies, you will be able to better understand when to use different colors and understand that it is not advisable to rely solely on colors, for example in error states in forms.

A screenshot of the Storybook addon “addon-a11y” showing the vision deficiency emulator and the color difference between a normal image and an image seen by someone with Tritanopia
A screenshot of the Storybook addon “addon-a11y” showing the vision deficiency emulator and the color difference between a normal image and an image seen by someone with Tritanopia

Conclusion

The project and the components used in this article have been developed in React, but Storybook has support for many more frameworks like Vue, Angular, Web Components, React Native … etc. You can read more at the official Storybook website. You can see the code in the project repository on my GitHub profile.

If you want to continue learning about web accessibility, you can follow me on my twitter account, and do not hesitate to contact me or tweet me if you have any questions or doubt.

My name is Adrián Bolonio. I’m an experienced Web Team Lead, Frontend Developer, and Web Accessibility (a11y) advocate.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store