Skip to content

Commit 73384cc

Browse files
SableRafSableRaf
committed
Add accessibility-review checklist
1 parent a2a1944 commit 73384cc

3 files changed

Lines changed: 507 additions & 0 deletions

File tree

‎.claude/skills/accessibility-review/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Accessibility Review Skill
2+
3+
Conducts manual accessibility reviews of UI components, pages, and applications against WCAG 2.1/2.2 Level AA standards. Provides prioritized findings focused on practical, modern web accessibility requirements.
4+
5+
## Quick Start
6+
7+
1. Open a component, page, or code file you want reviewed
8+
2. Ask: "Is this accessible?" or "Check this for accessibility issues"
9+
3. The skill reviews against WCAG standards and presents findings one at a time
10+
4. Decide to fix or ignore each issue as they're presented
11+
12+
## What It Does
13+
14+
- Reviews code, components, and pages against WCAG 2.1/2.2 Level AA
15+
- Prioritizes findings as **Critical** (blocks access) or **Warning** (creates friction)
16+
- Presents issues one at a time for focused decision-making
17+
- Provides specific code fixes with file locations
18+
- Tracks what was fixed vs. ignored with a final summary
19+
20+
## Review Process
21+
22+
The skill follows a stepped review process:
23+
24+
1. **Identifies the target** - Component, page, code file, or design
25+
2. **Conducts manual review** - Uses WCAG checklist systematically
26+
3. **Prioritizes findings** - Critical vs. Warning classifications
27+
4. **Presents issues one at a time** - You decide fix or ignore for each
28+
5. **Provides final summary** - Overview of all decisions made
29+
30+
## Issue Classification
31+
32+
### Critical Issues
33+
Blocks users from accessing core functionality:
34+
- Missing alt text on meaningful images
35+
- Non-keyboard accessible interactive elements
36+
- Insufficient color contrast (below 4.5:1 for normal text, 3:1 for large text)
37+
- Forms without proper labels
38+
- Missing focus indicators
39+
- Inaccessible modal/dialog patterns
40+
- Auto-playing media without controls
41+
42+
### Warning Issues
43+
Creates friction but doesn't fully block access:
44+
- Suboptimal heading hierarchy (skipped levels)
45+
- Missing ARIA landmarks
46+
- Link text that's unclear out of context
47+
- Redundant or unnecessary ARIA
48+
- Touch targets smaller than 44x44px
49+
- Missing skip links
50+
- Non-descriptive error messages
51+
52+
## Common Patterns Checked
53+
54+
### Interactive Elements
55+
- All interactive elements must be keyboard accessible
56+
- Focus must be visible with clear indicators
57+
- Custom controls need proper ARIA roles and states
58+
59+
### Forms
60+
- All inputs must have associated labels
61+
- Error messages must be programmatically associated
62+
- Required fields must be indicated clearly
63+
64+
### Color and Contrast
65+
- Text contrast: 4.5:1 minimum for normal text, 3:1 for large text
66+
- UI components: 3:1 contrast for interactive elements
67+
- Don't rely on color alone to convey information
68+
69+
### Images and Media
70+
- Meaningful images need descriptive alt text
71+
- Decorative images should have empty alt (alt="")
72+
- Videos need captions, audio content needs transcripts
73+
74+
### Structure
75+
- Use semantic HTML (nav, main, article, etc.)
76+
- Heading hierarchy should be logical (h1 → h2 → h3)
77+
- ARIA landmarks help screen reader navigation
78+
79+
## Files
80+
81+
| File | Purpose |
82+
|------|---------|
83+
| `SKILL.md` | Main skill instructions and review workflow |
84+
| `references/wcag-checklist.md` | Comprehensive WCAG 2.1/2.2 Level AA checklist organized by principle |
85+
86+
## Review Guidelines
87+
88+
The skill follows these principles:
89+
90+
- **Be Practical**: Focus on issues that genuinely impact users. Modern WCAG 2.1/2.2 Level AA is the standard—avoid over-engineering or citing obscure edge cases.
91+
92+
- **Be Specific**: Reference actual code locations using `file_path:line_number` format when possible.
93+
94+
- **Be Constructive**: Provide actionable fixes, not just problems. Include code examples when helpful.
95+
96+
- **Consider Context**: Some patterns may have accessibility trade-offs. Acknowledge these and suggest the most accessible approach for the use case.
97+
98+
## Example Interaction
99+
100+
**User:** "Is this button accessible?"
101+
102+
**Skill:**
103+
1. Reviews the button component against WCAG standards
104+
2. Finds issues (e.g., missing focus indicator, insufficient contrast)
105+
3. Presents first issue:
106+
```
107+
───────────────────────────────────
108+
Issue [1/2]: Critical
109+
───────────────────────────────────
110+
111+
**Problem**: Button lacks visible focus indicator
112+
113+
**Location**: `components/Button.tsx:45`
114+
[Shows code snippet]
115+
116+
**Impact**: Keyboard users can't see which element has focus
117+
118+
**Recommended Fix**: Add focus-visible styles
119+
───────────────────────────────────
120+
Fix this issue, or ignore?
121+
```
122+
4. Waits for your decision before presenting the next issue
123+
5. Provides final summary of all decisions
124+
125+
## Tips for Best Results
126+
127+
- **Be specific**: "Check this modal component" vs. "check accessibility"
128+
- **Review incrementally**: The one-at-a-time approach helps focus on each issue
129+
- **Provide context**: Mention if something is a work-in-progress or has constraints
130+
- **Ask questions**: "Why is this critical?" if you need clarification

