a11y-ally

name	a11y-ally
description	Use when running comprehensive WCAG accessibility audits with axe-core + pa11y + Lighthouse, generating context-aware remediation, or testing video accessibility. Supports 3-tier browser cascade with graceful degradation.
category	specialized-testing
priority	critical
tokenEstimate	10000
agents	[]
implementation_status	active
optimization_version	7
last_optimized	"2026-01-26T00:00:00.000Z"
dependencies	["playwright","playwright-extra","puppeteer-extra-plugin-stealth","@axe-core/playwright","pa11y","lighthouse"]
quick_reference_card	true
tags	["accessibility","wcag","a11y","video","captions","audiodesc","vtt","eu-compliance","context-aware","remediation","axe-core","pa11y","lighthouse","parallel","resilient","graceful-degradation","retry"]
trust_tier	3
validation	{"schema_path":"schemas/output.json","validator_path":"scripts/validate-config.json","eval_path":"evals/a11y-ally.yaml"}

/a11y-ally - Comprehensive Accessibility Audit

<default_to_action> When this skill is invoked with a URL, Claude executes ALL steps automatically without waiting for user prompts between steps.

THIS IS AN LLM-POWERED SKILL

The value of this skill is Claude's intelligence, not just running automated tools:

Automated Tools Do	Claude (This Skill) Does
Flag "button has no name"	Analyze context: icon class, parent element, nearby text → generate "Add to wishlist"
Flag "image missing alt"	Use Vision to see the image → describe actual content
Flag "video has no captions"	Download video, extract frames, analyze each frame with Vision → generate real captions
Output generic templates	Generate context-specific, copy-paste ready fixes

IF YOU SKIP THE LLM ANALYSIS, THIS SKILL HAS NO VALUE.

---

EXECUTION MODEL

CLAUDE EXECUTES ALL STEPS WITHOUT STOPPING.

Do NOT wait for user prompts between steps. Execute the full pipeline:

1. Data Collection: Run multi-tool scan (axe-core, pa11y, Lighthouse) via Bash
2. LLM Analysis: Read results and analyze context for each violation
3. Vision Pipeline: If videos detected → download → extract frames → Read each frame → describe
4. Intelligent Remediation: Generate context-specific fixes using your reasoning
5. Generate Reports: Write all output files to docs/accessibility-scans/{page-slug}/

WRONG:

Claude: "I found 5 violations. Should I analyze them?"
User: "Yes"
Claude: "I see a video. Should I run the video pipeline?"
User: "Yes"

RIGHT:

Claude: [Runs scan] → [Analyzes violations] → [Downloads video] → [Extracts frames] →
        [Reads each frame with Vision] → [Generates captions] → [Writes all files]
        "Audit complete. Generated 4 files in docs/accessibility-scans/example/"

---

STEP 1: BROWSER AUTOMATION - Content Fetching

Uses the qe-browser fleet skill as the browser engine. qe-browser wraps Vibium (WebDriver BiDi, 10MB Go binary) and provides the QE primitives we rely on. See .claude/skills/qe-browser/SKILL.md.

1.1: PRIMARY — qe-browser via Vibium CLI

# Navigate
vibium go "$TARGET_URL"
vibium wait load

# Capture accessibility tree without visual render
vibium a11y-tree --json > /tmp/a11y-work/tree.json

# Screenshot for Vision pipeline
vibium screenshot -o /tmp/a11y-work/page.png --full-page

If Vibium MCP tools are registered (mcp__vibium__*), prefer them; otherwise shell out to the vibium binary installed by aqe init.

1.2: Run axe-core + WCAG assertions via qe-browser

# Inject axe-core via vibium eval and collect violations
vibium eval --stdin <<'EOF'
const s = document.createElement('script');
s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js';
document.head.appendChild(s);
await new Promise(r => s.onload = r);
const results = await axe.run();
JSON.stringify({ violations: results.violations.length, issues: results.violations });
EOF

# Enforce: no critical a11y violations + no failed network requests
node .claude/skills/qe-browser/scripts/assert.js --checks '[
  {"kind": "no_console_errors"},
  {"kind": "no_failed_requests"},
  {"kind": "selector_visible", "selector": "main, [role=main]"}
]'

1.3: FALLBACK — pa11y + Lighthouse (when axe alone is insufficient)

# Only use when you need the extra rulesets, not as the primary path
pa11y "$TARGET_URL" --reporter json > /tmp/a11y-work/pa11y.json
lighthouse "$TARGET_URL" --only-categories=accessibility --output=json --output-path=/tmp/a11y-work/lighthouse.json --chrome-flags="--headless"

Why we dropped playwright-extra + puppeteer-extra-plugin-stealth from the primary path:

• 300MB+ of Node deps vs Vibium's 10MB binary
• Redundant: Vibium uses WebDriver BiDi which is less fingerprintable than raw CDP
• Simpler: one tool instead of a cascade

1d: PARALLEL MULTI-PAGE AUDIT (Optional)

For auditing multiple URLs simultaneously, use parallel execution:

// /tmp/a11y-work/parallel-audit.js
const { chromium } = require('playwright-extra');
const stealth = require('puppeteer-extra-plugin-stealth')();
const { AxeBuilder } = require('@axe-core/playwright');

chromium.use(stealth);

const MAX_CONCURRENT = 6;  // Maximum parallel auditors

async function auditUrl(browser, url) {
  const context = await browser.newContext();
  const page = await context.newPage();

  try {
    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
    await page.waitForTimeout(2000);

    const axeResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
      .analyze();

    return { url, success: true, violations: axeResults.violations };
  } catch (error) {
    return { url, success: false, error: error.message };
  } finally {
    await context.close();
  }
}

async function parallelAudit(urls) {
  const browser = await chromium.launch({ headless: true });
  const results = [];

  // Process in chunks of MAX_CONCURRENT
  for (let i = 0; i < urls.length; i += MAX_CONCURRENT) {
    const chunk = urls.slice(i, i + MAX_CONCURRENT);
    console.log(`Auditing batch ${Math.floor(i/MAX_CONCURRENT) + 1}: ${chunk.length} URLs`);

    const chunkResults = await Promise.all(
      chunk.map(url => auditUrl(browser, url))
    );
    results.push(...chunkResults);
  }

  await browser.close();
  return results;
}

// Usage: node parallel-audit.js url1 url2 url3 ...
const urls = process.argv.slice(2);
if (urls.length > 0) {
  parallelAudit(urls).then(results => {
    console.log(JSON.stringify(results, null, 2));
  });
}

Usage for multi-page audit:

node parallel-audit.js https://example.com https://example.com/about https://example.com/contact

1e: SITE CRAWL MODE (Optional)

For comprehensive site audits, crawl and audit all pages:

