@storybook/addon-a11y

What is @storybook/addon-a11y?

The @storybook/addon-a11y package is an addon for Storybook that helps you improve the accessibility of your UI components. It integrates with Storybook to provide automated checks and manual testing tools for accessibility issues, allowing developers to ensure their components are accessible to as many users as possible.

What are @storybook/addon-a11y's main functionalities?

Automated accessibility checks

Automatically run accessibility checks on your components within the Storybook UI. It uses the axe-core library to test each component for accessibility issues and provides a report.

import { withA11y } from '@storybook/addon-a11y';

export default {
  title: 'Button',
  decorators: [withA11y],
};

export const AccessibleButton = () => <button>Click me</button>;
export const InAccessibleButton = () => <button style={{ color: 'white', backgroundColor: 'white' }}>Can't see me</button>;

Manual accessibility testing tools

Provides tools for manual accessibility testing, such as color contrast checkers and keyboard event simulation, to complement the automated checks.

N/A

Customizable rules

Allows customization of the accessibility rules used for testing, enabling or disabling specific rules to tailor the checks to your project's needs.

import { withA11y } from '@storybook/addon-a11y';

export default {
  title: 'Button',
  decorators: [withA11y],
  parameters: {
    a11y: {
      config: {
        rules: [{ id: 'color-contrast', enabled: false }]
      }
    }
  }
};

Other packages similar to @storybook/addon-a11y

axe-core

A core library for accessibility testing used by many tools and services, including @storybook/addon-a11y. It can be integrated directly into testing workflows or used as part of other tools.

eslint-plugin-jsx-a11y

An ESLint plugin that enforces accessibility rules in JSX elements. Unlike @storybook/addon-a11y, which is used within Storybook, this plugin integrates with the ESLint static code analysis tool to catch accessibility issues during code linting.

react-axe

A library that can be used in React applications to audit accessibility in real-time during development. It also uses axe-core under the hood but is used directly in the app rather than in Storybook.

pa11y

An automated accessibility testing tool that runs in the command line or as part of your build process. It provides a different approach to accessibility testing compared to the Storybook addon, as it can be used for testing entire pages and is not specific to a component development environment.

README

storybook-addon-a11y

This storybook addon can be helpfull to make your UI components more accessibile.

Getting started

First, install the addon.

$ npm install -D @storybook/addon-a11y

Add this line to your addons.js file (create this file inside your storybook config directory if needed).

import '@storybook/addon-a11y/register';

import the 'checkA11y' decorator to check your stories for violations within your components.

import React from 'react';
import { storiesOf } from '@storybook/react';

import { checkA11y } from '@storybook/addon-a11y';

storiesOf('button', module)
  .addDecorator(checkA11y)
  .add('Accessible', () => (
    <button>
      Accessible button
    </button>
  ))
  .add('Inaccessible', () => (
    <button style={{ backgroundColor: 'red', color: 'darkRed', }}>
      Inaccessible button
    </button>
  ));

Roadmap

• Make UI accessibile
• Add color blindness filters (Example)
• Show in story where violations are.
• Make it configurable
• Add more example tests
• Add tests
• Make CI integration possible