--- 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 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 ```markdown ## 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