0
# Rule Mapping and Descriptions
1
2
Comprehensive mapping system that converts axe-core rule violations into user-friendly descriptions and remediation guidance.
3
4
## Capabilities
5
6
### Rule Title Mapping
7
8
Exported utility that converts axe-core rule IDs into user-friendly titles.
9
10
```typescript { .api }
11
/**
12
* Gets user-friendly title for an axe accessibility test result
13
* @param axeResult - Enhanced result from accessibility testing
14
* @returns Human-readable title for the rule or rule ID if no mapping exists
15
*/
16
function getTitleForAxeResult(axeResult: EnhancedResult): string;
17
```
18
19
This function provides user-friendly rule titles for accessibility violations and can be imported and used directly:
20
21
```typescript
22
import { getTitleForAxeResult } from '@storybook/addon-a11y';
23
24
// Get a friendly title for a violation
25
const title = getTitleForAxeResult(violationResult);
26
console.log(title); // "Color contrast" instead of "color-contrast"
27
```
28
29
### Rule Summary Mapping
30
31
Exported utility that provides user-friendly summaries and remediation guidance.
32
33
```typescript { .api }
34
/**
35
* Gets user-friendly summary for an axe accessibility test result
36
* @param axeResult - Enhanced result from accessibility testing
37
* @returns Friendly remediation summary or description fallback
38
*/
39
function getFriendlySummaryForAxeResult(
40
axeResult: EnhancedResult
41
): string | undefined;
42
```
43
44
This function provides user-friendly remediation guidance and can be imported and used directly:
45
46
```typescript
47
import { getFriendlySummaryForAxeResult } from '@storybook/addon-a11y';
48
49
// Get friendly remediation guidance for a violation
50
const guidance = getFriendlySummaryForAxeResult(violationResult);
51
console.log(guidance); // "The color contrast between text and its background meets WCAG AA contrast ratio."
52
```
53
54
### Rule Map Structure
55
56
Complete mapping of axe-core rules to user-friendly descriptions.
57
58
```typescript { .api }
59
type AxeRuleMap = {
60
[axeId: string]: {
61
/** The simple name of the rule */
62
title: string;
63
/** The summary of the rule from axe-core */
64
axeSummary: string;
65
/** The UX-friendly summary of the rule */
66
friendlySummary: string;
67
};
68
};
69
70
const combinedRulesMap: AxeRuleMap;
71
```
72
73
The rule map includes comprehensive coverage for:
74
- **WCAG 2.0 A/AA Success Criteria**
75
- **WCAG 2.1 A/AA Success Criteria**
76
- **WCAG 2.2 A/AA Success Criteria**
77
- **WCAG AAA Success Criteria**
78
- **Best Practice Rules**
79
- **Experimental Rules**
80
- **Deprecated Rules**
81
82
## Rule Categories
83
84
### WCAG 2.0 A/AA Rules
85
86
Essential accessibility rules aligned with WCAG 2.0 Level A and AA success criteria.
87
88
**Example Rules:**
89
90
```typescript { .api }
91
// Color contrast requirements
92
'color-contrast': {
93
title: 'Color contrast',
94
axeSummary: 'Ensure the contrast between foreground and background text meets WCAG 2 AA minimum thresholds',
95
friendlySummary: 'The color contrast between text and its background meets WCAG AA contrast ratio.'
96
}
97
98
// Button accessibility
99
'button-name': {
100
title: 'Button name',
101
axeSummary: 'Ensure buttons have discernible text',
102
friendlySummary: 'Every <button> needs a visible label or accessible name.'
103
}
104
105
// Image alt text
106
'image-alt': {
107
title: 'Image alt text',
108
axeSummary: 'Ensure <img> elements have alternative text or a role of none/presentation',
109
friendlySummary: 'Give every image alt text or mark it as decorative with alt="".'
110
}
111
```
112
113
### WCAG 2.1 A/AA Rules
114
115
Additional rules introduced in WCAG 2.1 for enhanced accessibility.
116
117
**Example Rules:**
118
119
```typescript { .api }
120
// Autocomplete attributes
121
'autocomplete-valid': {
122
title: 'autocomplete attribute valid',
123
axeSummary: 'Ensure the autocomplete attribute is correct and suitable for the form field',
124
friendlySummary: "Use valid autocomplete values that match the form field's purpose."
125
}
126
127
// Text spacing
128
'avoid-inline-spacing': {
129
title: 'Forced inline spacing',
130
axeSummary: 'Ensure that text spacing set via inline styles can be adjusted with custom CSS',
131
friendlySummary: "Don't lock in text spacing with forced (!important) inline styles—allow user CSS to adjust text spacing."
132
}
133
```
134
135
### WCAG 2.2 A/AA Rules
136
137
Latest accessibility requirements from WCAG 2.2.
138
139
**Example Rules:**
140
141
```typescript { .api }
142
// Touch target sizing
143
'target-size': {
144
title: 'Touch target size',
145
axeSummary: 'Ensure touch targets have sufficient size and space',
146
friendlySummary: 'Make sure interactive elements are big enough and not too close together for touch.'
147
}
148
```
149
150
### Best Practice Rules
151
152
Industry best practices beyond WCAG requirements.
153
154
**Example Rules:**
155
156
```typescript { .api }
157
// Heading order
158
'heading-order': {
159
title: 'Heading order',
160
axeSummary: 'Ensure the order of headings is semantically correct (no skipping levels)',
161
friendlySummary: "Use proper heading order (don't skip heading levels)."
162
}
163
164
// Landmark structure
165
'region': {
166
title: 'Landmark regions',
167
axeSummary: 'Ensure all page content is contained by landmarks',
168
friendlySummary: 'Wrap all page content in appropriate landmark regions (<header>, <main>, <footer>, etc.).'
169
}
170
171
// Skip links
172
'skip-link': {
173
title: 'Skip link',
174
axeSummary: 'Ensure all "skip" links have a focusable target',
175
friendlySummary: 'Make sure any "skip to content" link targets an existing, focusable element.'
176
}
177
```
178
179
### ARIA Rules
180
181
Comprehensive ARIA (Accessible Rich Internet Applications) rules.
182
183
**Example Rules:**
184
185
```typescript { .api }
186
// ARIA roles
187
'aria-roles': {
188
title: 'ARIA role value',
189
axeSummary: 'Ensure all elements with a role attribute use a valid value',
190
friendlySummary: 'Use only valid values in the role attribute (no typos or invalid roles).'
191
}
192
193
// ARIA attributes
194
'aria-valid-attr': {
195
title: 'ARIA attribute valid',
196
axeSummary: 'Ensure attributes that begin with aria- are valid ARIA attributes',
197
friendlySummary: 'Use only valid aria-* attributes (make sure the attribute name is correct).'
198
}
199
200
// ARIA required attributes
201
'aria-required-attr': {
202
title: 'ARIA required attributes',
203
axeSummary: 'Ensure elements with ARIA roles have all required ARIA attributes',
204
friendlySummary: 'Include all required ARIA attributes for elements with that ARIA role.'
205
}
206
```
207
208
## Usage in Components
209
210
The rule mapping system is integrated throughout the addon's UI components:
211
212
### Panel Display
213
214
```typescript
215
// Used in A11YPanel to show friendly titles
216
const violationTitle = getTitleForAxeResult(violation);
217
const violationSummary = getFriendlySummaryForAxeResult(violation);
218
```
219
220
### Report Generation
221
222
```typescript
223
// Used in Report component for detailed violation information
224
violations.forEach(violation => {
225
const title = getTitleForAxeResult(violation);
226
const guidance = getFriendlySummaryForAxeResult(violation);
227
228
// Display title and guidance in the UI
229
renderViolation({ title, guidance, ...violation });
230
});
231
```
232
233
### Tooltip Information
234
235
```typescript
236
// Used for contextual help and tooltips
237
const helpText = getFriendlySummaryForAxeResult(result);
238
showTooltip(helpText);
239
```
240
241
## Fallback Behavior
242
243
When no mapping exists for a rule:
244
- **Title**: Falls back to the original axe rule ID
245
- **Summary**: Falls back to the axe-core description field
246
- **Graceful Degradation**: Always provides some description even for unknown rules
247
248
## Rule Categories Overview
249
250
The complete rule mapping covers:
251
252
- **200+ WCAG Rules**: Comprehensive coverage of WCAG 2.0, 2.1, and 2.2
253
- **50+ Best Practice Rules**: Industry standards beyond WCAG requirements
254
- **30+ ARIA Rules**: Complete ARIA implementation guidance
255
- **Experimental Rules**: Cutting-edge accessibility requirements
256
- **Legacy Support**: Deprecated rules for backward compatibility
257
258
## Customization
259
260
While the rule mapping is comprehensive, organizations can extend it by:
261
262
1. Contributing additional rules to the `combinedRulesMap`
263
2. Overriding specific rule descriptions for organizational standards
264
3. Adding custom rule categories for specialized accessibility requirements
265
266
The mapping system ensures that all accessibility violations are presented in user-friendly language with actionable remediation guidance.