PixelPilot uiux-a11y-ci.instructions.md

Accessibility CI Skill

Automated accessibility testing in CI/CD pipeline using axe-core.

---

CORE PRINCIPLE

Rule: Every PR must pass accessibility checks. Fail on any Critical or Serious violation. Warn on Moderate/Minor.

---

GITHUB ACTION WORKFLOW

Basic Setup

# .github/workflows/a11y.yml
name: Accessibility Tests

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]
  # Manual trigger
  workflow_dispatch:
    inputs:
      url:
        description: 'URL to test'
        required: true
        type: string

jobs:
  a11y:
    runs-on: ubuntu-latest
    name: axe-core accessibility scan
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Start server
        run: |
          npm run preview &
          sleep 5
        env:
          PORT: 3000

      - name: Wait for server
        run: npx wait-on http://localhost:3000 --timeout 60000

      - name: Run axe-core tests
        id: axe
        run: |
          npx @axe-core/cli http://localhost:3000 \
            --exit \
            --tags wcag2a,wcag2aa,wcag21a,wcag21aa \
            --save results.json
        continue-on-error: true

      - name: Process results
        id: results
        run: |
          node << 'EOF'
          const fs = require('fs');
          const results = JSON.parse(fs.readFileSync('results.json', 'utf8'));
          
          let critical = 0, serious = 0, moderate = 0, minor = 0;
          const violations = [];
          
          results.forEach(page => {
            page.violations?.forEach(v => {
              const count = v.nodes.length;
              switch(v.impact) {
                case 'critical': critical += count; break;
                case 'serious': serious += count; break;
                case 'moderate': moderate += count; break;
                case 'minor': minor += count; break;
              }
              violations.push({
                impact: v.impact,
                description: v.description,
                help: v.help,
                helpUrl: v.helpUrl,
                count
              });
            });
          });
          
          // Generate summary
          const summary = `
          ## Accessibility Report
          
          | Severity | Count |
          |----------|-------|
          | 🔴 Critical | ${critical} |
          | 🟠 Serious | ${serious} |
          | 🟡 Moderate | ${moderate} |
          | 🔵 Minor | ${minor} |
          
          ${critical + serious > 0 ? '### ❌ FAILED — Fix critical/serious issues before merging' : '### ✅ PASSED'}
          
          ${violations.length > 0 ? '### Violations\n' + violations.slice(0, 10).map(v => 
            `- **[${v.impact.toUpperCase()}]** ${v.description} (${v.count} occurrences)\n  - ${v.help}\n  - [Learn more](${v.helpUrl})`
          ).join('\n') : ''}
          `;
          
          fs.writeFileSync('summary.md', summary);
          
          // Set outputs
          const core = require('@actions/core');
          core.setOutput('critical', critical);
          core.setOutput('serious', serious);
          core.setOutput('passed', critical + serious === 0);
          
          console.log(summary);
          EOF

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const summary = fs.readFileSync('summary.md', 'utf8');
            
            // Find existing comment
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });
            
            const botComment = comments.find(c => 
              c.user.type === 'Bot' && c.body.includes('Accessibility Report')
            );
            
            if (botComment) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: botComment.id,
                body: summary
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: summary
              });
            }

      - name: Fail on critical/serious
        if: steps.results.outputs.passed == 'false'
        run: |
          echo "❌ Accessibility check failed"
          echo "Critical: ${{ steps.results.outputs.critical }}"
          echo "Serious: ${{ steps.results.outputs.serious }}"
          exit 1