Storybook: Accessibility

5 min readJul 29, 2020

Storybook

Storybook is an open-source tool for developing, documenting, testing UI(user interface) components in isolation without worrying about app-specific dependencies and requirements. It is a collection of stories. Each story represents a single visual state of a component. Technically, a story is a function that returns something that can be rendered to screen.

Storybook provides plugins called addons to add advanced functionalities and workflows. These addons make storybook a powerful tool by letting storybook creator pick and choose the functionalities/addons based on the project requirements. You can even create your own custom addons!! One such addon for making UI components more accessible is storybook-addon-a11y

Note: I will be using a11y in short for accessibility. 11 is the number of characters between the letters a and y

Before getting into details on a11y addon, let’s understand a11y.

Accessibility

Accessibility is the practice of making websites usable by anyone. Anyone includes people with disabilities such as visual, hearing, mobility, and cognitive impairments. People with disabilities use assistive technology (a generic term used for describing the tools or software used to navigate, interact and understand the content and features of a website) such as screen readers, screen magnification software, text readers, speech input software, alternative input devices (head pointers, motion tracking or eye-tracking, single switch entry devices) to name a few.

Its the responsibility of each and every person involved in creating a website to make it accessible.

Storybook-addon-a11y

Storybook-addon-a11y is an addon offered by the storybook to validate accessibility requirements. It is created by the storybook core team and enhanced/improved by the open-source developer community.

A11y addon runs on top of axe a11y engine (developed by Deque Labs) which is also used by google lighthouse.
We can selectively disable a11y checks for a subset of stories e.g. say you want to check a11y on the button and checkbox components but not on logos and illustrations as they are CDN links and storybook is used only for documentation purpose, then you can disable the a11y check on logos and illustrations.
We can customize the axe configuration, and override these options at the story level.

Steps to add a11y addon

Add storybook

There are 2 ways to add a storybook to your application

Get a basic configuration setup based on the type of your project. e.g. If your app is a react application, then the storybook automatically detects the type of project and installs all the dependencies required. Below is the command for this setup

Open the terminal

cd your-application
npx -p @storybook/cli sb init

If storybook is not able to detect the type of the project then you will see a message

Detecting project type. ✓    We couldn't detect your project type. (code: UNDETECTED)    You can specify a project type explicitly via `sb init --type <type>` or follow some of the slow start guides: https://storybook.js.org/basics/slow-start-guide/
? Do you want to manually choose a Storybook project type to install?

By selecting yes, you will get the following options. Select one of the options based on your project type. This is the list of the supported frameworks, if you don’t find your project type then raise an issue with storybook

PREACT 
SVELTE 
RAX 
REACT_SCRIPTS 
METEOR 
REACT 
REACT_NATIVE
REACT_PROJECT 
WEBPACK_REACT 
VUE 
SFC_VUE  
POLYMER 
WEB_COMPONENTS 
MITHRIL 
MARKO
HTML 
RIOT 
ANGULAR 
EMBER

2. Manual Setup

Based on the type of project you can manually run the commands in your terminal. Follow this documentation.

Add A11y Addon

Once you have storybook installed and setup, add the a11y addon to the `main.js` file. This is the same file you had created while setting up storybook.

module.exports = {
  addons: ['@storybook/addon-a11y/register'],
};

Add a11y as a decorator e.g.

import { withA11y } from '@storybook/addon-a11y';
export default { 
    title: 'Button',
    decorators: [withA11y],
};

Now run storybook and you will see 3 features as highlighted in the image below.

A11y Addon Features

Color Blindness Emulator

This feature is used for visual testing. Enables one to see through the eyes of color blindness people to make necessary changes for UI components to create an inclusive user experience.

When you click on the emulator you will be presented with a list of color blindness types along with normal vision type.

protanopia — unable to perceive ‘red’ color
protanomaly — red-green color blindness in which the red cones do not detect enough red and are too sensitive to greens, yellows, and oranges. As a result, greens, yellows, oranges, reds, and browns may appear similar, especially in low light
deuteranopia — unable to perceive ‘green’ color
deuteranomaly — red-green color blindness in which the green cones in the eye detect too much red light and not enough green light. As a result red, yellow, green, and brown can appear similar, especially in low light
tritanopia — unable to perceive ‘blue’ color
tritanomaly — blue-yellow color blindness. Blue is seen as more green and causes yellow, red, and pink to all look like pink.
achromatopsia — partial or total absence of color vision, cannot perceive any colors; see only black, white, and shades of gray.
achromatically — normal color vision
mono — perceive everything in shades of gray

Storybook Visual Testing using Emulator

Accessibility Validation Results

Inside the validation results section, you see 3 tabs each represented with a color: red for violations, green for passes, and orange for incomplete.

Violations

This tab shows all the a11y failures for the rules set by the storybook using axe engine.
If you click on more info… link in the image below, it will take you to a web page where you can find more info on the issue and the rule. This is very helpful to fix the issue.

Passes

This tab shows all the a11y passes for the rules set by the storybook using axe engine.

Incomplete

This tab shows the rules that axe engine didn’t pass or fail. But provides info on the rule and let human to make the decision whether to add this a11y check or not.