WCAG 2.1 AA Accessibility Audit Skill

This skill provides comprehensive instructions for running automated WCAG 2.1 AA accessibility audits on web applications. It uses the wcag-ci-audit.js script which leverages Puppeteer and axe-core to test all application routes for accessibility compliance.

Introduction

WCAG (Web Content Accessibility Guidelines) 2.1 AA is an international standard for web accessibility. Compliance ensures that web applications are usable by people with disabilities, including those using screen readers, keyboard navigation, or other assistive technologies.

This skill enables automated testing of your application’s accessibility by:

• Extracting routes from your React Router configuration
• Testing each route with axe-core accessibility engine
• Reporting violations with specific rule IDs and remediation guidance
• Providing exit codes suitable for CI/CD integration

When to Use

Use this skill in the following scenarios:

• Before deploying to production – Ensure accessibility compliance before release
• During accessibility reviews – Regular audits as part of development workflow
• In CI/CD pipelines – Automated accessibility checks on every commit or PR
• When making UI changes – Verify new components and pages meet standards
• Before compliance audits – Prepare for formal accessibility assessments
• After dependency updates – Ensure UI library updates don’t introduce violations

Prerequisites

Before running the WCAG audit, ensure the following are in place:

Required Software

1. Node.js – Version 14 or higher (check with node --version)
2. Chrome/Chromium Browser – Required for Puppeteer
   • Puppeteer can install Chrome automatically, or you can use an existing installation
   • Set PUPPETEER_EXECUTABLE_PATH if Chrome is in a non-standard location

Required Dependencies

The following npm packages must be installed (check package.json):

• puppeteer: ^24.15.0 or compatible version
• axe-core: ^4.10.2 or compatible version

Install missing dependencies:

npm install --save-dev puppeteer axe-core

Required Files

1. wcag-ci-audit.js – The audit script must exist in the project root
2. src/App.tsx – React Router configuration file for route extraction
   • Must contain <Route> components from react-router-dom
   • Script extracts path attributes from Route components

Application State

