diff --git a/.claude/skills/web-accessibility-checker/SKILL.md b/.claude/skills/web-accessibility-checker/SKILL.md new file mode 100644 index 000000000..44acb6e33 --- /dev/null +++ b/.claude/skills/web-accessibility-checker/SKILL.md @@ -0,0 +1,387 @@ +--- +name: web-accessibility-checker +description: Review websites for accessibility compliance with WCAG 2.2 Level AA and EU EAA requirements. Use when user asks to check, audit, review, or assess website accessibility, WCAG compliance, or EU accessibility standards. Identifies violations, provides remediation guidance, and generates compliance reports. +--- + +# Web Accessibility Checker Skill + +## Quick Start + +The European Accessibility Act (EAA) requires WCAG 2.2 Level AA compliance for organizations doing business in the EU (10+ employees, €2M+ revenue). This skill helps you audit websites for compliance through a three-step process: + +1. **Automated scan** - Run mechanical checks for common issues +2. **Manual checks** - Test keyboard navigation, screen readers, and UX patterns +3. **Report generation** - Create structured compliance reports + +**Important:** Automated tools catch only ~30-40% of accessibility issues. Manual testing is essential for true compliance. + +## Testing Workflow + +### Step 1: Automated Testing + +Run the automated checker to identify mechanical violations: + +```bash +node scripts/automated-checks.js +``` + +The script checks for: +- Color contrast ratios (WCAG 2.2 SC 1.4.3, 1.4.11) +- Missing alt text (SC 1.1.1) +- Form labels (SC 3.3.2) +- Heading hierarchy (SC 1.3.1, 2.4.6) +- ARIA attributes (SC 4.1.2) +- Keyboard navigation issues (SC 2.1.1) +- Link text quality (SC 2.4.4) +- HTML validation (SC 4.1.1) + +**Output:** JSON file with violations categorized by WCAG level (A, AA, AAA) and success criterion. + +**Note:** Focus on Level A and AA violations. AAA is beyond EAA requirements and often not achievable for all content. + +### Step 2: Manual Testing + +Automated tools miss 60-70% of issues. Perform these critical manual checks: + +**Keyboard Navigation (15-20 minutes):** +1. Tab through all interactive elements (links, buttons, form fields) +2. Verify focus indicators are clearly visible (SC 2.4.7) +3. Check for logical tab order (SC 2.4.3) +4. Ensure no keyboard traps (SC 2.1.2) +5. Test skip links work (SC 2.4.1) + +**Visual Testing:** +1. Disable CSS and verify logical reading order (SC 1.3.2) +2. Zoom to 200% - check text reflows without horizontal scrolling (SC 1.4.4, 1.4.10) +3. Zoom to 400% - verify no content is clipped or hidden (SC 1.4.10) +4. Spot-check color contrast for edge cases like hover states (SC 1.4.3) + +**Form Testing:** +1. Trigger validation errors - verify messages are clear and programmatically associated (SC 3.3.1, 3.3.3) +2. Check form instructions appear before fields (SC 3.3.2) +3. Verify autocomplete works for common fields (SC 1.3.5, 3.3.7) +4. Test password managers can fill authentication forms (SC 3.3.8) + +**Interactive Component Testing:** +1. Verify UI components have 3:1 contrast with adjacent colors (SC 1.4.11) +2. Check interactive targets are at least 24×24 CSS pixels (SC 2.5.5) +3. For drag operations, verify single-pointer alternatives exist (SC 2.5.7) +4. Test hover/focus content is hoverable, dismissible, and persistent (SC 1.4.13) + +**Screen Reader Spot Check (if time permits):** +1. Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS) +2. Verify page landmarks are announced (SC 1.3.1) +3. Check form errors are read aloud (SC 3.3.1) +4. Verify image alt text is meaningful (SC 1.1.1) + +For complete manual testing procedures, reference `references/manual-testing-checklist.md`. + +### Step 3: Report Generation + +Generate a structured compliance report: + +```bash +node scripts/generate-report.js violations.json +``` + +The report includes: +- **Executive summary** - Pass/fail counts by level (A, AA, AAA) +- **Violations by POUR principle** - Grouped thematically, not by page location +- **Detailed findings** - Each violation shows: + - Success criterion number (e.g., "WCAG 2.2 SC 1.4.3") + - Severity (Critical, High, Medium, Low) + - Location (URL, selector, line number) + - Description (what's wrong) + - Remediation steps (how to fix it) + - Link to WCAG documentation +- **Testing methodology** - Tools used, pages tested, date +- **Next steps** - Prioritized remediation recommendations + +## The Four POUR Principles + +WCAG 2.2 is organized around four principles that make content accessible: + +### Perceivable +Information and UI components must be presentable to users in ways they can perceive. This includes text alternatives for non-text content, captions for audio/video, adaptable content that can be presented in different ways, and content that's distinguishable (sufficient color contrast, resizable text, no information conveyed by color alone). + +### Operable +UI components and navigation must be operable. Content must be keyboard accessible, users need enough time to read and interact, nothing should cause seizures, navigation must be clear and consistent, and multiple input modalities should be supported (mouse, keyboard, touch, voice). + +### Understandable +Information and UI operation must be understandable. Text must be readable, pages must behave in predictable ways, and users should get help with input errors (clear labels, error messages, suggestions). + +### Robust +Content must be robust enough to work with current and future assistive technologies. This primarily means valid HTML, proper ARIA usage, and compatibility with screen readers and other assistive technologies. + +For detailed success criteria under each principle, reference `references/wcag-22-criteria.md`. + +## Critical Level AA Requirements + +These are the most commonly failed AA criteria that audits must catch: + +**WCAG 2.1 AA Criteria (still required in 2.2):** + +- **1.4.3 Contrast (Minimum):** Text must have 4.5:1 contrast ratio (3:1 for large text ≥18pt or ≥14pt bold). Don't just report "insufficient contrast" - specify actual ratio and required ratio. Example: "Text '#666' on '#fff' has 3.2:1 contrast, needs 4.5:1" + +- **1.4.10 Reflow:** Content reflows without horizontal scrolling at 320px width (equivalent to 400% zoom). No 2D scrolling required to read content. + +- **1.4.11 Non-text Contrast:** UI components and graphical objects must have 3:1 contrast with adjacent colors. This includes form field borders, button outlines, focus indicators, chart elements. + +- **1.4.12 Text Spacing:** Content must support user text spacing adjustments (line height 1.5×, paragraph spacing 2×, letter spacing 0.12×, word spacing 0.16×) without loss of content or functionality. + +- **1.4.13 Content on Hover or Focus:** If hovering or focusing triggers additional content (tooltips, dropdowns), it must be: + - Hoverable (pointer can move to the revealed content) + - Dismissible (can close without moving focus, usually Escape key) + - Persistent (stays visible until user dismisses or focus moves) + +- **2.4.7 Focus Visible:** Keyboard focus indicators must be clearly visible for all interactive elements. Default browser focus styles are acceptable but custom focus styles must have 3:1 contrast. + +**New WCAG 2.2 AA Criteria (added October 2023):** + +- **2.5.5 Target Size (Minimum):** Interactive targets must be at least 24×24 CSS pixels, with exceptions for inline links, user-controlled sizes, and essential spacing. This is less strict than AAA's 44×44 requirement. + +- **2.5.7 Dragging Movements:** If functionality uses dragging (sliders, sortable lists, drawing), provide a single-pointer alternative (buttons, keyboard controls). Exception: dragging is essential (signature drawing). + +- **2.5.8 Target Size (Enhanced) [AAA, not required]:** 44×44 CSS pixels. Mention only if user specifically asks about AAA. + +- **3.2.6 Consistent Help:** If help mechanisms appear on multiple pages (contact links, chatbots, phone numbers), they must appear in the same relative order. Helps users with cognitive disabilities. + +- **3.3.7 Redundant Entry:** Information previously entered in the same process should be auto-populated or available to select. Examples: shipping address pre-filled in billing, previous search terms available. Exceptions: re-entry is essential (password confirmation) or security-required. + +- **3.3.8 Accessible Authentication (Minimum):** Don't require cognitive function tests for authentication. Password managers must work, or provide alternatives like: + - Email/SMS magic links + - Biometric authentication + - Copy-paste support for passwords + - Object recognition (not text entry or puzzles) + +**Common Mistakes:** +- Invisible focus indicators or focus indicators with <3:1 contrast +- Buttons/links smaller than 24×24 pixels on mobile +- Form fields requiring re-entry of email or phone (violates 3.3.7) +- Password fields that block paste (violates 3.3.8) +- Help links in footer on page 1 but header on page 2 (violates 3.2.6) + +## Report Format + +Structure all accessibility reports consistently: + +```markdown +# Accessibility Audit Report + +**Website:** [URL] +**Date:** [ISO date] +**Auditor:** [Name/Tool] + +## Executive Summary + +- **Total issues:** 47 (12 critical, 23 high, 8 medium, 4 low) +- **Level A compliance:** FAIL (8 issues) +- **Level AA compliance:** FAIL (39 issues) +- **Overall EAA compliance:** FAIL + +**Verdict:** This website does not meet WCAG 2.2 Level AA requirements and is not EAA-compliant. + +## Violations by Principle + +### Perceivable (18 issues) + +#### SC 1.1.1 Non-text Content (Level A) - CRITICAL +**Issue:** 12 images missing alt text +**Location:** +- `/products` - 8 product images (`.product-card img`) +- `/about` - 4 team photos (`.team-member img`) + +**Impact:** Screen reader users cannot understand image content. + +**Remediation:** +```html + + + + +Blue ceramic coffee mug with white handle +``` + +For decorative images, use `alt=""` not omit the attribute entirely. + +**Reference:** [WCAG 2.2 SC 1.1.1](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) + +--- + +#### SC 1.4.3 Contrast (Minimum) (Level AA) - HIGH +**Issue:** Link text has insufficient contrast +**Location:** `/homepage` - Footer links +**Measured contrast:** 3.1:1 (text #7A7A7A on #FFFFFF) +**Required contrast:** 4.5:1 + +**Impact:** Users with low vision or color blindness cannot read links. + +**Remediation:** +```css +/* Before */ +footer a { color: #7A7A7A; } + +/* After - darkened to meet 4.5:1 */ +footer a { color: #595959; } +``` + +Use tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify. + +**Reference:** [WCAG 2.2 SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) + +--- + +[Continue for all Perceivable violations...] + +### Operable (15 issues) + +[List violations: keyboard access, focus visible, target size, dragging alternatives, etc.] + +### Understandable (10 issues) + +[List violations: form labels, error messages, consistent help, redundant entry, authentication] + +### Robust (4 issues) + +[List violations: HTML validation, ARIA usage, name-role-value] + +## Testing Methodology + +**Automated Testing:** +- Tool: axe-core 4.8.0 via Selenium +- Pages tested: 15 (all main user journeys) +- Date: 2025-10-23 + +**Manual Testing:** +- Keyboard navigation: Full audit of homepage, product listing, checkout +- Screen reader: Spot checks with NVDA on Windows +- Zoom testing: All pages tested at 200% and 400% +- Form testing: Contact form, login, checkout flow + +**Standards:** +- WCAG 2.2 Level AA +- EN 301 549 (European standard) +- European Accessibility Act (EAA) requirements + +## Next Steps (Prioritized) + +### Phase 1: Critical Issues (1-2 weeks) +1. Add alt text to all images (SC 1.1.1) - 12 issues +2. Fix color contrast on links and buttons (SC 1.4.3) - 8 issues +3. Add visible focus indicators (SC 2.4.7) - 6 issues + +### Phase 2: High Priority (2-4 weeks) +4. Add form labels and error messages (SC 3.3.2, 3.3.1) - 15 issues +5. Increase button/link target sizes to 24×24px (SC 2.5.5) - 9 issues +6. Fix heading hierarchy (SC 1.3.1) - 5 issues + +### Phase 3: Medium Priority (1-2 months) +7. Implement reflow for mobile (SC 1.4.10) - 4 issues +8. Add keyboard alternatives to drag operations (SC 2.5.7) - 2 issues +9. Enable autocomplete on forms (SC 3.3.7) - 3 issues + +### Phase 4: Polish (Ongoing) +10. Fix HTML validation errors (SC 4.1.1) - 4 issues +11. Review ARIA usage (SC 4.1.2) - 3 issues + +**Estimated total remediation time:** 8-12 weeks with 1 FTE developer + +**Recommended re-audit:** After Phase 2 completion (approximately 6 weeks) +``` + +## Important Notes + +1. **Automated tools are incomplete:** Automated scanners catch 30-40% of issues. Manual testing is required for EAA compliance. Don't rely solely on scripts. + +2. **Focus on A and AA:** Level AAA is optional and often unachievable for all content types (e.g., AAA contrast requires 7:1 ratio, difficult for branded colors). EAA requires only Level AA. + +3. **WCAG 2.2, not 2.1:** The skill references WCAG 2.2 (published October 2023), which includes 9 new success criteria. Ensure audits check 2.2 requirements, not just 2.1. + +4. **EAA deadline is June 28, 2025:** Organizations need time to remediate. If auditing in 2025, emphasize urgency. + +5. **Microenterprises are exempt:** Companies with <10 employees AND <€2M revenue are exempt from EAA. All others doing business in EU must comply. + +6. **When in doubt, reference detailed guidance:** If you're unsure how to test a criterion or what counts as a violation, load the detailed WCAG criteria reference before making a determination. + +7. **Be specific in error reports:** Don't say "contrast insufficient." Say "Text '#666' on '#fff' has 3.2:1 contrast, needs 4.5:1 (WCAG 2.2 SC 1.4.3)." Include actual values and remediation code examples. + +8. **Prioritize by impact, not by count:** 1 broken keyboard navigation issue (affects 15% of users completely) is more critical than 20 missing alt texts on decorative images. + +## When to Use References + +Load reference documentation on-demand to avoid unnecessary token usage: + +**Load `references/wcag-22-criteria.md` when:** +- User asks about a specific success criterion (e.g., "What is SC 2.5.5?") +- You need detailed testing procedures for a criterion +- You need clarification on what counts as a pass/fail +- You're unsure which WCAG level a requirement belongs to +- User asks for complete WCAG 2.2 criteria list + +**Load `references/manual-testing-checklist.md` when:** +- Performing or explaining manual accessibility testing +- User asks "how do I test keyboard navigation?" +- User needs screen reader testing guidance +- You need step-by-step testing workflows + +**Load `references/eaa-requirements.md` when:** +- User asks about EU compliance or European Accessibility Act +- User asks about deadlines (June 28, 2025) +- User asks who must comply with EAA +- User asks about penalties for non-compliance +- User asks about relationship between EAA, EN 301 549, and WCAG + +## Typical User Interactions + +**Example 1: Quick audit request** +``` +User: "Check https://example.com for accessibility issues" +Assistant: +1. Run automated-checks.js on the URL +2. Perform quick keyboard tab test and zoom check +3. Generate report with violations grouped by POUR principle +4. Summarize critical issues and recommended next steps +``` + +**Example 2: Specific criterion question** +``` +User: "Does this site meet SC 1.4.3?" +Assistant: +1. Load references/wcag-22-criteria.md to get SC 1.4.3 details +2. Run contrast checker on the provided URL +3. Report specific contrast ratios for text elements +4. Provide pass/fail verdict with evidence +``` + +**Example 3: EAA compliance question** +``` +User: "Do we need to comply with EAA? We're a UK company." +Assistant: +1. Load references/eaa-requirements.md +2. Ask about employee count and revenue +3. Ask if they do business in EU (sell to EU customers, have EU users) +4. Provide compliance determination and deadline +``` + +**Example 4: Manual testing guidance** +``` +User: "How do I test keyboard navigation?" +Assistant: +1. Load references/manual-testing-checklist.md +2. Provide step-by-step keyboard testing workflow +3. Explain what to look for (focus indicators, tab order, traps) +4. Suggest testing tools if helpful +``` + +## Success Criteria + +The skill is working correctly if: + +1. ✅ Automated checks return violations with success criterion numbers and severity +2. ✅ Reports are grouped by POUR principle, not just page location +3. ✅ Each violation includes specific remediation steps with code examples +4. ✅ Reports distinguish between Level A, AA, and AAA (focusing on A/AA) +5. ✅ Manual testing checklist covers keyboard, zoom, screen reader, forms +6. ✅ EAA context is provided (who must comply, deadlines, relationship to WCAG) +7. ✅ References are loaded on-demand, not preemptively +8. ✅ Error messages are specific: "Text '#666' on '#fff' has 3.2:1, needs 4.5:1" not "fix contrast" diff --git a/.claude/skills/web-accessibility-checker/references/eaa-requirements.md b/.claude/skills/web-accessibility-checker/references/eaa-requirements.md new file mode 100644 index 000000000..4c04e9f58 --- /dev/null +++ b/.claude/skills/web-accessibility-checker/references/eaa-requirements.md @@ -0,0 +1,517 @@ +# European Accessibility Act (EAA) Requirements + +Comprehensive guide to EAA compliance requirements, deadlines, and relationship to WCAG 2.2. + +--- + +## What is the European Accessibility Act (EAA)? + +The **European Accessibility Act** (Directive (EU) 2019/882) is EU legislation requiring certain products and services to be accessible to people with disabilities. + +**Key facts:** +- Adopted: April 17, 2019 +- Transposition deadline: June 28, 2022 (EU member states had to implement into national law) +- **Compliance deadline: June 28, 2025** ← CRITICAL DATE +- Applies to: Products and services placed on market after June 28, 2025 +- Enforcement: National authorities in each EU member state + +--- + +## Who Must Comply? + +### Covered Organizations + +EAA applies to **economic operators** (businesses) that provide certain products or services to consumers in the EU: + +#### Size Requirements +- **10+ employees**, OR +- **Annual turnover or balance sheet ≥ €2 million** + +**Exemption:** Microenterprises (<10 employees AND <€2M revenue) are exempt. + +#### Geographic Scope +- Companies **operating in the EU** (selling to EU consumers) +- Includes non-EU companies if they serve EU market +- All 27 EU member states + likely EEA (Norway, Iceland, Liechtenstein) + +**Important:** UK companies selling to EU customers must comply. Brexit doesn't exempt from EAA. + +### Covered Products and Services + +EAA applies to **specific categories**, not all digital products: + +#### Digital Services (Relevant to Web Accessibility) +1. **E-commerce** - Online shops, marketplaces +2. **Banking services** - Online banking, mobile banking apps +3. **E-books** - Digital publications +4. **Websites and mobile applications** for services listed in EAA +5. **Consumer-facing digital services** + +#### Other Covered Items (Less relevant to web) +- Computers and operating systems +- Smartphones and tablets +- ATMs, ticketing machines, check-in machines +- E-readers +- Telecommunication services (phone, VoIP) +- Audio-visual media services +- Transport services (air, bus, rail, waterborne) + +### Who Is Exempt? + +- **Microenterprises:** <10 employees AND <€2M revenue +- **Disproportionate burden:** Can claim exemption if compliance would cause "disproportionate burden" (heavy documentation required) +- **Fundamental alteration:** If accessibility would fundamentally alter product/service +- **Pre-existing content:** Content created before June 28, 2025 (but must be updated if substantially modified) + +**Note:** Exemptions require justification and documentation. Cannot simply claim exemption without proof. + +--- + +## What Are the Accessibility Requirements? + +EAA references **EN 301 549**, the European standard for ICT accessibility, which incorporates **WCAG 2.1 Level AA**. + +### Technical Standard: EN 301 549 + +**EN 301 549 v3.2.1** (March 2021) is the harmonized European standard for ICT product and service accessibility. + +**Key sections:** +- **Section 9:** Web content (incorporates WCAG 2.1 Level AA) +- **Section 10:** Non-web documents +- **Section 11:** Software (including mobile apps) +- **Section 12:** Documentation and support + +### WCAG Compliance + +**EAA requirement = WCAG 2.1 Level AA minimum** + +**However:** Best practice is **WCAG 2.2 Level AA** because: +1. WCAG 2.2 is backward compatible with WCAG 2.1 +2. WCAG 2.2 adds 9 new success criteria (all improvements, no conflicts) +3. EN 301 549 will likely update to WCAG 2.2 in next revision +4. Many EU member states already reference WCAG 2.2 in national laws +5. Future-proofing compliance + +**Official position (as of 2024):** +- Minimum: WCAG 2.1 Level AA (via EN 301 549 v3.2.1) +- Recommended: WCAG 2.2 Level AA +- Level AAA: Not required, only recommended for specific contexts + +### What Must Be Accessible? + +For websites and mobile apps: + +1. **Content:** + - Text alternatives for non-text content + - Captions and audio descriptions for multimedia + - Proper heading structure + - Sufficient color contrast + - Resizable text without loss of functionality + +2. **Functionality:** + - Keyboard accessible + - Sufficient time to read/interact + - No seizure-inducing content + - Navigable structure + - Predictable behavior + +3. **Forms and Input:** + - Labeled form fields + - Error identification and suggestions + - Help text and instructions + - Error prevention for important transactions + +4. **Compatibility:** + - Valid HTML + - Compatibility with assistive technologies (screen readers, voice control) + - Proper use of ARIA when semantic HTML insufficient + +5. **Mobile Specific:** + - Touch target sizes (24×24 CSS pixels minimum) + - Alternatives to complex gestures + - Support for portrait and landscape orientation + - Reflow at 320px width + +--- + +## Timeline and Deadlines + +### Key Dates + +| Date | Event | +|------|-------| +| **April 17, 2019** | EAA adopted by EU | +| **June 28, 2022** | Member states must transpose into national law | +| **June 28, 2025** | **COMPLIANCE DEADLINE** - Products/services on market must comply | +| **June 28, 2030** | Self-service terminals (ATMs, kiosks) compliance deadline (extended) | + +### What "June 28, 2025" Means + +- **New products/services** launched after this date must be accessible from day one +- **Existing products/services** must be brought into compliance by this date +- No grandfather clause for existing products in scope +- **Recommendation:** Start compliance work in 2024, complete by Q1 2025 to allow buffer time + +### Urgency for 2025 + +If you're reading this in 2024-2025: + +**Immediate priorities:** +1. Determine if EAA applies to your organization (employees, revenue, EU sales) +2. Audit current accessibility state (automated + manual testing) +3. Create remediation roadmap with timelines +4. Allocate budget and resources +5. Begin fixing critical issues (keyboard access, alt text, contrast, forms) +6. Plan for re-audit before June 2025 + +**Realistic timeline:** +- Small site (10-20 pages): 2-3 months to remediate +- Medium site (50-100 pages): 4-6 months to remediate +- Large site (100+ pages or complex functionality): 6-12 months to remediate +- Enterprise site or platform: 12-18 months to remediate + +**Start now if you haven't already.** June 28, 2025 is a hard deadline. + +--- + +## Enforcement and Penalties + +### How EAA Is Enforced + +EAA is enforced at **national level** by member states: +- Each EU country designates national enforcement authority +- Enforcement varies by country (different fines, procedures, complaint processes) +- Penalties determined by national law, not EAA directly + +### Potential Penalties + +While specific penalties vary by member state, expect: + +**Financial penalties:** +- Fines for non-compliance (varies by country, can be substantial) +- Daily fines until compliance achieved +- Legal costs if sued by users or advocacy groups + +**Business consequences:** +- Product/service removal from market until compliant +- Reputational damage +- Loss of customer trust +- Exclusion from public procurement +- Legal liability for discrimination + +**Examples from member states:** +- **Germany:** Fines up to €100,000+ for serious violations +- **France:** Fines up to 4% of annual turnover under certain circumstances +- **Italy:** Fines ranging from €5,000 to €50,000+ depending on severity + +### Complaint Process + +Users can file complaints: +1. User encounters inaccessible product/service +2. User files complaint with national authority or company +3. Investigation by enforcement authority +4. Company given opportunity to remediate +5. If non-compliant: penalties, forced remediation, product removal + +### Litigation Risk + +Beyond regulatory enforcement: +- **Civil lawsuits:** Individuals or groups can sue for discrimination +- **Class actions:** Multiple users collectively sue +- **Advocacy organization complaints:** NGOs advocating for disability rights may file complaints + +**Bottom line:** Cost of compliance << Cost of non-compliance + penalties + litigation + reputation damage + +--- + +## Relationship Between EAA, WCAG, and Other Standards + +### Standard Hierarchy + +``` +European Accessibility Act (EAA) + ↓ references +EN 301 549 v3.2.1 (European ICT Accessibility Standard) + ↓ incorporates +WCAG 2.1 Level AA (W3C Web Content Accessibility Guidelines) + ↓ updated to +WCAG 2.2 Level AA (Recommended for future-proofing) +``` + +### Other Related Legislation + +#### Web Accessibility Directive (WAD) +- Directive (EU) 2016/2102 +- Applies to: **Public sector** websites and mobile apps +- Requirement: WCAG 2.1 Level AA +- Deadline: Already in effect (2018-2020) +- Different from EAA: WAD = public sector, EAA = private sector + +#### ADA (United States) +- Americans with Disabilities Act +- Not EU law, but relevant for global companies +- Requirement: Generally interpreted as WCAG 2.1 Level AA +- Enforcement: DOJ, private lawsuits (very active) +- If serving both US and EU: Compliance with WCAG 2.2 AA satisfies both + +#### UK Equality Act 2010 +- UK law (post-Brexit) +- Requirement: Reasonable adjustments, generally WCAG 2.1 AA +- Applies to UK businesses +- Separate from EAA but similar requirements + +#### AODA (Canada - Ontario) +- Accessibility for Ontarians with Disabilities Act +- Requirement: WCAG 2.0 Level AA (updating to 2.1) +- Applies to Ontario businesses + +### Global Compliance Strategy + +If operating globally: +- **Implement WCAG 2.2 Level AA** as baseline +- Satisfies: EAA, WAD, ADA, UK Equality Act, AODA, and most other jurisdictions +- Future-proof: WCAG 2.2 is latest standard +- Simplifies: Single standard easier than tracking multiple requirements + +--- + +## Steps to Achieve EAA Compliance + +### 1. Determine Applicability (1 week) + +**Questions to answer:** +- Do we have ≥10 employees OR ≥€2M revenue? +- Do we provide products/services to EU consumers? +- Are our products/services in EAA scope (e-commerce, banking, e-books, etc.)? +- Can we claim microenterprise exemption? + +**If YES to first 3 questions and NO to exemption → EAA applies to you.** + +### 2. Conduct Accessibility Audit (2-4 weeks) + +**Automated testing:** +- Run tools like axe DevTools, WAVE, or automated scripts +- Identifies ~30-40% of issues +- Quick way to find common problems + +**Manual testing:** +- Keyboard navigation +- Screen reader testing +- Zoom and reflow testing +- Form interaction testing +- Color contrast verification + +**Deliverable:** Accessibility audit report with categorized violations + +### 3. Prioritize and Plan Remediation (1-2 weeks) + +**Categorize issues:** +- **Critical:** Complete blockers (keyboard traps, unlabeled forms, missing alt text on key images) +- **High:** Major barriers (insufficient contrast, missing focus indicators, inaccessible modals) +- **Medium:** Partial barriers (generic link text, minor contrast issues, missing autocomplete) +- **Low:** Minor issues (heading structure improvements, language attributes) + +**Create roadmap:** +- Phase 1: Critical issues (weeks 1-4) +- Phase 2: High priority (weeks 5-10) +- Phase 3: Medium priority (weeks 11-16) +- Phase 4: Low priority and polish (weeks 17-20) + +### 4. Implement Fixes (2-6 months depending on scope) + +**Development priorities:** +- Fix code (HTML, CSS, JavaScript) +- Add ARIA where semantic HTML insufficient +- Provide text alternatives (alt text, captions, transcripts) +- Improve color contrast +- Implement keyboard support +- Test as you go + +**Resources needed:** +- Front-end developers (most issues are front-end) +- UX designers (for redesigns if needed) +- Content editors (for alt text, captions) +- QA testers (for validation) +- Accessibility specialist (consultant or hire) + +### 5. Re-Audit and Validate (2-4 weeks) + +**Internal validation:** +- Re-run automated tests +- Re-test manually +- Test with real assistive technologies +- User testing with people with disabilities (highly recommended) + +**External validation (optional but recommended):** +- Third-party accessibility audit +- WCAG 2.2 Level AA conformance testing +- Certification (not required but valuable) + +### 6. Maintain Compliance (Ongoing) + +**Establish processes:** +- Accessibility checklist for new features +- Automated testing in CI/CD pipeline +- Regular manual audits (quarterly or bi-annually) +- Training for developers, designers, content creators +- Accessibility champions within teams + +**Monitor for regressions:** +- New features can introduce new issues +- Design system updates may affect accessibility +- Third-party components may not be accessible + +--- + +## Claiming Exemptions (Use Carefully) + +### Disproportionate Burden + +You may claim **disproportionate burden** if compliance would impose an excessive organizational or financial burden. + +**Criteria:** +- Size and resources of organization +- Estimated costs of compliance +- Estimated benefits of compliance +- Frequency of use of product/service + +**Requirements if claiming:** +- **Document** the assessment in detail +- Provide **partial compliance** where possible +- Provide **alternative means** of access (e.g., phone support if web not accessible) +- Reassess periodically (burden may decrease over time) + +**Warning:** Disproportionate burden is **not a blanket exemption**. Must be justified case-by-case and documented. Enforcement authorities will scrutinize these claims. + +### Fundamental Alteration + +Claim if accessibility would **fundamentally alter** the nature of the product/service. + +**Example:** Accessibility requirement for a visual art app to describe paintings to blind users might fundamentally alter the service. + +**Requirements:** +- Document why it's a fundamental alteration +- Provide alternatives where possible +- This is a narrow exception, rarely applicable to standard websites/apps + +### Microenterprise Exemption + +**Automatic exemption if:** +- **<10 employees**, AND +- **<€2M annual turnover or balance sheet** + +**Recommendation:** Even if exempt, implement accessibility best practices: +1. You may grow beyond exemption threshold +2. Accessibility improves UX for all users +3. Opens market to people with disabilities (~15% of population) +4. May be required by customers (B2B contracts) + +--- + +## Documentation and Conformance Statements + +### Accessibility Statement (Recommended) + +While not strictly required by EAA, **accessibility statements** are best practice and may be required by some national implementations. + +**Include:** +- Commitment to accessibility +- Standard met (WCAG 2.2 Level AA) +- Known issues and workarounds +- Contact method for accessibility feedback +- Date of last audit +- Complaints process + +**Example:** +```markdown +# Accessibility Statement + +[Company Name] is committed to ensuring digital accessibility for people with disabilities. We are continually improving the user experience for everyone and applying the relevant accessibility standards. + +## Conformance Status +The Web Content Accessibility Guidelines (WCAG) define requirements for designers and developers to improve accessibility for people with disabilities. This website is **partially conformant** with WCAG 2.2 Level AA. Partially conformant means that some parts of the content do not fully conform to the accessibility standard. + +## Known Issues +We are aware of the following accessibility issues and are working to address them: +- [Issue 1]: [Description and expected resolution date] +- [Issue 2]: [Description and expected resolution date] + +## Feedback +We welcome your feedback on the accessibility of [website]. Please contact us: +- Email: accessibility@example.com +- Phone: +XX XXX XXXX + +We aim to respond to accessibility feedback within 5 business days. + +## Enforcement Procedure +If you are not satisfied with our response, you may contact [National Enforcement Authority]. + +Last updated: [Date] +``` + +### Voluntary Product Accessibility Template (VPAT) + +**VPAT** (now called "Accessibility Conformance Report") is standardized format for documenting accessibility conformance. + +**Sections:** +- Product information +- WCAG 2.x conformance (Level A, AA, AAA) +- Success criteria met/partially met/not met +- Explanations and remediation plans + +**Use cases:** +- Required for US government procurement (Section 508) +- Requested by large enterprise customers +- Demonstrates due diligence +- Useful for B2B sales + +**Not required by EAA, but valuable for compliance documentation.** + +--- + +## Resources and Tools + +### Official EAA Resources +- **EU EAA Directive:** https://eur-lex.europa.eu/eli/dir/2019/882/oj +- **European Commission EAA Page:** https://ec.europa.eu/social/main.jsp?catId=1202 +- **EN 301 549 Standard:** https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf + +### WCAG Resources +- **WCAG 2.2 Quick Reference:** https://www.w3.org/WAI/WCAG22/quickref/ +- **WCAG 2.2 Understanding Docs:** https://www.w3.org/WAI/WCAG22/Understanding/ +- **How to Meet WCAG:** https://www.w3.org/WAI/WCAG22/quickref/ + +### Testing Tools +- **axe DevTools:** https://www.deque.com/axe/devtools/ +- **WAVE:** https://wave.webaim.org/ +- **WebAIM Contrast Checker:** https://webaim.org/resources/contrastchecker/ +- **NVDA Screen Reader:** https://www.nvaccess.org/ + +### Organizations and Consultants +- **W3C Web Accessibility Initiative (WAI):** https://www.w3.org/WAI/ +- **WebAIM:** https://webaim.org/ +- **Deque Systems:** https://www.deque.com/ +- **TPGi (The Paciello Group):** https://www.tpgi.com/ + +--- + +## Summary Checklist + +- [ ] Determine if EAA applies to your organization +- [ ] Identify products/services in scope +- [ ] Conduct accessibility audit (automated + manual) +- [ ] Create remediation roadmap with timeline to June 2025 +- [ ] Allocate budget and resources +- [ ] Implement fixes targeting WCAG 2.2 Level AA +- [ ] Re-audit and validate compliance +- [ ] Document conformance (accessibility statement, VPAT if needed) +- [ ] Establish ongoing accessibility maintenance processes +- [ ] Train team on accessibility best practices +- [ ] Monitor enforcement developments in member states +- [ ] Consider user testing with people with disabilities + +**Remember:** EAA compliance deadline is June 28, 2025. Start now if you're in scope and haven't begun. The cost and time required should not be underestimated. + +--- + +**Last updated:** 2024 (informational purposes - verify current requirements with legal counsel and national authorities) diff --git a/.claude/skills/web-accessibility-checker/references/manual-testing-checklist.md b/.claude/skills/web-accessibility-checker/references/manual-testing-checklist.md new file mode 100644 index 000000000..077bc0206 --- /dev/null +++ b/.claude/skills/web-accessibility-checker/references/manual-testing-checklist.md @@ -0,0 +1,963 @@ +# Manual Accessibility Testing Checklist + +Automated tools catch only 30-40% of accessibility issues. This comprehensive manual testing checklist covers what automation cannot detect. + +**Estimated time:** 2-3 hours for thorough audit of a typical website + +--- + +## 1. Keyboard Navigation Testing (30-45 minutes) + +Keyboard navigation is critical - approximately 15% of users rely on keyboards exclusively. + +### Setup +- Close all browser extensions that might interfere +- Use latest Chrome, Firefox, or Safari +- Have DevTools open to inspect focus + +### Test Procedure + +#### 1.1 Tab Through Entire Page + +**Steps:** +1. Click in address bar +2. Press Tab repeatedly through entire page +3. Note every interactive element you land on +4. Continue until focus loops back to browser UI + +**What to verify:** +- ✅ All interactive elements receive focus (links, buttons, form fields, custom widgets) +- ✅ Focus order is logical (left-to-right, top-to-bottom in most cultures) +- ✅ Focus indicator is clearly visible at all times +- ✅ No keyboard traps (can always move forward) + +**Common issues:** +- Skip links not visible or not functional +- Interactive elements not reachable (`tabindex="-1"` on wrong elements) +- Tab order jumps around page illogically (CSS positioning vs. DOM order mismatch) +- Custom widgets (dropdowns, modals) not keyboard accessible + +**How to test focus visibility:** +``` +Tab to element → Can you clearly see where focus is? +- If barely visible: FAIL SC 2.4.7 +- If invisible: CRITICAL FAIL SC 2.4.7 +- Check contrast of focus indicator against background (3:1 minimum per SC 1.4.11) +``` + +#### 1.2 Shift+Tab Backward Navigation + +**Steps:** +1. Tab to middle of page +2. Press Shift+Tab to move backward +3. Verify focus moves in reverse order + +**What to verify:** +- ✅ Can navigate backward through all elements +- ✅ No elements skipped +- ✅ No keyboard traps + +#### 1.3 Test Interactive Components + +For each type of interactive component, verify keyboard support: + +**Links:** +- Tab to focus → Enter to activate +- Should navigate to destination + +**Buttons:** +- Tab to focus → Enter or Space to activate +- Should trigger action + +**Form fields:** +- Tab to focus → Type to enter text +- Arrow keys in dropdowns/radios +- Space to check/uncheck checkboxes + +**Custom dropdowns/comboboxes:** +- Tab to focus +- Enter or Space to open +- Arrow keys to navigate options +- Enter to select +- Escape to close + +**Modals/dialogs:** +- Opens when triggered (via keyboard) +- Focus moves into modal +- Tab cycles within modal only (focus trap) +- Escape closes modal +- Focus returns to trigger element when closed + +**Tabs:** +- Tab to tab list +- Arrow keys move between tabs (not Tab key) +- Enter or Space to activate tab +- Tab to move into tab panel + +**Accordions:** +- Tab to header +- Enter or Space to expand/collapse +- Arrow keys to move between headers (optional) +- Tab to move into expanded content + +**Carousels/sliders:** +- Tab to controls (prev/next buttons) +- Enter or Space to activate buttons +- Optionally: Left/Right arrows to navigate slides + +#### 1.4 Test Skip Links + +**Steps:** +1. Load page +2. Press Tab once +3. "Skip to main content" link should appear +4. Press Enter +5. Focus should jump to main content area + +**What to verify:** +- ✅ Skip link visible when focused +- ✅ Skip link actually works (focus moves to target) +- ✅ Multiple skip links if needed (skip to nav, skip to search, etc.) + +**Common issues:** +- Skip link visually hidden even when focused +- Skip link target doesn't exist or isn't focusable +- No skip link at all + +#### 1.5 Test Focus Management in SPAs + +For single-page applications: + +**Page changes:** +- When route changes, focus should move to appropriate location +- Ideally: move to page heading or main content +- Announce page change to screen readers + +**Dynamic content:** +- When content loads/changes, manage focus appropriately +- Example: After deleting item, focus moves to next item or list +- Don't leave focus on deleted element + +#### 1.6 No Mouse Testing + +**Challenge mode:** +1. Unplug mouse or disable trackpad +2. Try to complete primary user tasks using only keyboard +3. Can you do everything? + +**Tasks to test:** +- Fill out and submit a form +- Navigate to different pages +- Use search functionality +- Open and close modals +- Play/pause videos +- Submit a purchase (test environment) + +**If you can't complete a task with keyboard alone:** CRITICAL FAIL SC 2.1.1 + +--- + +## 2. Screen Reader Testing (45-60 minutes) + +Screen reader testing catches issues automation cannot. + +### Setup + +**Windows:** +- NVDA (free): https://www.nvaccess.org/download/ +- JAWS (paid, most popular): https://www.freedomscientific.com/products/software/jaws/ + +**macOS:** +- VoiceOver (built-in): Cmd+F5 to enable + +**Test with at least one screen reader.** If testing professionally, test with both NVDA and JAWS. + +### Basic Screen Reader Commands + +**NVDA/JAWS:** +- Start reading: Insert+Down arrow +- Stop reading: Ctrl +- Next item: Down arrow +- Previous item: Up arrow +- Next heading: H +- Next link: K (JAWS) or K (NVDA) +- Next form field: F +- Navigate by landmarks: D +- List all headings: Insert+F7 (NVDA), Insert+F6 (JAWS) +- List all links: Insert+F7, select Links tab + +**VoiceOver:** +- Start reading: VO+A (VO = Ctrl+Option) +- Stop reading: Ctrl +- Next item: VO+Right arrow +- Previous item: VO+Left arrow +- Rotor (navigation menu): VO+U + +### Test Procedure + +#### 2.1 Page Structure Test + +**Steps:** +1. Open page with screen reader +2. List all headings (Insert+F7 in NVDA) +3. Navigate through headings with H key + +**What to verify:** +- ✅ Page has h1 heading (only one) +- ✅ Heading hierarchy is logical (no skipped levels: h1→h2→h3, not h1→h3) +- ✅ Headings describe content accurately +- ✅ Major sections have headings + +**Common issues:** +- Multiple h1 elements +- Skipped heading levels (h1 → h3) +- Empty headings +- Headings used for styling, not structure + +#### 2.2 Landmark Navigation Test + +**Steps:** +1. Navigate by landmarks (D key in NVDA/JAWS, Rotor→Landmarks in VoiceOver) +2. Verify landmarks are announced + +**Expected landmarks:** +- Banner (header) +- Navigation (nav) +- Main (main content) +- Complementary (sidebar/aside) +- Contentinfo (footer) +- Search (if present) + +**How to check:** +```html + +
→ banner +