CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/npm-storybook--addon-a11y

Test component compliance with web accessibility standards

Overview
Eval results
Files

Storybook A11y Addon

@storybook/addon-a11y is a Storybook addon that provides comprehensive accessibility testing capabilities for Storybook stories. It integrates axe-core, a powerful accessibility testing engine, to automatically run accessibility audits on components and stories within the Storybook interface, enabling developers to identify and fix accessibility issues during development.

Package Information

  • Package Name: @storybook/addon-a11y
  • Package Type: npm
  • Language: TypeScript
  • Installation: npx storybook add @storybook/addon-a11y

Core Imports

Main addon functionality:

import addon, { PARAM_KEY, Setup, A11yParameters } from "@storybook/addon-a11y";

Preview functionality:

import { experimental_afterEach, initialGlobals, parameters } from "@storybook/addon-a11y/preview";

For CommonJS:

const { PARAM_KEY, Setup } = require("@storybook/addon-a11y");
const { experimental_afterEach } = require("@storybook/addon-a11y/preview");

Basic Usage

The addon provides both automated and manual accessibility testing capabilities. After installation, it automatically adds an accessibility panel to Storybook and runs tests on stories.

// Configure a story with accessibility parameters
export const ButtonStory = {
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'color-contrast', enabled: true }
        ]
      },
      options: {
        runOnly: ['wcag2a', 'wcag2aa']
      }
    }
  }
};

// Configure global accessibility settings
export const globals = {
  a11y: {
    manual: false  // Enable automatic testing
  }
};

Architecture

The addon consists of several key components:

  • Manager Component: Provides the accessibility panel UI in Storybook with test results and controls
  • Preview Integration: Automatic test execution using experimental_afterEach hook
  • Test Runner: Core accessibility testing functionality using axe-core
  • Configuration System: Flexible parameter and global configuration options
  • Vitest Integration: Support for standalone testing with vitest-axe matchers

Capabilities

Main Addon Configuration

Core addon functionality providing the main export and parameter constants for integrating accessibility testing into Storybook.

declare const addon: () => any;
export default addon;

export const PARAM_KEY: "a11y";

Main Configuration

Preview Integration

Automatic accessibility testing integration for Storybook preview with configurable test execution and reporting.

export const experimental_afterEach: AfterEach<any>;

export const initialGlobals: {
  a11y: {
    manual: boolean;
  };
};

export const parameters: {
  a11y: A11yParameters;
};

Preview Integration

Configuration Types

Type definitions for configuring accessibility testing parameters and global settings.

export interface A11yParameters {
  /**
   * Accessibility configuration
   *
   * @see https://storybook.js.org/docs/writing-tests/accessibility-testing
   */
  a11y?: {
    /** Manual configuration for specific elements */
    element?: ElementContext;

    /**
     * Configuration for the accessibility rules
     *
     * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
     */
    config?: Spec;

    /**
     * Options for the accessibility checks To learn more about the available options,
     *
     * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
     */
    options?: RunOptions;

    /** Remove the addon panel and disable the addon's behavior */
    disable?: boolean;
  };
}

export interface A11yGlobals {
  /**
   * Accessibility configuration
   *
   * @see https://storybook.js.org/docs/writing-tests/accessibility-testing
   */
  a11y: {
    /**
     * Prevent the addon from executing automated accessibility checks upon visiting a story. You
     * can still trigger the checks from the addon panel.
     *
     * @see https://storybook.js.org/docs/writing-tests/accessibility-testing#turn-off-automated-a11y-tests
     */
    manual?: boolean;
  };
}

export type A11YReport = AxeResults | { error: Error };

Post-Installation Script

Automated migration script that runs after addon installation to configure accessibility testing.

export default function postinstall(options: PostinstallOptions): Promise<void>;

interface PostinstallOptions {
  packageManager: PackageManagerName;
  configDir: string;
  yes?: boolean;
}

type PackageManagerName = 'npm' | 'yarn' | 'pnpm' | 'bun';

Usage Example:

// Typically called automatically after installation
// Can be manually invoked if needed
import postinstall from '@storybook/addon-a11y/postinstall';

await postinstall({ yes: true });

Error Handling

The addon handles accessibility testing errors gracefully:

  • Test Failures: Violations are reported in the accessibility panel with detailed information
  • Runtime Errors: Errors during test execution are caught and reported via the event system
  • Vitest Integration: In standalone Vitest runs, accessibility violations throw errors to fail tests
  • Configuration Errors: Invalid axe-core configurations are handled with appropriate error messaging

Environment Support

The addon supports multiple testing environments:

  • Storybook Interface: Full UI integration with visual results panel
  • Vitest Standalone: Integration with vitest-axe matchers for automated testing
  • Portable Stories: Support for testing stories outside of Storybook interface
  • Browser Environments: Works in all major browsers supported by Storybook
tessl i tessl/npm-storybook--addon-a11y@8.6.0
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/addon-a11y@8.6.x