• Frontend application must be running (default: http://localhost:8080)
  • The audit script needs a live application to test
  • Start your dev server before running the audit
  • Use AUDIT_URL environment variable to specify a different URL

How to Run

Option 1: Using NPM Script (Recommended)

If your package.json includes the audit script:

npm run audit:wcag

Option 2: Direct Execution

Run the script directly with Node.js:

node wcag-ci-audit.js

Option 3: With Environment Variables

Customize the audit behavior with environment variables:

AUDIT_URL=http://localhost:3000 APP_FILE=src/routes.tsx node wcag-ci-audit.js

Configuration Options

The audit script supports the following environment variables:

AUDIT_URL

• Default: http://localhost:8080
• Description: Base URL of the application to audit
• Example: AUDIT_URL=http://localhost:3000 node wcag-ci-audit.js
• Use case: Testing staging or production environments

APP_FILE

• Default: src/App.tsx
• Description: Path to the file containing React Router Route components
• Example: APP_FILE=src/routes/index.tsx node wcag-ci-audit.js
• Use case: Projects with non-standard route file locations

SKIP_DYNAMIC_ROUTES

• Default: true (skips routes with parameters like :id)
• Description: Whether to skip dynamic routes during audit
• Set to false: SKIP_DYNAMIC_ROUTES=false node wcag-ci-audit.js
• Note: Dynamic routes are replaced with placeholder values (e.g., /users/:id → /users/test-id)

SKIP_CATCH_ALL

• Default: true (skips catch-all routes like *)
• Description: Whether to skip catch-all/404 routes
• Set to false: SKIP_CATCH_ALL=false node wcag-ci-audit.js

PUPPETEER_EXECUTABLE_PATH

• Default: Auto-detected from common installation paths
• Description: Custom path to Chrome/Chromium executable
• Example: PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser node wcag-ci-audit.js
• Use case: Custom Chrome installations or CI environments

Instructions for the Agent

When the user requests a WCAG audit, follow this workflow:

Step 1: Pre-flight Checks

Before running the audit, verify:

1. Script Exists: Check that wcag-ci-audit.js is present in the project root

   test -f wcag-ci-audit.js || ls wcag-ci-audit.js
   

2. Route File Exists: Verify src/App.tsx (or configured APP_FILE) exists

   test -f src/App.tsx || ls src/App.tsx
   

3. Dependencies Installed: Check package.json for puppeteer and axe-core

   • If missing, suggest: npm install --save-dev puppeteer axe-core

4. Frontend Running (if testing localhost):

   • Check if dev server is running on the configured port
   • If not, inform user they need to start the application first
   • Suggest: npm run dev or appropriate start command

5. Chrome Available (optional check):

   • Script will attempt to find Chrome automatically
   • If issues occur, suggest: npx puppeteer browsers install chrome

Step 2: Execution

Run the audit script:

npm run audit:wcag

Or directly:

node wcag-ci-audit.js

Monitor the output for:

• Route extraction success/failure
• Each page being audited
• Violation reports per page
• Final summary statistics

Step 3: Post-execution Analysis

After the audit completes:

1. Check Exit Code:

   • 0 = All pages passed (no violations)
   • 1 = Violations found or errors occurred

2. Summarize Results:

   • Total routes found
   • Pages successfully audited
   • Total violations count
   • Pages with violations

3. Provide Actionable Feedback:

   • List violation types found
   • Reference specific rule IDs (e.g., color-contrast, aria-required-attr)
   • Suggest priority fixes (critical violations first)
   • Link to axe-core documentation for detailed remediation

4. Next Steps:

   • If violations found: Provide guidance on fixing common issues
   • If audit passed: Confirm compliance and suggest periodic re-auditing
   • For CI/CD: Explain how to integrate into pipeline

Step 4: Error Handling

Handle common errors appropriately:

Browser Launch Failures:

• Error: “Failed to launch browser”
• Solution: Install Chrome via npx puppeteer browsers install chrome
• Alternative: Set PUPPETEER_EXECUTABLE_PATH to existing Chrome installation

Route Extraction Failures:

• Error: “Could not parse [APP_FILE]”
• Solution: Verify file exists and contains valid React Router <Route> components
• Check: File path matches APP_FILE environment variable

Network/Connection Errors:

• Error: “Failed to audit [URL]”
• Solution: Verify frontend application is running
• Check: AUDIT_URL matches actual application URL
• Verify: No firewall or network restrictions

Timeout Errors:

• Error: Page load timeout
• Solution: Application may be slow to load
• Consider: Increasing timeout in script (requires script modification)

Authentication Required:

• Observation: Pages redirect to login
• Note: This is expected for protected routes
• Consider: Providing test credentials or bypassing auth for audit

Troubleshooting

Browser Launch Issues

Problem: Script fails with “Failed to launch browser”

Solutions:

1. Install Chrome via Puppeteer:

   npx puppeteer browsers install chrome
   

2. Use existing Chrome installation:

   export PUPPETEER_EXECUTABLE_PATH="/path/to/chrome"
   node wcag-ci-audit.js
   

3. On Linux CI environments, may need:

   apt-get install -y chromium-browser
   export PUPPETEER_EXECUTABLE_PATH="/usr/bin/chromium-browser"
   

Route Extraction Issues

Problem: “No routes found” or “Could not parse [file]”

Solutions:

1. Verify src/App.tsx exists and contains Route components
2. Check file format – must use JSX/TSX with <Route path="..."> syntax
3. If routes are in a different file, set APP_FILE environment variable
4. Ensure React Router v6 syntax (not v5 or earlier)

Application Not Running

Problem: All pages fail with connection errors

Solutions:

1. Start the development server:

   npm run dev
   

2. Verify the URL matches AUDIT_URL (default: http://localhost:8080)

3. Check if application is running on a different port

4. For production/staging, set AUDIT_URL to the correct domain

Authentication-Required Pages

Problem: Pages redirect to login or show authentication errors

Solutions:

1. This is expected behavior for protected routes
2. Consider creating a test user account for auditing
3. Some violations may still be detectable on login pages
4. For comprehensive testing, provide authentication credentials (requires script modification)

Missing Dependencies

Problem: “Cannot find module ‘puppeteer'” or “Cannot find module ‘axe-core'”

Solutions:

1. Install missing dependencies:

   npm install --save-dev puppeteer axe-core
   

2. Verify package.json includes these in devDependencies

3. Run npm install to ensure all dependencies are installed

Dynamic Routes Not Tested

Problem: Dynamic routes (with :id) are skipped

Solutions:

1. This is default behavior to avoid testing invalid URLs
2. To include dynamic routes:

   SKIP_DYNAMIC_ROUTES=false node wcag-ci-audit.js
   

3. Note: Dynamic routes will use placeholder values (e.g., test-id)

Understanding Results

Exit Codes

• 0: Audit completed successfully with no violations
• 1: Violations found or errors occurred during audit

Output Format

The audit provides:

1. Route Extraction: Lists all routes found in App.tsx
2. Per-Page Results: For each route:
   • Success/failure status
   • Number of violations (if any)
   • Violation details with rule IDs
3. Summary: Total statistics including:
   • Routes found
   • Pages audited
   • Pages skipped (errors)
   • Total violations

Violation Information

Each violation includes:

• Rule ID: Unique identifier (e.g., color-contrast, aria-required-attr)
• Description: Human-readable explanation (help field)
• Impact: Severity level (critical, serious, moderate, minor)
• Affected Elements: Count of DOM nodes with the violation

Common Violation Types

Color Contrast (color-contrast):

• Text doesn’t meet minimum contrast ratios
• Fix: Adjust text/background colors to meet WCAG AA (4.5:1 for normal text, 3:1 for large text)

ARIA Attributes (aria-required-attr, aria-valid-attr):

• Missing or invalid ARIA attributes
• Fix: Add proper ARIA labels, roles, and properties

Keyboard Navigation (keyboard, focus-order-semantics):

• Elements not keyboard accessible
• Fix: Ensure all interactive elements are focusable and have logical tab order

Image Alt Text (image-alt):

• Images missing alternative text
• Fix: Add descriptive alt attributes to all images

Heading Structure (heading-order, page-has-heading-one):

• Incorrect heading hierarchy
• Fix: Use proper h1-h6 hierarchy, one h1 per page

CI/CD Integration

GitHub Actions

Example workflow for running WCAG audits on every PR:

name: WCAG Accessibility Audit

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  wcag-audit:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build application
        run: npm run build
      
      - name: Start application
        run: |
          npm run preview &
          sleep 10
        env:
          PORT: 8080
      
      - name: Run WCAG audit
        run: npm run audit:wcag
        env:
          AUDIT_URL: http://localhost:8080
          SKIP_DYNAMIC_ROUTES: false

GitLab CI

Example .gitlab-ci.yml configuration:

wcag-audit:
  stage: test
  image: node:18
  
  before_script:
    - npm ci
    - npm run build
    - npm run preview &
    - sleep 10
  
  script:
    - npm run audit:wcag
  environment:
    AUDIT_URL: http://localhost:8080
  
  artifacts:
    when: always
    reports:
      junit: wcag-report.xml
    expire_in: 1 week

Exit Code Handling

Both CI systems will fail the build if the audit script exits with code 1:

• Success (exit 0): Build continues
• Failure (exit 1): Build fails, PR cannot be merged

To allow warnings without failing builds, you would need to modify the script to differentiate between errors and violations.

Best Practices

When to Run Audits

1. Before Committing UI Changes: Catch violations early
2. In Pre-commit Hooks: Automate accessibility checks
3. In CI/CD Pipeline: Prevent violations from reaching production
4. Before Major Releases: Comprehensive accessibility review
5. After Dependency Updates: Ensure UI libraries don’t introduce violations

Fixing Violations Systematically

1. Prioritize by Impact:

   • Critical violations first (blocking keyboard navigation, missing alt text)
   • Serious violations next (color contrast, ARIA issues)
   • Moderate/minor violations last

2. Fix by Component:

   • Group violations by component or page
   • Fix all violations in one component before moving to the next

3. Test Incrementally:

   • Run audit after fixing each major violation type
   • Verify fixes don’t introduce new violations

4. Document Exceptions:

   • If a violation cannot be fixed (e.g., third-party component), document why
   • Consider alternative solutions or workarounds

Manual Testing Recommendations

Automated testing catches many issues, but manual testing is also important:

1. Screen Reader Testing: Test with NVDA, JAWS, or VoiceOver
2. Keyboard Navigation: Navigate entire application using only keyboard
3. Browser Zoom: Test at 200% zoom level
4. High Contrast Mode: Verify readability in high contrast mode
5. Color Blindness: Use simulators to check color-dependent information

Integration with Development Workflow

1. Pre-commit Hooks: Run quick audits before commits
2. PR Requirements: Make WCAG audit passing a PR requirement
3. Regular Full Audits: Schedule comprehensive audits monthly or quarterly
4. Accessibility Training: Educate team on common violations and fixes

Additional Resources

• WCAG 2.1 Guidelines
• axe-core Documentation
• Puppeteer Documentation
• WebAIM Contrast Checker
• WAVE Browser Extension