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

Div/span with onClick (use or )
No visible label (use text content or aria-label)
Button used for navigation (use )
Link used for action (use )

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

This Skill: Quick element-specific checks
- "Is this button accessible?"
- "Check this form for a11y"
- Single component analysis
/audit-a11y Command: Comprehensive site audit
- Full WCAG 2.1 Level AA audit
- Multiple pages analyzed
- Detailed compliance reports

Resources

WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
WebAIM Keyboard Testing: https://webaim.org/articles/keyboard/

accessibility-checker