kanopi/accessibility-checker

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

1. Universal Design: Build for everyone from the start, not as an afterthought
2. Progressive Enhancement: Core functionality works for all, enhancements are optional
3. Semantic First: Meaningful HTML structure over ARIA workarounds
4. 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?

1. Interactive (buttons, links, forms) → Check keyboard access, focus indicators, ARIA
2. Content (text, headings, images) → Check contrast, hierarchy, alt text
3. Structure (navigation, landmarks) → Check semantic HTML, skip links
4. Dynamic (modals, dropdowns, tabs) → Check keyboard traps, ARIA states
5. 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?

1. Code review → Check semantic HTML, ARIA attributes
2. Manual keyboard test → Tab through page, test interactions
3. Contrast calculation → Calculate exact ratios
4. Screen reader test → Test with VoiceOver/NVDA (if comprehensive audit)
5. 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 <label> 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 <button> or <a>)
• No visible label (use text content or aria-label)
• Button used for navigation (use <a>)
• Link used for action (use <button>)

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/