‎.claude/skills/accessibility-review/SKILL.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
name: accessibility-review
3+
description: Reviews UI for accessibility issues against WCAG 2.1/2.2 AA. Triggers on "is this accessible?", "check accessibility", or contrast/a11y review requests.
4+
---
5+
6+
# Accessibility Review
7+
8+
## Overview
9+
10+
This skill enables manual accessibility reviews of web content, components, and applications against WCAG 2.1/2.2 Level AA standards. Reviews focus on practical, modern accessibility requirements without being overly pedantic.
11+
12+
## When to Use This Skill
13+
14+
Use this skill when the user asks questions like:
15+
- "Is this accessible?"
16+
- "Can you review the color contrast?"
17+
- "Check this component for accessibility issues"
18+
- "Does this meet accessibility standards?"
19+
- Any request to review, check, or validate accessibility
20+
21+
## Review Process
22+
23+
### 1. Identify the Target
24+
25+
Determine what needs to be reviewed:
26+
- Specific component (button, form, modal, etc.)
27+
- Full page or application
28+
- Code file or set of files
29+
- Design mockup or screenshot
30+
31+
### 2. Conduct Manual Review
32+
33+
Use the WCAG checklist in `references/wcag-checklist.md` to systematically review the target against modern accessibility standards.
34+
35+
Focus on the most common and impactful issues:
36+
- **Perceivable**: Color contrast, text alternatives, semantic structure
37+
- **Operable**: Keyboard navigation, focus management, interactive elements
38+
- **Understandable**: Clear labels, error handling, consistent navigation
39+
- **Robust**: Valid HTML, ARIA usage, compatibility
40+
41+
### 3. Prioritize Findings
42+
43+
Classify each issue as:
44+
45+
**Critical** - Blocks users from accessing core functionality:
46+
- Missing alt text on meaningful images
47+
- Non-keyboard accessible interactive elements
48+
- Insufficient color contrast (below 4.5:1 for normal text, 3:1 for large text)
49+
- Forms without proper labels
50+
- Missing focus indicators
51+
- Inaccessible modal/dialog patterns
52+
- Auto-playing media without controls
53+
54+
**Warning** - Creates friction but doesn't fully block access:
55+
- Suboptimal heading hierarchy (skipped levels)
56+
- Missing ARIA landmarks
57+
- Link text that's unclear out of context
58+
- Redundant or unnecessary ARIA
59+
- Touch targets smaller than 44x44px
60+
- Missing skip links
61+
- Non-descriptive error messages
62+
63+
### 4. Stepped Review (One Issue at a Time)
64+
65+
**IMPORTANT**: Do NOT present all findings at once. Review issues one at a time, waiting for user decision before proceeding.
66+
67+
**4.1 Start with Overview**
68+
69+
Begin by telling the user how many issues were found:
70+
71+
```
72+
Found [X] accessibility issues ([Y] critical, [Z] warnings).
73+
74+
Let's review them one at a time. I'll present each issue with a recommended fix, and you can decide to:
75+
- **Fix** — I'll implement the change
76+
- **Ignore** — Tell me why, and I'll note it
77+
78+
Starting with critical issues first.
79+
```
80+
81+
**4.2 Present Each Issue**
82+
83+
For each issue, present ONE at a time using this format:
84+
85+
```
86+
───────────────────────────────────
87+
Issue [1/X]: [Critical/Warning]
88+
───────────────────────────────────
89+
90+
**Problem**: [Clear description of the issue]
91+
92+
**Location**: `file_path:line_number`
93+
[Show the relevant code snippet]
94+
95+
**Impact**: [How this affects users — be specific about who and how]
96+
97+
**Recommended Fix**:
98+
[Specific code change or approach]
99+
100+
───────────────────────────────────
101+
Fix this issue, or ignore? (If ignoring, please share why)
102+
```
103+
104+
**4.3 Handle User Response**
105+
106+
**If user says "fix":**
107+
1. Implement the fix
108+
2. Confirm: "Fixed. [Brief description of what changed]"
109+
3. Move to next issue
110+
111+
**If user says "ignore" with reason:**
112+
1. Acknowledge: "Noted — ignoring because: [their reason]"
113+
2. Track the decision (see 4.4)
114+
3. Move to next issue
115+
116+
**If user says "ignore" without reason:**
117+
1. Ask: "Got it. Quick note on why? (Helps for future reference)"
118+
2. Accept any response and move on
119+
120+
**4.4 Track Decisions**
121+
122+
Keep a running tally as you go through issues. After all issues are reviewed, present a summary.
123+
124+
### 5. Final Summary
125+
126+
After reviewing all issues, present a summary:
127+
128+
```
129+
## Accessibility Review Complete
130+
131+
**Reviewed**: [X] issues ([Y] critical, [Z] warnings)
132+
133+
### Fixed ([N])
134+
- [Issue description] — `file:line`
135+
- [Issue description] — `file:line`
136+
137+
### Ignored ([N])
138+
- [Issue description] — Reason: [user's reason]
139+
- [Issue description] — Reason: [user's reason]
140+
141+
### Remaining Concerns
142+
[Any patterns noticed, suggestions for future, or issues that were ignored but warrant reconsideration]
143+
```
144+
145+
## Review Guidelines
146+
147+
**Be Practical**: Focus on issues that genuinely impact users. Modern WCAG 2.1/2.2 Level AA is the standard—avoid over-engineering or citing obscure edge cases.
148+
149+
**Be Specific**: Reference actual code locations using `file_path:line_number` format when possible.
150+
151+
**Be Constructive**: Provide actionable fixes, not just problems. Include code examples when helpful.
152+
153+
**Consider Context**: Some patterns may have accessibility trade-offs. Acknowledge these and suggest the most accessible approach for the use case.
154+
155+
## Common Patterns to Check
156+
157+
### Interactive Elements
158+
- All interactive elements must be keyboard accessible (Enter/Space to activate)
159+
- Focus must be visible with clear indicators
160+
- Custom controls need proper ARIA roles and states
161+
162+
### Forms
163+
- All inputs must have associated labels (explicit or aria-label)
164+
- Error messages must be programmatically associated with fields
165+
- Required fields must be indicated clearly
166+
167+
### Color and Contrast
168+
- Text contrast: 4.5:1 minimum for normal text, 3:1 for large text (18pt+ or 14pt+ bold)
169+
- UI components: 3:1 contrast for interactive elements and their states
170+
- Don't rely on color alone to convey information
171+
172+
### Images and Media
173+
- Meaningful images need descriptive alt text
174+
- Decorative images should have empty alt (alt="")
175+
- Videos need captions, audio content needs transcripts
176+
177+
### Structure
178+
- Use semantic HTML (nav, main, article, etc.)
179+
- Heading hierarchy should be logical (h1 → h2 → h3)
180+
- ARIA landmarks help screen reader navigation
181+
182+
## Resources
183+
184+
This skill includes:
185+
186+
### references/wcag-checklist.md
187+
Comprehensive checklist of WCAG 2.1/2.2 Level AA requirements organized by principle (Perceivable, Operable, Understandable, Robust). Reference this during reviews to ensure thorough coverage of accessibility standards.

0 commit comments

Comments
 (0)