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
```