| name | accessibility-review |
| description | Heuristic and WCAG 2.1 AA accessibility review of UX specs, Figma flows, or described interactions. Tied to your design system's accessibility standards. |
| version | 1 |
| user-invocable | true |
/accessibility-review - Accessibility Review
Systematic accessibility review of design work before engineering handoff.
Quick Start
/accessibility-review → Review a spec I'll help you describe
/accessibility-review [paste spec or describe flow] → I'll run the review
/accessibility-review [Figma link] → I'll review the flow (requires Figma MCP)
Output: Review saved to outputs/design-specs/[feature]-a11y-review-[date].md
Standard: WCAG 2.1 AA (unless your principles.md specifies otherwise)
Time: 15–20 minutes per flow or spec
Context Routing (Internal)
Before reviewing, check:
| Source | Files/Folders | What to extract |
|---|
| Accessibility standards | context-library/design-system/principles.md | Team's specific AA requirements and any exceptions |
| Component accessibility | context-library/design-system/component-ux/ | Existing accessibility rules for components being used |
| Spec | outputs/design-specs/ or described in chat | The flow, states, and components being reviewed |
| Figma MCP (if connected) | Linked file | Live view of the design being reviewed |
Review Framework
Guided Questions
- "What are you reviewing? (spec, Figma flow, described interaction)"
- "What platform? (web, iOS, Android)"
- "What's the user flow from entry to completion?"
- "What interactive elements are present?"
Review Areas
Work through each area systematically. Flag issues with severity and the WCAG criterion.
1. Keyboard Navigation
- Can all interactive elements be reached via Tab in a logical order?
- Does focus order match visual/reading order?
- Is there a keyboard trap anywhere (e.g., dialog or modal)?
- Can the user exit any focused component with Escape?
- Are all actions achievable without a mouse?
- Do custom components (if any) implement standard keyboard patterns?
WCAG criteria: 2.1.1 (Keyboard), 2.1.2 (No Keyboard Trap), 2.4.3 (Focus Order)
2. Focus Visibility
- Is the focus indicator visible on all interactive elements?
- Does the focus indicator meet 3:1 contrast ratio against adjacent background?
- Does the spec explicitly NOT use
outline: none without a replacement?
WCAG criterion: 2.4.7 (Focus Visible), 2.4.11 (Focus Appearance — AA 2.2)
3. Screen Reader Compatibility
- Do all images have meaningful
alt text? (Decorative: alt="")
- Do all form inputs have associated visible
<label> elements?
- Are error messages programmatically associated with their input (
aria-describedby)?
- Do icons used as buttons have
aria-label?
- Are status messages and dynamic content changes announced (
aria-live)?
- Is there a logical heading hierarchy (one
<h1>, logical h2/h3 nesting)?
WCAG criteria: 1.1.1 (Non-text Content), 1.3.1 (Info and Relationships), 4.1.3 (Status Messages)
4. Color and Contrast
- Normal text: 4.5:1 minimum contrast against background
- Large text (18px+ or 14px+ bold): 3:1 minimum
- UI components and focus indicators: 3:1 minimum against adjacent color
- Is information conveyed by color alone? (Error state, status badge, etc.) If so, a secondary indicator is required.
WCAG criteria: 1.4.3 (Contrast Minimum), 1.4.11 (Non-text Contrast), 1.4.1 (Use of Color)
5. Touch and Pointer
- Are touch targets at least 44×44 CSS px?
- Does any interaction require hovering? (hover-only affordances fail on mobile)
- Do multi-step gestures (swipe, pinch) have button alternatives?
WCAG criteria: 2.5.5 (Target Size), 2.5.3 (Pointer Gestures)
6. Motion and Animation
- Do animations that convey information work without motion? (respect
prefers-reduced-motion)
- Does anything flash more than 3 times per second?
WCAG criteria: 1.4.2 (Audio Control), 2.3.1 (Three Flashes)
7. Content and Copy
- Do error messages say what went wrong AND how to fix it?
- Do empty states explain why and give a clear next action?
- Are loading states communicated to screen readers (not just visual)?
- Is link text meaningful out of context? ("Learn more about X" not just "click here")
WCAG criteria: 2.4.6 (Headings and Labels), 3.3.1 (Error Identification), 3.3.3 (Error Suggestion)
8. Forms
- All inputs have visible labels (not just placeholder)
- Required fields marked (
isRequired prop or equivalent)
- Error validation messages are inline, specific, and programmatically associated
- Groups (checkbox sets, radio groups) use
<fieldset> + <legend> (or RadioGroup/CheckboxGroup)
WCAG criteria: 1.3.5 (Identify Input Purpose), 3.3.2 (Labels or Instructions)
Severity Classification
| Severity | Meaning | When to fix |
|---|
| Critical | Blocks access for users with disabilities. Cannot complete the task. | Before launch |
| Serious | Significant barrier. Frustrating or difficult but not completely blocking. | This release |
| Minor | Usability degradation for some users. Task completable with effort. | Next iteration |
| Enhancement | Goes beyond AA; WCAG AAA or best practice. | Backlog |
Output Structure
# Accessibility Review: [Feature Name]
Date: [date]
Reviewer:
Standard: WCAG 2.1 AA
Spec / Figma: [link]
---
## Summary
[1–2 sentences: overall accessibility quality and key concerns]
Critical issues: [#]
Serious issues: [#]
Minor issues: [#]
Enhancements: [#]
---
## Issues
### Issue 1: [Short description]
Severity: Critical / Serious / Minor
WCAG: [criterion number and name]
Location: [screen, component, or state]
What's wrong:
[Specific description of the problem]
How to fix:
[Specific, actionable fix. Reference Storybook component or prop if applicable.]
---
## What's Working Well
[Specific accessibility decisions in the design that are solid and should be preserved]
---
## Sign-off Checklist
- [ ] All critical issues resolved
- [ ] Serious issues have remediation plan with owner and date
- [ ] Minor issues logged for next iteration
Quality Check Before Saving
