0
# Storybook Accessibility Addon
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-a11y
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npx storybook add @storybook/addon-a11y`
10

11
## Core Imports
12

13
```typescript
14
import { PARAM_KEY, A11yTypes } from "@storybook/addon-a11y";
15
```
16

17
For complete addon functionality (includes preview configuration):
18

19
```typescript
20
import addon, { 
21
  PARAM_KEY, 
22
  A11yTypes, 
23
  A11yParameters,
24
  run,
25
  getTitleForAxeResult,
26
  getFriendlySummaryForAxeResult,
27
  getIsVitestStandaloneRun,
28
  getIsVitestRunning
29
} from "@storybook/addon-a11y";
30
```
31

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

34
```typescript
35
import { afterEach, initialGlobals, parameters } from "@storybook/addon-a11y/preview";
36
```
37

38
For manager registration:
39

40
```typescript
41
import "@storybook/addon-a11y/manager";
42
```
43

44
For CLI postinstall (used internally by Storybook CLI):
45

46
```typescript
47
import postinstall from "@storybook/addon-a11y/postinstall";
48
```
49

50
## Basic Usage
51

52
### Installation and Configuration
53

54
```typescript
55
// .storybook/main.ts
56
export default {
57
  addons: ["@storybook/addon-a11y"],
58
};
59
```
60

61
### Story Configuration
62

63
```typescript
64
// stories/Button.stories.ts
65
import type { Meta, StoryObj } from '@storybook/react';
66
import { Button } from './Button';
67

68
const meta: Meta<typeof Button> = {
69
  component: Button,
70
  parameters: {
71
    a11y: {
72
      // Configure accessibility testing options
73
      options: {
74
        rules: {
75
          'color-contrast': { enabled: true }
76
        }
77
      },
78
      // Disable accessibility testing for this story
79
      disable: false,
80
      // Set test mode: 'off' | 'todo' | 'error'
81
      test: 'error'
82
    },
83
  },
84
};
85

86
export default meta;
87
type Story = StoryObj<typeof meta>;
88

89
export const Primary: Story = {
90
  parameters: {
91
    a11y: {
92
      context: {
93
        // Include specific elements for testing
94
        include: ['.primary-button'],
95
        // Exclude elements from testing
96
        exclude: ['.decorative-only']
97
      }
98
    }
99
  }
100
};
101
```
102

103
## Architecture
104

105
The Storybook Accessibility Addon is built around several key components:
106

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

114
## Capabilities
115

116
### Configuration and Parameters
117

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

120
```typescript { .api }
121
interface A11yParameters {
122
  context?: ContextSpecWithoutNode;
123
  options?: RunOptions;
124
  config?: Spec;
125
  disable?: boolean;
126
  test?: 'off' | 'todo' | 'error';
127
}
128

129
interface A11yGlobals {
130
  a11y?: {
131
    manual?: boolean;
132
  };
133
}
134
```
135

136
[Configuration and Parameters](./configuration.md)
137

138
### Testing and Validation
139

140
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.
141

142
```typescript { .api }
143
const afterEach: AfterEach<any> = async ({
144
  id: storyId,
145
  reporting,
146
  parameters,
147
  globals,
148
  viewMode,
149
}) => Promise<void>;
150

151
interface EnhancedResults extends Omit<AxeResults, 'incomplete' | 'passes' | 'violations'> {
152
  incomplete: EnhancedResult[];
153
  passes: EnhancedResult[];
154
  violations: EnhancedResult[];
155
}
156
```
157

158
[Testing and Validation](./testing.md)
159

160
### User Interface Components
161

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

164
```typescript { .api }
165
// These components are automatically registered when importing the manager
166
import "@storybook/addon-a11y/manager";
167

168
// Internal components (not directly importable):
169
// - A11YPanel: Main accessibility panel component  
170
// - A11yContextProvider: Context provider for accessibility state
171
// - VisionSimulator: Vision impairment simulation tool
172
```
173

174
[User Interface Components](./ui-components.md)
175

176
### Rule Mapping and Descriptions
177

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

180
```typescript { .api }
181
type AxeRuleMap = {
182
  [axeId: string]: {
183
    title: string;
184
    axeSummary: string;
185
    friendlySummary: string;
186
  };
187
};
188

189
const combinedRulesMap: AxeRuleMap;
190
```
191

192
[Rule Mapping and Descriptions](./rule-mapping.md)
193

194
## Types
195

196
### Core Types
197

198
```typescript { .api }
199
interface A11yTypes {
200
  parameters: A11yParameters;
201
  globals: A11yGlobals;
202
}
203

204
type A11YReport = EnhancedResults | { error: Error };
205

206
const RuleType = {
207
  VIOLATION: 'violations',
208
  PASS: 'passes',
209
  INCOMPLETION: 'incomplete',
210
} as const;
211

212
type RuleType = (typeof RuleType)[keyof typeof RuleType];
213
```
214

215
### Enhanced Result Types
216

217
```typescript { .api }
218
interface EnhancedNodeResult extends NodeResult {
219
  linkPath: string;
220
}
221

222
interface EnhancedResult extends Omit<Result, 'nodes'> {
223
  nodes: EnhancedNodeResult[];
224
}
225
```
226

227
### Context and Selector Types
228

229
```typescript { .api }
230
type SelectorWithoutNode = Omit<Selector, 'Node'> | Omit<SelectorList, 'NodeList'>;
231

232
type ContextObjectWithoutNode =
233
  | {
234
      include: SelectorWithoutNode;
235
      exclude?: SelectorWithoutNode;
236
    }
237
  | {
238
      exclude: SelectorWithoutNode;
239
      include?: SelectorWithoutNode;
240
    };
241

242
type ContextSpecWithoutNode = SelectorWithoutNode | ContextObjectWithoutNode;
243
```
244

245
## Utility Functions
246

247
```typescript { .api }
248
// Test runner function for executing accessibility tests
249
function run(input?: A11yParameters, storyId: string): Promise<EnhancedResults>;
250

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

255
// Environment detection utilities
256
function getIsVitestStandaloneRun(): boolean;
257
function getIsVitestRunning(): boolean;
258
```
259

260
## Constants
261

262
```typescript { .api }
263
// Exported constant
264
const PARAM_KEY = 'a11y';
265

266
// Internal constants (not exported):
267
// const ADDON_ID = 'storybook/a11y';
268
// const PANEL_ID = 'storybook/a11y/panel'; 
269
// const DOCUMENTATION_LINK = 'writing-tests/accessibility-testing';
270
// const TEST_PROVIDER_ID = 'storybook/addon-a11y/test-provider';
271
```
272

273
## Postinstall Function
274

275
```typescript { .api }
276
// CLI postinstall automation function
277
function postinstall(options: PostinstallOptions): Promise<void>;
278

279
interface PostinstallOptions {
280
  yes?: boolean;
281
  packageManager?: string;
282
  configDir?: string;
283
}
284
```