Accessibility Checker
Automatically check code and elements for accessibility issues.
Accessibility Philosophy
Accessibility is not a checklist—it's a mindset of inclusive design.
Core Beliefs
- Universal Design: Build for everyone from the start, not as an afterthought
- Progressive Enhancement: Core functionality works for all, enhancements are optional
- Semantic First: Meaningful HTML structure over ARIA workarounds
- Real Users: Test with actual assistive technology users when possible
Scope Balance
- Quick checks (this skill): Fast feedback on specific components (60-70% of issues)
- Comprehensive audits (
/audit-a11y command): Full site analysis with parallel specialists (85-90% coverage)
- Manual testing: Keyboard, screen readers, user testing (catches remaining 10-15%, irreplaceable)
This skill provides rapid feedback during development. For production readiness, use comprehensive audits + manual testing.
When to Use This Skill
Activate this skill when the user:
- Asks "is this accessible?"
- Shows an element and asks "does this meet WCAG?"
- Mentions "accessibility issue", "a11y", or "screen reader"
- Asks "will this work for keyboard users?"
- Questions contrast, ARIA, alt text, or form labels
- Says "check this for accessibility"
Decision Framework
Before checking accessibility, assess:
What Element Type Is This?
- Interactive (buttons, links, forms) → Check keyboard access, focus indicators, ARIA
- Content (text, headings, images) → Check contrast, hierarchy, alt text
- Structure (navigation, landmarks) → Check semantic HTML, skip links
- Dynamic (modals, dropdowns, tabs) → Check keyboard traps, ARIA states
- Media (images, video, audio) → Check captions, transcripts, alt text
What WCAG Level Is Required?
WCAG 2.1 Level AA (industry standard):
- ✅ Color contrast: 4.5:1 (normal text), 3:1 (large text)
- ✅ Keyboard navigation: All functionality accessible
- ✅ Focus indicators: Visible on all interactive elements
- ✅ Form labels: All inputs have associated labels
- ✅ Alt text: Meaningful for content images, empty for decorative
WCAG AAA (enhanced):
- Higher contrast ratios (7:1 for normal text)
- More stringent requirements
What's the Scope?
- Single element - User shows specific component → Check that element
- Page section - User mentions component → Check related elements
- Entire page - User says "check this page" → Full page audit
- Interactive flow - User shows user journey → Test keyboard flow
What Are Common Issues?
Quick wins (easy to fix):
- Missing alt text on images
- Low contrast text
- Missing form labels
- Missing focus indicators
Complex issues (need design changes):
- Keyboard traps
- Complex ARIA patterns
- Dynamic content announcements
- Touch target sizes
What Testing Method?
- Code review → Check semantic HTML, ARIA attributes
- Manual keyboard test → Tab through page, test interactions
- Contrast calculation → Calculate exact ratios
- Screen reader test → Test with VoiceOver/NVDA (if comprehensive audit)
- Automated tools → Run axe-core or pa11y (for full audits)
Decision Tree
User asks about accessibility
↓
Identify element type (interactive/content/structure)
↓
Determine WCAG level (AA standard)
↓
Check specific criteria (contrast/keyboard/ARIA)
↓
Test manually if needed
↓
Report issues with confidence scores
↓
Provide exact fixes (colors, ARIA, HTML)
Best Practices
DO:
- ✅ Use semantic HTML5 elements first (header, nav, main, article, button, etc.)
- ✅ Provide visible labels for all form controls (label element, not placeholder)
- ✅ Ensure 4.5:1 contrast for normal text, 3:1 for large text (WCAG AA)
- ✅ Make all interactive elements keyboard accessible (tab, enter, space, arrows)
- ✅ Provide text alternatives for non-text content (alt, aria-label, captions)
- ✅ Test with keyboard only (no mouse) before submitting
- ✅ Use ARIA to enhance, not replace, semantic HTML
- ✅ Ensure focus indicators are visible (2px minimum, high contrast)
- ✅ Structure content with proper heading hierarchy (h1 → h2 → h3)
DON'T:
- ❌ Use div/span with click handlers instead of button/link
- ❌ Rely on color alone to convey information
- ❌ Use placeholder as label replacement
- ❌ Trap keyboard focus in modals without escape mechanism
- ❌ Hide content with display:none when it should be screen-reader accessible
- ❌ Use positive tabindex (tabindex="1", "2", etc.) - breaks natural tab order
- ❌ Add ARIA when semantic HTML would suffice
- ❌ Remove focus outlines without providing alternative indicators
- ❌ Auto-play media without user control
- ❌ Use complex ARIA patterns when simple alternatives exist
Quick Checks
This skill performs focused accessibility checks on specific elements, unlike /audit-a11y which does comprehensive site-wide audits.
Common Checks
Button Accessibility:
- Has accessible name (text, aria-label, or aria-labelledby)
- Keyboard focusable
- Proper ARIA role if custom button
- Sufficient color contrast
Form Accessibility:
- All inputs have associated labels
- Error messages properly linked
- Required fields indicated
- Fieldsets for related inputs
Image Accessibility:
- Alt text present and descriptive
- Decorative images have alt=""
- Complex images have detailed descriptions
Link Accessibility:
- Descriptive link text (not "click here")
- Links distinguishable from text
- Keyboard accessible
Response Format
## Accessibility Check: [Element Type]
### ✅ Passes
- Has proper ARIA label
- Keyboard accessible
- Sufficient color contrast (4.8:1)
### ❌ Issues Found
1. **Missing focus indicator** (WCAG 2.4.7 Level AA)
- Current: No visible focus state
- Fix: Add `:focus` styles with outline
2. **Low contrast** (WCAG 1.4.3 Level AA)
- Current: 3.2:1
- Required: 4.5:1
- Fix: Use darker text color #333
### Suggested Code
[Provide fixed code example]
Common Issues by Component Type
Forms
- Missing elements (use for attribute)
- Placeholder as label (violates 3.3.2 Labels or Instructions)
- No error messages associated (use aria-describedby)
- Required fields not marked (use required + aria-required)
Modals/Dialogs
- No focus trap (keyboard escapes modal)
- No ESC key handler (violates 2.1.2 No Keyboard Trap)
- Missing role="dialog" or role="alertdialog"
- No aria-labelledby pointing to title
- Focus not moved to modal on open
Buttons/Links
Images
- Missing alt attribute (violates 1.1.1 Non-text Content)
- Decorative images with alt text (should be alt="")
- Complex images without long description (use aria-describedby)
- Icon buttons without text alternative (use aria-label)
Integration with /audit-a11y Command
Resources