メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/proffesor-for-testing/agentic-qe --skill a11y-allyコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Ruflo is a multi-agent orchestration platform for AI coding agents (Claude Code, Cursor, Codex, Copilot, Gemini, Amp, +12 more). Use this skill when the user wants to (1) install/init ruflo in a project, (2) run multi-agent swarms with hierarchical coordination, (3) use ruflo's 314+ MCP tools for memory, routing, hooks, sub-agents, or workflows, (4) check ruflo status/version/doctor health, or (5) discover which of ruflo's 30+ plugins fits their task.
Build dependency-aware execution plans for complex Agentic QE, Ruflo, integration, migration, or multi-stream engineering programs. Use when Codex must turn research or requirements into phased work, select a small AQE fleet, map critical paths and parallel streams, define acceptance gates, or sequence risky changes. Use aqe-plan-quality instead when the primary output is only a test or quality plan.
Conduct evidence-first technical research for Agentic QE, Ruflo, related ruvnet projects, or external tools. Use when Codex must investigate a repository, compare current upstream changes, trace dependencies and history, distinguish verified facts from inference, or synthesize findings into actionable engineering recommendations. Do not use for a simple known-answer lookup or an implementation-only task.
SOC 職業分類に基づく
SKILL.md を表示中
| 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"} |
<default_to_action> When this skill is invoked with a URL, Claude executes ALL steps automatically without waiting for user prompts between steps.
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.
CLAUDE EXECUTES ALL STEPS WITHOUT STOPPING.
Do NOT wait for user prompts between steps. Execute the full pipeline:
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/"
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.
# 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.
# 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]"}
]'
# 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:
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
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)));
IMPORTANT: This step uses THREE accessibility testing tools for maximum coverage:
Combined detection rate is ~15% higher than any single tool.
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:
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}`);
})();
After running the scan, read the results file:
cat /tmp/a11y-work/scan-results.json
The results include:
| 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 |
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.
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.
For EACH violation, Claude must:
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>
INFER PURPOSE from:
add-to-cart, wishlist, menu-toggle.product-card with product dataicon-cart, icon-heart, icon-searchGENERATE SPECIFIC FIX:
<!-- NOT THIS (generic template) -->
<button aria-label="[DESCRIPTION]">
<!-- THIS (context-aware) -->
<button aria-label="Add Adidas Superstar to cart - $99">
Rate your confidence in each fix:
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"`
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>
For each violation, calculate user impact:
| 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% |
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
Calculate priority for each remediation:
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)
| 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 |
| 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 |
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
| 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%** |
Execute for EACH video detected on page.
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
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:
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:
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:
Document for each frame:
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]
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]
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 |
# 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}
# 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
Integrate with the learning system to improve over time.
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
})
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"]
}
})
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:
Manual testing instructions (cannot be fully automated):
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)
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
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
| 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 | [ ] | [ ] | [ ] |
Before completing, verify ALL items:
/tmp/a11y-work/scan-results.jsonBLOCKING: Cannot generate final reports until video pipeline attempted.
IF ANY CHECKBOX IS NO = TASK INCOMPLETE </default_to_action>
/a11y-ally https://example.com
| 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 |
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)
| Level | Min Score | Critical | Serious |
|---|---|---|---|
| A | 70% | 0 | ≤5 |
| AA | 85% | 0 | ≤3 |
| AAA | 95% | 0 | 0 |
| Tools Succeeded | Detection Rate | Status |
|---|---|---|
| 3/3 | ~95% | ✅ Optimal |
| 2/3 | ~85% | ⚠️ Good |
| 1/3 | ~70% | ⚠️ Acceptable |
| 0/3 | — | ❌ Retry needed |
ROI = (Impact × Users%) / Effort_Hours
| 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 |
<video> element