0
# Configuration and Parameters
1

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

4
## Capabilities
5

6
### A11y Parameters
7

8
Main configuration interface for accessibility testing parameters.
9

10
```typescript { .api }
11
interface A11yParameters {
12
  /**
13
   * Context parameter for axe-core's run function, except without support for passing Nodes and
14
   * NodeLists directly.
15
   *
16
   * @see https://github.com/dequelabs/axe-core/blob/develop/doc/context.md
17
   */
18
  context?: ContextSpecWithoutNode;
19
  /**
20
   * Options for running axe-core.
21
   *
22
   * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
23
   */
24
  options?: RunOptions;
25
  /**
26
   * Configuration object for axe-core.
27
   *
28
   * @see https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
29
   */
30
  config?: Spec;
31
  /** Whether to disable accessibility tests. */
32
  disable?: boolean;
33
  /** Defines how accessibility violations should be handled: 'off', 'todo', or 'error'. */
34
  test?: A11yTest;
35
}
36

37
type A11yTest = 'off' | 'todo' | 'error';
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
// Basic story configuration
44
export const BasicButton: Story = {
45
  parameters: {
46
    a11y: {
47
      // Disable testing for this story
48
      disable: true
49
    }
50
  }
51
};
52

53
// Configure test mode
54
export const ButtonWithTodoTests: Story = {
55
  parameters: {
56
    a11y: {
57
      // Show violations as warnings instead of errors
58
      test: 'todo'
59
    }
60
  }
61
};
62

63
// Configure axe-core options
64
export const ButtonWithCustomRules: Story = {
65
  parameters: {
66
    a11y: {
67
      options: {
68
        rules: {
69
          'color-contrast': { enabled: true },
70
          'button-name': { enabled: true },
71
          'aria-allowed-attr': { enabled: false }
72
        }
73
      }
74
    }
75
  }
76
};
77
```
78

79
### A11y Globals
80

81
Global configuration for the accessibility addon affecting all stories.
82

83
```typescript { .api }
84
interface A11yGlobals {
85
  /**
86
   * Accessibility configuration
87
   *
88
   * @see https://storybook.js.org/docs/writing-tests/accessibility-testing
89
   */
90
  a11y?: {
91
    /**
92
     * Prevent the addon from executing automated accessibility checks upon visiting a story. You
93
     * can still trigger the checks from the addon panel.
94
     *
95
     * @see https://storybook.js.org/docs/writing-tests/accessibility-testing#turn-off-automated-a11y-tests
96
     */
97
    manual?: boolean;
98
  };
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
// .storybook/preview.ts
106
export const globals = {
107
  a11y: {
108
    // Disable automatic testing, require manual trigger
109
    manual: true
110
  }
111
};
112
```
113

114
### Context Configuration
115

116
Specify which elements to include or exclude from accessibility testing.
117

118
```typescript { .api }
119
type SelectorWithoutNode = Omit<Selector, 'Node'> | Omit<SelectorList, 'NodeList'>;
120

121
type ContextObjectWithoutNode =
122
  | {
123
      include: SelectorWithoutNode;
124
      exclude?: SelectorWithoutNode;
125
    }
126
  | {
127
      exclude: SelectorWithoutNode;
128
      include?: SelectorWithoutNode;
129
    };
130

131
type ContextSpecWithoutNode = SelectorWithoutNode | ContextObjectWithoutNode;
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
// Include only specific elements
138
export const FormStory: Story = {
139
  parameters: {
140
    a11y: {
141
      context: {
142
        include: ['.form-container', '#main-form']
143
      }
144
    }
145
  }
146
};
147

148
// Exclude decorative elements
149
export const LayoutStory: Story = {
150
  parameters: {
151
    a11y: {
152
      context: {
153
        exclude: ['.decorative-bg', '.visual-flourish']
154
      }
155
    }
156
  }
157
};
158

159
// Complex context configuration
160
export const ComponentStory: Story = {
161
  parameters: {
162
    a11y: {
163
      context: {
164
        include: ['.component-root'],
165
        exclude: ['.component-root .debug-panel']
166
      }
167
    }
168
  }
169
};
170
```
171

172
### Preview Configuration
173

174
Default configurations applied at the preview level.
175

176
```typescript { .api }
177
const initialGlobals = {
178
  a11y: {
179
    manual: false,
180
  },
181
};
182

183
const parameters = {
184
  a11y: {
185
    test: 'todo',
186
  } as A11yParameters,
187
};
188
```
189

190
**Usage:**
191

192
```typescript
193
// .storybook/preview.ts
194
// Option 1: Import from preview entry point
195
import { initialGlobals, parameters } from '@storybook/addon-a11y/preview';
196

197
// Option 2: Import from main entry point (re-exported)
198
import { initialGlobals, parameters } from '@storybook/addon-a11y';
199

200
export { initialGlobals, parameters };
201

202
// Or customize defaults
203
export const globals = {
204
  ...initialGlobals,
205
  a11y: {
206
    manual: true // Override default
207
  }
208
};
209

210
export const parameters = {
211
  ...parameters,
212
  a11y: {
213
    test: 'error', // Override default test mode
214
    options: {
215
      // Add global axe-core options
216
      rules: {
217
        'region': { enabled: false } // Disable region rule globally
218
      }
219
    }
220
  }
221
};
222
```
223

224
### Constants
225

226
Key constants used for configuration and identification.
227

228
```typescript { .api }
229
const PARAM_KEY = 'a11y';
230
const ADDON_ID = 'storybook/a11y';
231
const PANEL_ID = 'storybook/a11y/panel';
232
const TEST_PROVIDER_ID = 'storybook/addon-a11y/test-provider';
233
```
234

235
### Event Constants
236

237
```typescript { .api }
238
// Event constants for internal communication (not exported)
239
// const EVENTS = {
240
//   RESULT: 'storybook/a11y/result',
241
//   REQUEST: 'storybook/a11y/request', 
242
//   RUNNING: 'storybook/a11y/running',
243
//   ERROR: 'storybook/a11y/error',
244
//   MANUAL: 'storybook/a11y/manual',
245
//   SELECT: 'storybook/a11y/select'
246
// };
247
```
248

249
### Documentation Links
250

251
```typescript { .api }
252
// Internal documentation constants (not exported)
253
const DOCUMENTATION_LINK = 'writing-tests/accessibility-testing';
254
const DOCUMENTATION_DISCREPANCY_LINK = 'writing-tests/accessibility-testing#why-are-my-tests-failing-in-different-environments';
255
```
256

257
## Test Modes
258

259
The addon supports three test modes that determine how accessibility violations are handled:
260

261
- **`'off'`**: Disables accessibility testing completely
262
- **`'todo'`**: Reports violations as warnings (non-blocking)  
263
- **`'error'`**: Reports violations as errors (blocking in test environments)
264

265
## Default Behavior
266

267
By default, the addon:
268
- Runs automatically when stories are rendered (`manual: false`)
269
- Reports violations as todos/warnings (`test: 'todo'`)
270
- Tests all elements in the story canvas
271
- Disables the 'region' rule to avoid false positives in component testing