playbooks

home / skills / shotaiuchi / dotclaude / review-accessibility

review-accessibility skill

/dotclaude/skills/review-accessibility

This skill helps you review UI code for accessibility, ensuring screen readers, keyboard navigation, color contrast, and semantic structure meet WCAG

npx playbooks add skill shotaiuchi/dotclaude --skill review-accessibility

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: review-accessibility
description: >-
  Accessibility (a11y)-focused code review. Apply when reviewing UI code for
  screen reader support, keyboard navigation, color contrast, WCAG compliance,
  semantic HTML, ARIA labels, and inclusive design.
user-invocable: false
---

# Accessibility Review

Review code from an accessibility (a11y) perspective.

## Review Checklist

### Screen Reader Support
- Verify all interactive elements have accessible labels
- Check images have meaningful alt text (or empty alt for decorative)
- Ensure dynamic content changes are announced
- Verify form fields have associated labels

### Keyboard Navigation
- Check all interactive elements are keyboard accessible
- Verify logical tab order follows visual layout
- Ensure focus indicators are visible
- Check keyboard traps do not exist (can always escape)

### Visual & Color
- Verify color contrast meets WCAG AA (4.5:1 text, 3:1 large text)
- Check information is not conveyed by color alone
- Ensure text is resizable without loss of content
- Verify animations can be disabled (prefers-reduced-motion)

### Semantic Structure
- Check proper heading hierarchy (h1 > h2 > h3)
- Verify semantic HTML elements are used (nav, main, article)
- Ensure lists use proper list elements
- Check landmark regions are properly defined

### Mobile Accessibility
- Verify touch targets are at least 44x44dp
- Check content descriptions on Android (contentDescription)
- Ensure accessibility traits on iOS (accessibilityLabel, accessibilityHint)
- Verify gesture-based actions have alternatives

### WCAG Compliance
- Level A: All essential requirements met
- Level AA: Enhanced requirements for public-facing applications
- Check forms have clear error identification and suggestions
- Verify time-based content can be paused or extended

## Output Format

| Level | Description |
|-------|-------------|
| Blocker | WCAG A violation, prevents access for some users |
| Major | WCAG AA violation, significant barrier |
| Minor | Usability issue for assistive technology users |
| Enhancement | Improves experience but not a violation |

Overview

This skill performs accessibility-focused code reviews for UI code, identifying issues that affect screen reader users, keyboard-only navigation, color contrast, and semantic structure. It flags WCAG A/AA violations, ranks findings by severity, and suggests targeted fixes to make interfaces inclusive and compliant.

How this skill works

The review inspects markup, attributes, ARIA usage, styling, scripts that modify the DOM, and mobile accessibility properties. It evaluates screen reader labels, keyboard focus behavior, contrast ratios, heading structure, form labeling, and mobile touch targets, then classifies each finding as Blocker, Major, Minor, or Enhancement.

When to use it

  • Before a public release to ensure WCAG A/AA compliance
  • During PR reviews for UI components or pages
  • When adding dynamic content or client-side navigation
  • When auditing mobile apps for iOS and Android accessibility
  • When improving usability for assistive technology users

Best practices

  • Treat missing accessible labels and unlabeled form fields as blockers and fix immediately
  • Prefer native semantic elements over ARIA when possible (use <button>, <nav>, <main>)
  • Verify keyboard tab order matches visual order and that focus is visibly styled
  • Measure color contrast and avoid conveying information by color alone
  • Test dynamic updates with a screen reader and ensure proper aria-live regions
  • Include alternative interactions for gesture-only controls on mobile

Example use cases

  • Review a login form to ensure inputs have labels, error messages are announced, and focus moves to the first invalid field
  • Audit a single-page app to confirm route changes update focus and screen readers are informed
  • Check a data table for proper headers, keyboard sortable columns, and row selection announcements
  • Validate a marketing page for contrast issues, heading hierarchy, and non-text content descriptions
  • Assess a mobile screen for adequate touch target size and platform-specific accessibility properties

FAQ

How are findings prioritized?

Findings map to severity: Blocker for WCAG A failures, Major for WCAG AA breaches, Minor for assistive tech usability issues, and Enhancement for suggested improvements.

Do you replace manual testing with screen readers and keyboard checks?

No. Automated inspection and code review surface many issues, but manual testing with real assistive technologies and keyboard-only interaction is required to validate behavior.