| name | accessibility-checker |
| description | Automatically check specific elements or code for accessibility issues when user asks if something is accessible or mentions WCAG compliance. Performs focused accessibility checks on individual components, forms, or pages. Invoke when user asks "is this accessible?", "WCAG compliant?", or shows code/elements asking about accessibility. |
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