// /tmp/a11y-work/crawl-audit.js
async function crawlAndAudit(startUrl, maxPages = 50) {
  const browser = await chromium.launch({ headless: true });
  const visited = new Set();
  const toVisit = [startUrl];
  const results = [];
  const baseUrl = new URL(startUrl).origin;

  while (toVisit.length > 0 && results.length < maxPages) {
    const url = toVisit.shift();
    if (visited.has(url)) continue;
    visited.add(url);

    console.log(`[${results.length + 1}/${maxPages}] Auditing: ${url}`);

    const context = await browser.newContext();
    const page = await context.newPage();

    try {
      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });

      // Extract same-domain links for crawling
      const links = await page.evaluate((base) => {
        return [...document.querySelectorAll('a[href]')]
          .map(a => a.href)
          .filter(href => href.startsWith(base) && !href.includes('#'))
          .filter(href => !href.match(/\.(pdf|jpg|png|gif|css|js)$/i));
      }, baseUrl);

      // Add new links to queue
      links.forEach(link => {
        if (!visited.has(link) && !toVisit.includes(link)) {
          toVisit.push(link);
        }
      });

      // Run accessibility audit
      const axeResults = await new AxeBuilder({ page })
        .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
        .analyze();

      results.push({ url, violations: axeResults.violations });
    } catch (e) {
      results.push({ url, error: e.message });
    }

    await context.close();
  }

  await browser.close();
  return { pagesAudited: results.length, results };
}

// Usage: node crawl-audit.js https://example.com 50
const [startUrl, maxPages] = process.argv.slice(2);
crawlAndAudit(startUrl, parseInt(maxPages) || 50).then(r => console.log(JSON.stringify(r, null, 2)));

---

STEP 2: COMPREHENSIVE WCAG SCAN (Multi-Tool, Parallel, Resilient)

IMPORTANT: This step uses THREE accessibility testing tools for maximum coverage:

• axe-core: Industry standard, excellent for ARIA and semantic issues
• pa11y: Strong on contrast, links, and HTML validation
• Lighthouse: Google's accessibility scoring with performance correlation

Combined detection rate is ~15% higher than any single tool.

2.0: RESILIENCE ARCHITECTURE (v7.0 Enhancement)

Key improvements over v6.0:

Feature	v6.0 (Old)	v7.0 (New)
Tool execution	Sequential	Parallel (Promise.allSettled)
Timeout handling	Global 60s	Per-tool (60s/60s/90s)
Failure mode	All-or-nothing	Graceful degradation
Retry logic	None	Exponential backoff (3 retries)
Output style	Wait for all	Progressive (stream as ready)
Minimum tools	3 required	1 of 3 sufficient

Coverage by tools succeeded:

• 3/3 tools: ~95% detection (optimal)
• 2/3 tools: ~85% detection (good)
• 1/3 tools: ~70% detection (acceptable)
• 0/3 tools: FAIL - retry with different strategy

2.1: Run Multi-Tool Analysis (PARALLEL + RESILIENT)

Create and run /tmp/a11y-work/multi-tool-scan.js:

const { chromium } = require('playwright-extra');
const stealth = require('puppeteer-extra-plugin-stealth')();
const { AxeBuilder } = require('@axe-core/playwright');
const pa11y = require('pa11y');
const lighthouse = require('lighthouse').default || require('lighthouse');
const { launch: launchChrome } = require('chrome-launcher');
const fs = require('fs');

chromium.use(stealth);

const TARGET_URL = process.argv[2] || 'TARGET_URL';
const OUTPUT_FILE = '/tmp/a11y-work/scan-results.json';
const SYSTEM_CHROMIUM = '/usr/bin/chromium';

// ========== RESILIENCE UTILITIES ==========

// Timeout wrapper - wraps any promise with a timeout
function withTimeout(promise, ms, name) {
  return Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error(`${name} timed out after ${ms}ms`)), ms)
    )
  ]);
}

