tessl/npm-storybook--addon-a11y

Storybook addon that provides comprehensive accessibility testing for UI components using axe-core engine to ensure WCAG compliance

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Storybook Accessibility Addon

Name: tessl/npm-storybook--addon-a11y
Author: tessl

Storybook Accessibility Addon provides comprehensive accessibility testing for UI components using the axe-core engine. It enables developers to automatically test their Storybook stories for WCAG compliance and web accessibility standards, offering real-time accessibility analysis with visual feedback, violation detection, color vision simulation, and detailed reporting.

Package Information

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

Core Imports

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

For complete addon functionality (includes preview configuration):

import addon, { 
  PARAM_KEY, 
  A11yTypes, 
  A11yParameters,
  run,
  getTitleForAxeResult,
  getFriendlySummaryForAxeResult,
  getIsVitestStandaloneRun,
  getIsVitestRunning
} from "@storybook/addon-a11y";

For preview configuration (re-exported from main entry):

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

For manager registration:

import "@storybook/addon-a11y/manager";

For CLI postinstall (used internally by Storybook CLI):

import postinstall from "@storybook/addon-a11y/postinstall";

Basic Usage

Installation and Configuration

// .storybook/main.ts
export default {
  addons: ["@storybook/addon-a11y"],
};

Story Configuration

// stories/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    a11y: {
      // Configure accessibility testing options
      options: {
        rules: {
          'color-contrast': { enabled: true }
        }
      },
      // Disable accessibility testing for this story
      disable: false,
      // Set test mode: 'off' | 'todo' | 'error'
      test: 'error'
    },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  parameters: {
    a11y: {
      context: {
        // Include specific elements for testing
        include: ['.primary-button'],
        // Exclude elements from testing
        exclude: ['.decorative-only']
      }
    }
  }
};

Architecture

The Storybook Accessibility Addon is built around several key components:

Core Testing Engine: Uses axe-core for comprehensive WCAG compliance testing
Storybook Integration: Seamlessly integrates with Storybook's preview and manager APIs
Visual Components: Provides accessibility panel, vision simulator, and detailed reporting UI
Test Automation: Automatically runs accessibility tests during story rendering
Configuration System: Flexible parameter system for customizing test behavior
Rule Mapping: User-friendly descriptions and explanations for accessibility violations

Capabilities

Configuration and Parameters

Core configuration options for customizing accessibility testing behavior, including axe-core options, context specification, and test modes.

interface A11yParameters {
  context?: ContextSpecWithoutNode;
  options?: RunOptions;
  config?: Spec;
  disable?: boolean;
  test?: 'off' | 'todo' | 'error';
}

interface A11yGlobals {
  a11y?: {
    manual?: boolean;
  };
}

Configuration and Parameters

Testing and Validation

Automated accessibility testing capabilities that run axe-core tests on stories through the afterEach hook, with support for different execution modes and detailed result reporting.

const afterEach: AfterEach<any> = async ({
  id: storyId,
  reporting,
  parameters,
  globals,
  viewMode,
}) => Promise<void>;

interface EnhancedResults extends Omit<AxeResults, 'incomplete' | 'passes' | 'violations'> {
  incomplete: EnhancedResult[];
  passes: EnhancedResult[];
  violations: EnhancedResult[];
}

Testing and Validation

User Interface Components

Internal React components that provide the accessibility testing interface within Storybook, automatically registered when importing the manager.

// These components are automatically registered when importing the manager
import "@storybook/addon-a11y/manager";

// Internal components (not directly importable):
// - A11YPanel: Main accessibility panel component  
// - A11yContextProvider: Context provider for accessibility state
// - VisionSimulator: Vision impairment simulation tool

User Interface Components

Rule Mapping and Descriptions

Comprehensive internal mapping system that converts axe-core rule violations into user-friendly descriptions and remediation guidance displayed in the UI.

type AxeRuleMap = {
  [axeId: string]: {
    title: string;
    axeSummary: string;
    friendlySummary: string;
  };
};

const combinedRulesMap: AxeRuleMap;

Rule Mapping and Descriptions

Types

Core Types

interface A11yTypes {
  parameters: A11yParameters;
  globals: A11yGlobals;
}

type A11YReport = EnhancedResults | { error: Error };

const RuleType = {
  VIOLATION: 'violations',
  PASS: 'passes',
  INCOMPLETION: 'incomplete',
} as const;

type RuleType = (typeof RuleType)[keyof typeof RuleType];

Enhanced Result Types

interface EnhancedNodeResult extends NodeResult {
  linkPath: string;
}

interface EnhancedResult extends Omit<Result, 'nodes'> {
  nodes: EnhancedNodeResult[];
}

Context and Selector Types

type SelectorWithoutNode = Omit<Selector, 'Node'> | Omit<SelectorList, 'NodeList'>;

type ContextObjectWithoutNode =
  | {
      include: SelectorWithoutNode;
      exclude?: SelectorWithoutNode;
    }
  | {
      exclude: SelectorWithoutNode;
      include?: SelectorWithoutNode;
    };

type ContextSpecWithoutNode = SelectorWithoutNode | ContextObjectWithoutNode;

Utility Functions

// Test runner function for executing accessibility tests
function run(input?: A11yParameters, storyId: string): Promise<EnhancedResults>;

// Rule mapping helpers for user-friendly descriptions
function getTitleForAxeResult(axeResult: EnhancedResult): string;
function getFriendlySummaryForAxeResult(axeResult: EnhancedResult): string | undefined;

// Environment detection utilities
function getIsVitestStandaloneRun(): boolean;
function getIsVitestRunning(): boolean;

Constants

// Exported constant
const PARAM_KEY = 'a11y';

// Internal constants (not exported):
// const ADDON_ID = 'storybook/a11y';
// const PANEL_ID = 'storybook/a11y/panel'; 
// const DOCUMENTATION_LINK = 'writing-tests/accessibility-testing';
// const TEST_PROVIDER_ID = 'storybook/addon-a11y/test-provider';

Postinstall Function

// CLI postinstall automation function
function postinstall(options: PostinstallOptions): Promise<void>;

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