// Retry wrapper - retries with exponential backoff
async function withRetry(fn, name, maxRetries = 3, baseDelay = 2000) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isLastAttempt = attempt === maxRetries;
      console.log(`[${name}] Attempt ${attempt}/${maxRetries} failed: ${error.message}`);
      if (isLastAttempt) throw error;
      const delay = baseDelay * Math.pow(2, attempt - 1); // Exponential backoff
      console.log(`[${name}] Retrying in ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

// Sleep utility
const sleep = (ms) => new Promise(r => setTimeout(r, ms));

// Progressive output - append results as they arrive
function progressiveOutput(tool, data) {
  console.log(`\n=== ${tool.toUpperCase()} COMPLETE ===`);
  console.log(JSON.stringify(data, null, 2));

  // Append to results file for progressive access
  try {
    let results = {};
    if (fs.existsSync(OUTPUT_FILE)) {
      results = JSON.parse(fs.readFileSync(OUTPUT_FILE, 'utf8'));
    }
    results[tool] = data;
    results.lastUpdated = new Date().toISOString();
    fs.writeFileSync(OUTPUT_FILE, JSON.stringify(results, null, 2));
  } catch (e) { /* ignore file errors */ }
}

// ========== TOOL RUNNERS ==========

// TOOL 1: Axe-core (with page info extraction)
async function runAxeCore(url) {
  console.log('[axe-core] Starting...');
  const browser = await chromium.launch({
    headless: true,
    executablePath: SYSTEM_CHROMIUM,
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-blink-features=AutomationControlled'
    ]
  });

  const context = await browser.newContext({
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    locale: 'en-US',
    viewport: { width: 1920, height: 1080 }
  });

  const page = await context.newPage();

  try {
    // Use domcontentloaded (faster, more reliable than networkidle)
    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });

    // Random delay to appear human
    await sleep(2000 + Math.random() * 2000);

    // Try to dismiss cookie banners
    try {
      const cookieSelectors = [
        'button:has-text("Accept")', 'button:has-text("Akzeptieren")',
        'button:has-text("Alle akzeptieren")', '[data-testid="cookie-accept"]',
        '#onetrust-accept-btn-handler', '.cookie-consent-accept'
      ];
      for (const selector of cookieSelectors) {
        const btn = await page.$(selector);
        if (btn) { await btn.click(); await sleep(500); break; }
      }
    } catch (e) { /* ignore cookie errors */ }

    // Run axe-core analysis
    const axeResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
      .analyze();

    // Extract comprehensive page info
    const pageInfo = await page.evaluate(() => ({
      title: document.title,
      url: window.location.href,
      lang: document.documentElement.lang,
      images: {
        total: document.querySelectorAll('img').length,
        withAlt: document.querySelectorAll('img[alt]').length,
        withoutAlt: document.querySelectorAll('img:not([alt])').length,
        emptyAlt: document.querySelectorAll('img[alt=""]').length
      },
      headings: {
        h1: Array.from(document.querySelectorAll('h1')).map(h => h.textContent.trim().slice(0,60)),
        h2: document.querySelectorAll('h2').length,
        h3: document.querySelectorAll('h3').length,
        total: document.querySelectorAll('h1,h2,h3,h4,h5,h6').length
      },
      forms: {
        total: document.querySelectorAll('form').length,
        inputs: document.querySelectorAll('input, select, textarea').length,
        buttons: document.querySelectorAll('button').length
      },
      links: { total: document.querySelectorAll('a').length },
      aria: {
        ariaLabels: document.querySelectorAll('[aria-label]').length,
        roles: document.querySelectorAll('[role]').length
      },
      landmarks: {
        main: document.querySelectorAll('main').length,
        nav: document.querySelectorAll('nav').length,
        header: document.querySelectorAll('header').length,
        footer: document.querySelectorAll('footer').length
      },
      media: {
        videos: document.querySelectorAll('video').length,
        iframes: document.querySelectorAll('iframe').length,
        videoUrls: Array.from(document.querySelectorAll('video')).map(v => {
          const src = v.src || (v.querySelector('source') ? v.querySelector('source').src : '');
          return {
            src: src,
            hasCaptions: !!v.querySelector('track[kind="captions"]')
          };
        })
      }
    }));

    const violations = axeResults.violations.map(v => ({
      tool: 'axe-core',
      id: v.id,
      impact: v.impact,
      description: v.description,
      help: v.help,
      helpUrl: v.helpUrl,
      tags: v.tags,
      nodeCount: v.nodes.length,
      nodes: v.nodes.slice(0, 5).map(n => ({
        html: n.html.slice(0, 200),
        target: n.target,
        failureSummary: n.failureSummary
      }))
    }));

    return {
      success: true,
      pageInfo,
      violations,
      passesCount: axeResults.passes.length
    };
  } finally {
    await context.close();
    await browser.close();
  }
}

// TOOL 2: Pa11y
async function runPa11y(url) {
  console.log('[pa11y] Starting...');
  const results = await pa11y(url, {
    standard: 'WCAG2AA',
    timeout: 45000,
    wait: 2000,
    chromeLaunchConfig: {
      executablePath: SYSTEM_CHROMIUM,
      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
    }
  });

  const violations = results.issues.map(issue => ({
    tool: 'pa11y',
    id: issue.code,
    impact: issue.type === 'error' ? 'serious' : issue.type === 'warning' ? 'moderate' : 'minor',
    description: issue.message,
    selector: issue.selector,
    context: (issue.context || '').slice(0, 200)
  }));

  return { success: true, violations, total: results.issues.length };
}

// TOOL 3: Lighthouse
async function runLighthouse(url) {
  console.log('[lighthouse] Starting...');
  const chrome = await launchChrome({
    chromePath: SYSTEM_CHROMIUM,
    chromeFlags: ['--headless', '--no-sandbox', '--disable-gpu', '--disable-dev-shm-usage']
  });

  try {
    const result = await lighthouse(url, {
      port: chrome.port,
      onlyCategories: ['accessibility'],
      output: 'json'
    });

    const lhr = result.lhr;
    const score = Math.round(lhr.categories.accessibility.score * 100);
    const violations = Object.values(lhr.audits)
      .filter(audit => audit.score !== null && audit.score < 1)
      .map(audit => ({
        tool: 'lighthouse',
        id: audit.id,
        impact: audit.score === 0 ? 'critical' : audit.score < 0.5 ? 'serious' : 'moderate',
        score: audit.score,
        description: audit.title
      }));

    return { success: true, score, violations };
  } finally {
    await chrome.kill();
  }
}

// ========== MAIN: PARALLEL EXECUTION WITH GRACEFUL DEGRADATION ==========

(async () => {
  console.log('=== MULTI-TOOL ACCESSIBILITY SCAN (v7.0 PARALLEL + RESILIENT) ===');
  console.log('Target:', TARGET_URL);
  console.log('Strategy: Promise.allSettled with per-tool timeouts\n');

  const startTime = Date.now();

  // Run ALL tools in PARALLEL with individual timeouts
  const [axeResult, pa11yResult, lighthouseResult] = await Promise.allSettled([
    withTimeout(
      withRetry(() => runAxeCore(TARGET_URL), 'axe-core', 2, 3000),
      60000, 'axe-core'
    ),
    withTimeout(
      withRetry(() => runPa11y(TARGET_URL), 'pa11y', 2, 3000),
      60000, 'pa11y'
    ),
    withTimeout(
      withRetry(() => runLighthouse(TARGET_URL), 'lighthouse', 2, 3000),
      90000, 'lighthouse'
    )
  ]);

  // ========== PROCESS RESULTS (Graceful Degradation) ==========
  const results = {
    url: TARGET_URL,
    timestamp: new Date().toISOString(),
    duration: `${((Date.now() - startTime) / 1000).toFixed(1)}s`,
    toolsSucceeded: 0,
    toolsFailed: 0,
    pageInfo: null,
    violations: [],
    byTool: {}
  };

  // Process axe-core results
  if (axeResult.status === 'fulfilled') {
    results.toolsSucceeded++;
    results.pageInfo = axeResult.value.pageInfo;
    results.violations.push(...axeResult.value.violations);
    results.byTool['axe-core'] = {
      success: true,
      count: axeResult.value.violations.length,
      passes: axeResult.value.passesCount
    };
    progressiveOutput('axe-core', axeResult.value);
  } else {
    results.toolsFailed++;
    results.byTool['axe-core'] = { success: false, error: axeResult.reason.message };
    console.log('\n[axe-core] FAILED:', axeResult.reason.message);
  }

  // Process pa11y results
  if (pa11yResult.status === 'fulfilled') {
    results.toolsSucceeded++;
    results.violations.push(...pa11yResult.value.violations);
    results.byTool['pa11y'] = {
      success: true,
      count: pa11yResult.value.violations.length
    };
    progressiveOutput('pa11y', pa11yResult.value);
  } else {
    results.toolsFailed++;
    results.byTool['pa11y'] = { success: false, error: pa11yResult.reason.message };
    console.log('\n[pa11y] FAILED:', pa11yResult.reason.message);
  }

  // Process lighthouse results
  if (lighthouseResult.status === 'fulfilled') {
    results.toolsSucceeded++;
    results.violations.push(...lighthouseResult.value.violations);
    results.byTool['lighthouse'] = {
      success: true,
      score: lighthouseResult.value.score,
      count: lighthouseResult.value.violations.length
    };
    progressiveOutput('lighthouse', lighthouseResult.value);
  } else {
    results.toolsFailed++;
    results.byTool['lighthouse'] = { success: false, error: lighthouseResult.reason.message };
    console.log('\n[lighthouse] FAILED:', lighthouseResult.reason.message);
  }

  // ========== DEDUPLICATE VIOLATIONS ==========
  const seen = new Set();
  const uniqueViolations = [];
  for (const v of results.violations) {
    const key = (v.description || '').toLowerCase().slice(0, 50);
    if (!seen.has(key)) {
      seen.add(key);
      uniqueViolations.push(v);
    }
  }
  results.uniqueViolations = uniqueViolations;
  results.totalUnique = uniqueViolations.length;

  // ========== FINAL OUTPUT ==========
  console.log('\n' + '='.repeat(60));
  console.log('=== SCAN COMPLETE ===');
  console.log('='.repeat(60));
  console.log(`Tools succeeded: ${results.toolsSucceeded}/3`);
  console.log(`Tools failed: ${results.toolsFailed}/3`);
  console.log(`Duration: ${results.duration}`);
  console.log(`Total unique violations: ${results.totalUnique}`);

  if (results.toolsSucceeded === 0) {
    console.log('\n⚠️  ALL TOOLS FAILED - Consider:');
    console.log('   1. Site may have strong bot protection');
    console.log('   2. Try Vibium MCP browser instead');
    console.log('   3. Check network connectivity');
  } else if (results.toolsSucceeded < 3) {
    console.log(`\n⚠️  Partial coverage (${results.toolsSucceeded}/3 tools) - Results still usable`);
  } else {
    console.log('\n✅ Full coverage achieved (3/3 tools)');
  }

  console.log('\n=== PAGE INFO ===');
  console.log(JSON.stringify(results.pageInfo, null, 2));

  console.log('\n=== VIOLATIONS BY TOOL ===');
  console.log(JSON.stringify(results.byTool, null, 2));

  console.log('\n=== UNIQUE VIOLATIONS ===');
  console.log(JSON.stringify(results.uniqueViolations, null, 2));

  // Save final results
  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(results, null, 2));
  console.log(`\nResults saved to: ${OUTPUT_FILE}`);
})();

2.2: Read Scan Results

After running the scan, read the results file:

cat /tmp/a11y-work/scan-results.json

The results include:

• pageInfo: Page structure, images, headings, media
• violations: All violations from all tools (deduplicated)
• byTool: Success/failure status per tool
• toolsSucceeded: Number of tools that completed (1-3)

2.3: Graceful Degradation Decision Tree

Tools Succeeded	Action
3/3	✅ Full coverage - proceed with all results
2/3	⚠️ Good coverage - note which tool failed in report
1/3	⚠️ Basic coverage - proceed but flag limited confidence
0/3	❌ Retry with Vibium MCP, or document failure

2.4: MANDATORY - Check for Videos and Trigger Pipeline

After reading scan results, check pageInfo.media.videoUrls:

// Check scan-results.json for videos
const results = JSON.parse(fs.readFileSync('/tmp/a11y-work/scan-results.json'));
if (results.pageInfo && results.pageInfo.media.videoUrls.length > 0) {
  console.log('=== VIDEOS DETECTED - TRIGGERING VIDEO PIPELINE ===');
  for (const video of results.pageInfo.media.videoUrls) {
    console.log(`Video: ${video.src}`);
    console.log(`  Has captions: ${video.hasCaptions}`);
  }
  // PROCEED TO STEP 7 IMMEDIATELY
}

IF videos detected AND hasCaptions=false → STEP 7 is MANDATORY before generating reports.

---

STEP 3: CONTEXT-AWARE REMEDIATION (LLM-POWERED)

THIS IS WHERE CLAUDE'S INTELLIGENCE MATTERS.

Generic tools output: aria-label="[DESCRIPTION]" You output: aria-label="Add to shopping cart" because you understand context.

3.1: Context Analysis (Use Your Reasoning)

For EACH violation, Claude must:

1. READ THE HTML CONTEXT - Don't just see <button class="btn">, see:

   <div class="product-card" data-product="Adidas Superstar">
     <img src="superstar.jpg" alt="White sneakers">
     <span class="price">$99</span>
     <button class="btn add-to-cart">  <!-- THIS IS THE VIOLATION -->
       <svg class="icon-cart">...</svg>
     </button>
   </div>
   

2. INFER PURPOSE from:

   • Class names: add-to-cart, wishlist, menu-toggle
   • Parent context: Inside .product-card with product data
   • Icon classes: icon-cart, icon-heart, icon-search
   • Nearby text: Product name, price, "Add to bag"
   • Page section: Header nav vs product grid vs checkout

3. GENERATE SPECIFIC FIX:

   <!-- NOT THIS (generic template) -->
   <button aria-label="[DESCRIPTION]">
   
   <!-- THIS (context-aware) -->
   <button aria-label="Add Adidas Superstar to cart - $99">
   

3.2: Confidence Scoring

Rate your confidence in each fix:

• 0.9+: Clear context (class="add-to-cart" near product name)
• 0.7-0.9: Reasonable inference (icon-cart class alone)
• <0.7: Needs human review (ambiguous context)

Include confidence in remediation.md:

### Button: `.product-card .btn` (Confidence: 0.95)
**Context:** Inside product card for "Adidas Superstar", has cart icon
**Fix:** `aria-label="Add Adidas Superstar to cart"`

3.2: Remediation Templates by Violation Type

Form Labels (WCAG 1.3.1, 3.3.2, 4.1.2)

<!-- Context: Input inside payment form, near "Card Number" text -->
<!-- Confidence: 0.95 -->

<!-- BEFORE -->
<input type="text" name="cardNumber" placeholder="1234 5678 9012 3456">

<!-- AFTER -->
<label for="card-number">Credit Card Number</label>
<input type="text"
       id="card-number"
       name="cardNumber"
       placeholder="1234 5678 9012 3456"
       aria-describedby="card-hint"
       autocomplete="cc-number"
       inputmode="numeric"
       pattern="[0-9\s]{13,19}">
<span id="card-hint" class="visually-hidden">Enter 16-digit card number</span>

<!-- RATIONALE -->
- Visible label aids all users
- aria-describedby provides additional context
- autocomplete enables autofill
- inputmode shows numeric keyboard on mobile
- pattern enables browser validation

Icon Buttons (WCAG 4.1.2)

<!-- Context: Button with SVG inside nav, classes include "menu-toggle" -->
<!-- Confidence: 0.92 -->

<!-- BEFORE -->
<button class="menu-toggle">
  <svg>...</svg>
</button>

<!-- AFTER -->
<button class="menu-toggle"
        type="button"
        aria-expanded="false"
        aria-controls="main-menu"
        aria-label="Open navigation menu">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

<!-- RATIONALE -->
- aria-label describes action, not icon
- aria-expanded communicates state
- aria-controls links to menu element
- SVG hidden from assistive tech (decorative)

Color Contrast (WCAG 1.4.3)

<!-- Context: Gray text (#767676) on white background -->
<!-- Current ratio: 4.48:1 (FAILS AA for normal text) -->
<!-- Required: 4.5:1 (AA) or 7:1 (AAA) -->

<!-- BEFORE -->
.low-contrast { color: #767676; background: #ffffff; }

<!-- AFTER (Option 1: Darken text - minimal change) -->
.accessible { color: #757575; background: #ffffff; } /* 4.6:1 - PASSES AA */

<!-- AFTER (Option 2: Higher contrast for AAA) -->
.high-contrast { color: #595959; background: #ffffff; } /* 7.0:1 - PASSES AAA */

<!-- COLOR ALTERNATIVES -->
| Original | AA Pass | AAA Pass | Notes |
|----------|---------|----------|-------|
| #767676  | #757575 | #595959  | Gray text |
| #0066cc  | #0055b3 | #003d82  | Link blue |
| #cc0000  | #b30000 | #8b0000  | Error red |

Heading Hierarchy (WCAG 1.3.1)

<!-- Context: Page has 10 H1 elements, skipped H2 levels -->

<!-- BEFORE (broken) -->
<h1>Welcome</h1>
<h1>Products</h1>      <!-- ERROR: Multiple H1s -->
<h4>Shoes</h4>         <!-- ERROR: Skipped H2, H3 -->
<h1>Contact</h1>

<!-- AFTER (correct) -->
<h1>Site Name - Main Page Title</h1>
<main>
  <section aria-labelledby="products-heading">
    <h2 id="products-heading">Products</h2>
    <h3>Shoes</h3>
    <h3>Clothing</h3>
  </section>
  <section aria-labelledby="contact-heading">
    <h2 id="contact-heading">Contact</h2>
  </section>
</main>

<!-- HEADING STRUCTURE VISUALIZATION -->
h1: Site Name - Main Page Title
├── h2: Products
│   ├── h3: Shoes
│   └── h3: Clothing
└── h2: Contact

Skip Links (WCAG 2.4.1)

<!-- Add as FIRST element inside <body> -->
<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <a href="#main-nav" class="skip-link">Skip to navigation</a>

  <header>
    <nav id="main-nav" aria-label="Main navigation">...</nav>
  </header>

  <main id="main-content" tabindex="-1">
    <!-- Main content -->
  </main>
</body>

<style>
.skip-link {
  position: absolute;
  top: -100%;
  left: 16px;
  background: #000;
  color: #fff;
  padding: 12px 24px;
  z-index: 10000;
  text-decoration: none;
  font-weight: bold;
  border-radius: 0 0 4px 4px;
  transition: top 0.2s;
}
.skip-link:focus {
  top: 0;
  outline: 3px solid #ffcc00;
  outline-offset: 2px;
}
</style>

Focus Indicators (WCAG 2.4.7)

/* NEVER do this */
*:focus { outline: none; } /* WCAG FAIL */

/* DO THIS - Custom focus styles */
:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

/* Remove outline only for mouse users */
:focus:not(:focus-visible) {
  outline: none;
}

/* High contrast for interactive elements */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible,
[role="button"]:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
  box-shadow: 0 0 0 6px rgba(0, 95, 204, 0.2);
}

/* Dark backgrounds need light focus */
.dark-bg :focus-visible {
  outline-color: #ffffff;
  box-shadow: 0 0 0 6px rgba(255, 255, 255, 0.3);
}

Keyboard Navigation (WCAG 2.1.1, 2.1.2)

<!-- Custom interactive element needs keyboard support -->

<!-- BEFORE (inaccessible) -->
<div class="dropdown" onclick="toggleMenu()">
  Menu
</div>

<!-- AFTER (accessible) -->
<button type="button"
        class="dropdown-trigger"
        aria-expanded="false"
        aria-controls="dropdown-menu"
        onclick="toggleMenu()"
        onkeydown="handleKeydown(event)">
  Menu
</button>
<ul id="dropdown-menu" role="menu" hidden>
  <li role="none"><a role="menuitem" href="/page1">Page 1</a></li>
  <li role="none"><a role="menuitem" href="/page2">Page 2</a></li>
</ul>

<script>
function handleKeydown(event) {
  switch(event.key) {
    case 'Enter':
    case ' ':
      event.preventDefault();
      toggleMenu();
      break;
    case 'Escape':
      closeMenu();
      break;
    case 'ArrowDown':
      event.preventDefault();
      focusFirstMenuItem();
      break;
  }
}
</script>

Modal Focus Trap (WCAG 2.4.3)

// Focus trap for modals - REQUIRED for WCAG compliance
function trapFocus(modal) {
  const focusable = modal.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  // Focus first element when modal opens
  first?.focus();

  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
    if (e.key === 'Escape') {
      closeModal();
    }
  });
}

// Return focus when modal closes
function closeModal() {
  modal.hidden = true;
  triggerButton.focus(); // Return focus to trigger
}

iframe Titles (WCAG 4.1.2)

<!-- All iframes MUST have descriptive titles -->
<iframe src="map.html" title="Store location map showing 5 nearby stores"></iframe>
<iframe src="video.html" title="Product demonstration video with captions"></iframe>
<iframe src="chat.html" title="Customer support chat window"></iframe>

---

STEP 4: USER IMPACT ANALYSIS

For each violation, calculate user impact:

4.1: Affected User Groups

Violation Type	Affected Groups	% of Users
Missing alt text	Blind, low-vision	7-10%
Missing form labels	Blind, screen reader users	5-8%
Low color contrast	Low-vision, color blind	8-12%
No keyboard access	Motor impaired, power users	10-15%
Missing captions	Deaf, hard-of-hearing	5-7%
Flashing content	Seizure sensitive	0.5-1%
Complex language	Cognitive impairment	10-15%

4.2: Impact Severity Classification

BLOCKS-USAGE: User cannot complete task at all
  - Missing form labels on required fields
  - Keyboard traps
  - Critical buttons without accessible names

IMPAIRS-USAGE: User can complete task with difficulty
  - Low contrast (can read with effort)
  - Missing skip links (tedious navigation)
  - Incorrect heading structure (confusing)

MINOR-INCONVENIENCE: Suboptimal but functional
  - Empty alt on decorative images
  - Redundant ARIA
  - Non-semantic HTML that works

---

STEP 5: ROI-BASED PRIORITIZATION

Calculate priority for each remediation:

5.1: Priority Formula

PRIORITY_SCORE = (IMPACT_WEIGHT × USERS_AFFECTED) / EFFORT_HOURS

Where:
- IMPACT_WEIGHT: Critical=10, Serious=7, Moderate=4, Minor=1
- USERS_AFFECTED: Estimated % of users impacted
- EFFORT_HOURS: Estimated fix time (0.25 to 8 hours)

5.2: Effort Estimation Guide

Fix Type	Effort	Complexity
Add aria-label	0.25h	Trivial
Add alt text	0.25h	Trivial
Add form label	0.5h	Simple
Fix color contrast	0.5h	Simple
Add skip links	1h	Simple
Fix heading structure	2h	Medium
Add keyboard navigation	4h	High
Implement focus trap	4h	High
Add video captions	8h	High

5.3: Priority Output Format

| Rank | Violation | Impact | Users | Effort | ROI Score |
|------|-----------|--------|-------|--------|-----------|
| 1 | Form labels missing | Critical | 15% | 0.5h | 300 |
| 2 | Keyboard trap | Critical | 12% | 4h | 30 |
| 3 | Low contrast | Serious | 10% | 0.5h | 140 |
| 4 | Missing alt text | Serious | 8% | 0.25h | 224 |

---

STEP 6: PRODUCTION READINESS ASSESSMENT

6.1: Compliance Scoring

COMPLIANCE_SCORE = (PASSED_CRITERIA / TOTAL_CRITERIA) × 100

Production Ready if:
✓ Score ≥ 85%
✓ Zero critical violations
✓ Fewer than 3 serious violations
✓ All user journeys keyboard accessible

6.2: POUR Analysis (Perceivable, Operable, Understandable, Robust)

| Principle | Guidelines | Pass | Fail | Score |
|-----------|-----------|------|------|-------|
| Perceivable | 1.1-1.4 | 12 | 3 | 80% |
| Operable | 2.1-2.5 | 18 | 2 | 90% |
| Understandable | 3.1-3.3 | 8 | 1 | 89% |
| Robust | 4.1 | 4 | 1 | 80% |
| **TOTAL** | | **42** | **7** | **86%** |

---

STEP 7: VIDEO ACCESSIBILITY PIPELINE

Execute for EACH video detected on page.

7.1: Detect and Extract Video URLs (MANDATORY)

This step MUST be integrated into STEP 2 multi-tool scan.

Add this to the page.evaluate() in the multi-tool scan:

// In pageInfo extraction (STEP 2), add:
videos: {
  elements: [...document.querySelectorAll('video')].map(v => ({
    src: v.src || v.querySelector('source')?.src,
    fullUrl: new URL(v.src || v.querySelector('source')?.src || '', window.location.href).href,
    poster: v.poster,
    hasCaptions: v.querySelector('track[kind="captions"]') !== null,
    hasDescriptions: v.querySelector('track[kind="descriptions"]') !== null,
    duration: v.duration || 'unknown',
    autoplay: v.autoplay,
    muted: v.muted
  })),
  iframes: [...document.querySelectorAll('iframe')].map(iframe => {
    const src = iframe.src;
    const isVideo = /youtube|vimeo|dailymotion|wistia/.test(src);
    return isVideo ? { src, platform: src.match(/(youtube|vimeo|dailymotion|wistia)/)?.[1] } : null;
  }).filter(Boolean)
}

MANDATORY OUTPUT: Log all video URLs found:

=== VIDEOS DETECTED ===
Video 1: https://example.com/promo.mp4 (no captions, no descriptions)
YouTube iframe: https://youtube.com/embed/xxx

7.2: Download and Extract Frames (MANDATORY for each video)

For EACH video URL found in 7.1:

# Create output directory
mkdir -p /tmp/a11y-work/frames

# Download video (with retry and user-agent)
curl -L -A "Mozilla/5.0" --retry 3 -o /tmp/a11y-work/video.mp4 "FULL_VIDEO_URL"

# Verify download succeeded
if [ -f /tmp/a11y-work/video.mp4 ] && [ -s /tmp/a11y-work/video.mp4 ]; then
  echo "Video downloaded successfully"
  ffmpeg -i /tmp/a11y-work/video.mp4 -vf "fps=1/3" -frames:v 10 /tmp/a11y-work/frames/frame_%02d.jpg 2>/dev/null
  echo "Extracted $(ls /tmp/a11y-work/frames/*.jpg 2>/dev/null | wc -l) frames"
else
  echo "VIDEO DOWNLOAD FAILED - Document this in audit-summary.md"
fi

IF VIDEO DOWNLOAD FAILS:

1. Document the failure reason in audit-summary.md
2. Still create video-captions violation in violations.json
3. Add remediation instructions WITHOUT generated captions
4. Mark video pipeline as "blocked" not "skipped"

7.3: Analyze Each Frame with Claude Vision (MANDATORY)

USE THE READ TOOL ON EACH FRAME IMAGE.

Claude Code has native vision capabilities. When you Read an image file, you SEE it.

Read /tmp/a11y-work/frames/frame_01.jpg
Read /tmp/a11y-work/frames/frame_02.jpg
Read /tmp/a11y-work/frames/frame_03.jpg
... (continue for all frames)

For EACH frame, describe:

• SCENE: Setting, environment, lighting, location
• PEOPLE: Who appears, what they're doing, expressions, clothing
• PRODUCTS: Items shown (for e-commerce: product names, colors, styles)
• TEXT: Any visible text, logos, signs, prices
• ACTION: Movement, transitions, what's happening

Example output after reading frame_01.jpg:

Frame 1 (0:00-0:03): A woman in white Adidas sneakers running on a forest trail.
Morning light filters through trees. She wears black athletic leggings and a
gray tank top. The Adidas three-stripe logo is visible on her shoes.

THIS IS THE LLM VALUE. Generic tools output "[DESCRIBE CONTENT]". You output actual descriptions because you can SEE the image.

---

FALLBACK: If Read tool fails on images

Try Anthropic API directly:

const Anthropic = require('@anthropic-ai/sdk');
const fs = require('fs');
const client = new Anthropic();

const imageData = fs.readFileSync('/tmp/a11y-work/frames/frame_01.jpg').toString('base64');
const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 500,
  messages: [{
    role: 'user',
    content: [
      { type: 'image', source: { type: 'base64', media_type: 'image/jpeg', data: imageData } },
      { type: 'text', text: 'Describe this video frame for accessibility captions.' }
    ]
  }]
});

LAST RESORT: Context-Based Inference (No Vision) If vision completely unavailable, infer from:

• Video filename: "product-demo.mp4" → product demonstration
• Page context: product page → product showcase
• Surrounding text: nearby headings and descriptions

Document for each frame:

• SCENE: Setting, environment, lighting
• PEOPLE: Who, actions, expressions, clothing
• OBJECTS: Products, props, equipment
• TEXT: Visible text, logos, signs
• ACTION: Movement, transitions
• COLORS: Dominant colors, accessibility-relevant

7.4: Generate WebVTT Captions

WEBVTT
Kind: captions
Language: {detected-language}

00:00:00.000 --> 00:00:03.000
[Description from frame_01 analysis]

00:00:03.000 --> 00:00:06.000
[Description from frame_02 analysis]

7.5: Generate Audio Descriptions

WEBVTT
Kind: descriptions
Language: en

00:00:00.000 --> 00:00:03.000
SCENE: [Detailed scene for blind users]
VISUAL: [What's on screen]
TEXT: [Any readable text]
ACTION: [What's happening]

---

STEP 8: GENERATE COMPREHENSIVE REPORTS

8.1: Required Output Files

Save ALL files to docs/accessibility-scans/{page-slug}/:

File	Contents
audit-summary.md	Executive summary, scores, top issues, user impact
remediation.md	ALL copy-paste code fixes with context
violations.json	Machine-readable violation data
implementation.md	Video integration guide (if videos)
*.vtt	Caption and audio description files

8.2: audit-summary.md Template

# Accessibility Audit Report: {Site Name}

**URL:** {url}
**Date:** {date}
**Standard:** WCAG 2.2 Level AA

## Executive Summary

| Metric | Value |
|--------|-------|
| **Compliance Score** | {score}% |
| **Production Ready** | {Yes/No} |
| **Critical Issues** | {count} |
| **Total Violations** | {count} |
| **Estimated Fix Time** | {hours}h |

## POUR Analysis
{table}

## Top 10 Issues by Priority
{priority table with ROI scores}

## User Impact Summary
{affected user groups and percentages}

## Recommendations
{prioritized action items}

8.3: remediation.md Template

# Accessibility Remediation Guide: {Site Name}

## Quick Wins (Copy-Paste Ready)

### 1. Form Labels ({count} issues)
{For EACH unlabeled input: context, before/after code, rationale, confidence}

### 2. Heading Structure ({count} issues)
{Current structure visualization, fixed structure, code changes}

### 3. Color Contrast ({count} issues)
{For EACH: current colors, ratio, suggested colors, CSS fixes}

### 4. Missing Alt Text ({count} issues)
{For EACH image: context-inferred alt text suggestions}

### 5. Keyboard Navigation ({count} issues)
{For EACH: element, issue, fix code, test instructions}

### 6. Focus Indicators
{Global CSS to add}

### 7. Skip Links
{Full HTML + CSS to add}

### 8. ARIA Fixes ({count} issues)
{For EACH: context, specific aria attributes to add}

### 9. iframe Titles ({count} issues)
{For EACH: suggested title based on content}

### 10. Video Accessibility ({count} videos)
{Links to generated VTT files, implementation code}

## Testing Checklist
- [ ] Tab through entire page - all interactive elements reachable
- [ ] Screen reader announces all content correctly
- [ ] Color contrast passes (use axe DevTools)
- [ ] Works without mouse
- [ ] Works at 200% zoom
- [ ] Video captions synchronized and accurate

---

STEP 9: LEARNING PROTOCOL (When MCP Available)

Integrate with the learning system to improve over time.

9.1: Query Previous Patterns BEFORE Audit

Check if similar sites were audited before:

// Load MCP tools
ToolSearch("select:mcp__claude-flow_alpha__memory_retrieve")
ToolSearch("select:mcp__claude-flow_alpha__hooks_intelligence_pattern_search")

// Retrieve domain-specific patterns
mcp__claude-flow_alpha__memory_retrieve({
  key: `accessibility/patterns/${domain}`,
  namespace: "learning"
})

// Search for similar violation patterns
mcp__claude-flow_alpha__hooks_intelligence_pattern_search({
  query: "accessibility remediation",
  type: "accessibility-fix",
  limit: 10
})

9.2: Store Successful Patterns AFTER Audit

Store patterns that worked for future reuse:

ToolSearch("select:mcp__claude-flow_alpha__memory_store")
ToolSearch("select:mcp__claude-flow_alpha__hooks_intelligence_pattern_store")

// Store audit outcome
mcp__claude-flow_alpha__memory_store({
  key: `accessibility-audit/${domain}-${Date.now()}`,
  namespace: "learning",
  value: {
    url: auditedUrl,
    timestamp: new Date().toISOString(),
    violationsFound: violations.length,
    criticalCount: violations.filter(v => v.impact === 'critical').length,
    toolsUsed: ['axe-core', 'pa11y', 'lighthouse'],
    patterns: {
      commonViolations: extractTopViolationTypes(violations),
      effectiveFixes: extractFixesThatWorked(remediations)
    }
  }
})

// Store reusable remediation patterns
mcp__claude-flow_alpha__hooks_intelligence_pattern_store({
  pattern: "form-label-contextual-fix",
  confidence: 0.92,
  type: "accessibility-remediation",
  metadata: {
    wcagCriteria: "1.3.1, 3.3.2, 4.1.2",
    violationType: "missing-form-label",
    codeTemplate: "<label for=\"{id}\">{inferredLabel}</label>",
    contextSignals: ["placeholder", "nearby-text", "field-name"]
  }
})

9.3: Calculate Audit Quality Score

Self-assess audit completeness (for learning feedback):

Criteria	Points	Your Score
Multi-tool testing used (3 tools)	20
All WCAG 2.2 AA criteria checked	15
Context-aware fixes generated	20
Confidence scores included	10
ROI prioritization calculated	10
Video pipeline completed (if applicable)	15
EU compliance mapping included	10
Total	100

Quality Levels:

• 90-100: Excellent (1.0 reward)
• 70-89: Good (0.8 reward)
• 50-69: Acceptable (0.5 reward)
• <50: Incomplete (0.0 reward - redo required)

---

STEP 10: SCREEN READER TESTING GUIDE

Manual testing instructions (cannot be fully automated):

10.1: NVDA (Windows - Free)

1. Download: https://www.nvaccess.org/download/
2. Install and start NVDA (Ctrl+Alt+N)
3. Navigate to audited page

Key Commands:
- H: Jump through headings
- F: Jump through form fields
- B: Jump through buttons
- T: Jump through tables
- K: Jump through links
- D: Jump through landmarks
- Tab: Move through focusable elements

Verify:
- [ ] All headings announced with correct level
- [ ] Form fields announce labels
- [ ] Buttons announce purpose
- [ ] Images announce alt text or "decorative"
- [ ] Dynamic content changes announced (aria-live)

10.2: VoiceOver (macOS - Built-in)

1. Enable: System Preferences → Accessibility → VoiceOver
2. Toggle: Cmd+F5
3. Navigate to audited page

Key Commands:
- VO+U: Open rotor (headings, links, forms, landmarks)
- VO+Space: Activate element
- VO+Right/Left: Move through content
- VO+Cmd+H: Jump to next heading

Verify:
- [ ] Rotor shows all headings hierarchically
- [ ] Forms are navigable and labels announced
- [ ] Focus order matches visual order
- [ ] All content is reachable

10.3: JAWS (Windows - Commercial)

1. Trial: https://www.freedomscientific.com/products/software/jaws/
2. Start JAWS and navigate to page

Key Commands:
- H: Next heading
- F: Next form field
- B: Next button
- T: Next table
- Ins+F6: Heading list
- Ins+F7: Link list

Verify:
- [ ] Virtual cursor mode works correctly
- [ ] Forms mode activates in forms
- [ ] All ARIA roles announced properly

10.4: Screen Reader Testing Checklist

Test	NVDA	VoiceOver	JAWS
Headings hierarchy correct	[ ]	[ ]	[ ]
Form labels announced	[ ]	[ ]	[ ]
Button purposes clear	[ ]	[ ]	[ ]
Image alt text correct	[ ]	[ ]	[ ]
Links announce destination	[ ]	[ ]	[ ]
Landmarks navigable	[ ]	[ ]	[ ]
Focus order logical	[ ]	[ ]	[ ]
Dynamic updates announced	[ ]	[ ]	[ ]
No keyboard traps	[ ]	[ ]	[ ]
Skip links work	[ ]	[ ]	[ ]

---

VALIDATION CHECKLIST

Before completing, verify ALL items:

Content Fetching (v7.0 Resilient)

• Browser launched (Vibium/agent-browser/Playwright)
• Page loaded and analyzed
• Multi-tool scan ran with parallel execution
• At least 1 of 3 tools succeeded (graceful degradation)
• If tools failed, documented which tools and why
• Results saved to /tmp/a11y-work/scan-results.json

Violation Analysis

• All violations extracted with WCAG criteria
• Context analyzed for each violation
• User impact calculated

Remediation Generation

• Form label fixes with context and rationale
• Heading hierarchy fix with visualization
• Color contrast fixes with hex codes
• Alt text suggestions with confidence scores
• Skip link code (full HTML + CSS)
• Focus indicator CSS
• ARIA fixes with specific attributes
• Keyboard navigation fixes
• iframe titles

Video Accessibility (MANDATORY if pageInfo.media.videos > 0)

• Video URLs extracted (full URLs, not relative)
• Download attempted for EACH video
• IF download succeeded: Frames extracted with ffmpeg
• IF download succeeded: Each frame analyzed with Read tool
• IF download succeeded: captions.vtt generated from ACTUAL frame descriptions
• IF download succeeded: audiodesc.vtt generated
• IF download FAILED: Failure documented in audit-summary.md with reason
• IF download FAILED: Manual captioning instructions in remediation.md

BLOCKING: Cannot generate final reports until video pipeline attempted.

Output Files

• audit-summary.md with scores, priorities, and user impact
• remediation.md with ALL copy-paste code fixes
• violations.json with violation data
• VTT files (if videos)
• implementation.md (if videos)

Quality Checks

• Compliance score calculated
• Production readiness assessed
• ROI prioritization completed
• POUR analysis included

IF ANY CHECKBOX IS NO = TASK INCOMPLETE </default_to_action>

---

Quick Reference Card

Usage

/a11y-ally https://example.com

v7.0 Resilience Features

Feature	Description
Parallel Execution	All 3 tools run simultaneously via Promise.allSettled
Per-Tool Timeouts	axe: 60s, pa11y: 60s, Lighthouse: 90s
Retry with Backoff	2 retries per tool with exponential backoff
Graceful Degradation	Continue if 1+ tools succeed
Progressive Output	Results stream as tools complete
Bot Protection	Stealth mode, random delays, cookie dismissal

Expected Output Structure

docs/accessibility-scans/{page-slug}/
├── audit-summary.md      # Executive summary with scores
├── remediation.md        # ALL copy-paste code fixes
├── violations.json       # Machine-readable data
├── implementation.md     # Video integration (if videos)
├── video-*-captions.vtt  # Captions (if videos)
└── video-*-audiodesc.vtt # Audio descriptions (if videos)

Compliance Thresholds

Level	Min Score	Critical	Serious
A	70%	0	≤5
AA	85%	0	≤3
AAA	95%	0	0

Tool Coverage by Success

Tools Succeeded	Detection Rate	Status
3/3	~95%	✅ Optimal
2/3	~85%	⚠️ Good
1/3	~70%	⚠️ Acceptable
0/3	—	❌ Retry needed

ROI Formula

ROI = (Impact × Users%) / Effort_Hours

---

EU Compliance Mapping

WCAG	EN 301 549	EU Accessibility Act
1.1.1	9.1.1.1	EAA-I.1 Perceivable
1.4.3	9.1.4.3	EAA-I.1 Perceivable
2.1.1	9.2.1.1	EAA-I.2 Operable
2.4.7	9.2.4.7	EAA-I.2 Operable
3.3.2	9.3.3.2	EAA-I.3 Understandable
4.1.2	9.4.1.2	EAA-I.4 Robust

---

Critical Rules

Execution Rules (v7.0)

1. ALWAYS run multi-tool scan with parallel execution (Promise.allSettled)
2. ALWAYS continue if at least 1 of 3 tools succeeds (graceful degradation)
3. ALWAYS document which tools failed and why in audit-summary.md
4. ALWAYS use per-tool timeouts (60s/60s/90s) not global timeout
5. ALWAYS retry failed tools with exponential backoff before giving up

Quality Rules

6. ALWAYS analyze context before generating fixes
7. ALWAYS include confidence scores with remediation
8. ALWAYS calculate user impact and ROI
9. ALWAYS generate copy-paste ready code
10. NEVER generate placeholder/template fixes
11. NEVER skip video pipeline if videos detected
12. NEVER complete without remediation.md
13. NEVER fail audit just because 1-2 tools failed (use graceful degradation)

Gotchas

• axe-core catches ~30% of WCAG issues — automated tools miss keyboard navigation, reading order, and cognitive issues
• Agent runs Lighthouse only and reports "accessible" — Lighthouse alone is insufficient, always run axe-core + pa11y too
• Screen reader testing requires actual screen reader interaction, not just ARIA attribute checks
• Video accessibility (captions, audio descriptions) is frequently skipped — check every <video> element
• Color contrast tools disagree on gradients and transparency — test with actual low-vision simulation
• Playwright+Stealth may be blocked by some sites — fall back gracefully, don't skip the audit