wcag-a11y 0.2.0 → 0.3.0

package/README.md

@@ -87,14 +87,14 @@ Each command creates an `a11y.config.json` pre-wired for that provider. Fill in
 Scan a built-in page with 10 intentional violations. No dev server or config required — useful for trying the tool before pointing it at your own project.
 
 ```bash
-wcag-a11y demo                  # violations only
-wcag-a11y demo --ai             # violations + AI fixes (requires config)
-wcag-a11y demo --ai --report    # + save a11y-report.md
+wcag-a11y demo                  # violations + AI fixes (default, requires config)
+wcag-a11y demo --no-ai          # violations only, no AI — faster
+wcag-a11y demo --report         # + save a11y-report.md
 ```
 
 | Flag | Description |
 |---|---|
-| `--ai` | Generate AI fix explanations and prompts for each violation |
+| `--no-ai` | Skip AI fix generation — prints violations only, no prompts |
 | `-r, --report` | Save the full report to `a11y-report.md` in the current directory |
 
 ---
@@ -122,7 +122,7 @@ Scan a running dev server for accessibility violations.
 ```bash
 wcag-a11y scan -u http://localhost:3000
 wcag-a11y scan -u http://localhost:3000 --pages / /about /contact
-wcag-a11y scan -u http://localhost:3000 --crawl --ai --report
+wcag-a11y scan -u http://localhost:3000 --crawl --report
 wcag-a11y scan -u http://localhost:3000 --no-ai --ci
 ```
 
@@ -132,7 +132,7 @@ wcag-a11y scan -u http://localhost:3000 --no-ai --ci
 | `-p, --pages <pages...>` | `/` | One or more paths to scan. Separate with spaces: `--pages / /about /contact` |
 | `-c, --crawl` | off | Follow same-origin links and scan all reachable pages automatically |
 | `-r, --report` | off | Save the full scan output to `a11y-report.md` |
-| `--ai` / `--no-ai` | on | Generate AI fix explanations and prompts. Use `--no-ai` for a fast violation-only scan |
+| `--no-ai` | on | Skip AI fix generation — scan runs faster and prints violations only |
 | `--no-explain` | off | Print only the ready-to-paste prompt for each fix, without the AI explanation |
 | `--group <strategy>` | `rule` | `rule` (default) groups all violations of the same type into one fix prompt. `none` produces a separate prompt per element. Use `none` when violations of the same rule need different fixes |
 | `--ci` | off | Exit with code `1` if any violations are found. Use this to fail a CI pipeline |

package/dist/ai/gemini.js

@@ -45,15 +45,19 @@ export class GeminiProvider {
     }
     fallbackFix(g) {
         const v = g.representative;
-        const instanceNote = g.count > 1 ? ` There are ${g.count} similar instances at: ${g.selectors.join(', ')}.` : '';
+        const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
+        const explanation = `Users relying on assistive technologies are affected: ${g.description.toLowerCase()}. This fails WCAG 2.1 SC ${g.wcag} (Level ${g.level}).`;
+        const prompt = g.count > 1
+            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,
             instanceCount: g.count,
-            explanation: g.description,
+            explanation,
             fixedCode: v.html,
             wcagReference: `WCAG 2.1 SC ${g.wcag}`,
-            optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${g.selectors[0]}\` violates ${g.wcag} — ${g.description}.${instanceNote} Please fix it in the codebase.`,
+            optimalPrompt: prompt,
         };
     }
 }

package/dist/ai/ollama.js

@@ -43,15 +43,19 @@ export class OllamaProvider {
     }
     fallbackFix(g) {
         const v = g.representative;
-        const instanceNote = g.count > 1 ? ` There are ${g.count} similar instances at: ${g.selectors.join(', ')}.` : '';
+        const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
+        const explanation = `Users relying on assistive technologies are affected: ${g.description.toLowerCase()}. This fails WCAG 2.1 SC ${g.wcag} (Level ${g.level}).`;
+        const prompt = g.count > 1
+            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,
             instanceCount: g.count,
-            explanation: g.description,
+            explanation,
             fixedCode: v.html,
             wcagReference: `WCAG 2.1 SC ${g.wcag}`,
-            optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${g.selectors[0]}\` violates ${g.wcag} — ${g.description}.${instanceNote} Please fix it in the codebase.`,
+            optimalPrompt: prompt,
         };
     }
 }

package/dist/ai/openai.js

@@ -49,15 +49,19 @@ export class OpenAIProvider {
     }
     fallbackFix(g) {
         const v = g.representative;
-        const instanceNote = g.count > 1 ? ` There are ${g.count} similar instances at: ${g.selectors.join(', ')}.` : '';
+        const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
+        const explanation = `Users relying on assistive technologies are affected: ${g.description.toLowerCase()}. This fails WCAG 2.1 SC ${g.wcag} (Level ${g.level}).`;
+        const prompt = g.count > 1
+            ? `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`${v.html.slice(0, 300)}\`\n\nApply the fix to all ${g.count} instances in the codebase to comply with WCAG 2.1 SC ${g.wcag}.`
+            : `Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n- HTML: \`${v.html.slice(0, 300)}\`\n\nApply the fix to comply with WCAG 2.1 SC ${g.wcag}.`;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,
             instanceCount: g.count,
-            explanation: g.description,
+            explanation,
             fixedCode: v.html,
             wcagReference: `WCAG 2.1 SC ${g.wcag}`,
-            optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${g.selectors[0]}\` violates ${g.wcag} — ${g.description}.${instanceNote} Please fix it in the codebase.`,
+            optimalPrompt: prompt,
         };
     }
 }

package/dist/ai/prompt.js

@@ -11,10 +11,10 @@ export function buildPrompt(groups) {
 Each item must have:
 - "ruleId": the rule id from the input
 - "selectors": array of CSS selectors affected (copy from input)
-- "explanation": 1-2 sentences explaining why this matters for users with disabilities (plain English, no jargon)
+- "explanation": 1-2 sentences on concrete user impact — name exactly who is affected (e.g. "screen reader users", "keyboard-only users", "users with low vision") and what they cannot do because of this specific violation. Do not write generic statements like "users with disabilities may be affected."
 - "fixedCode": the corrected HTML snippet only (no explanation, just code)
-- "wcagReference": e.g. "WCAG 2.1 SC 1.1.1 — Non-text Content"
-- "optimalPrompt": a ready-to-paste prompt the developer can give to an AI coding assistant (Cursor, GitHub Copilot, Claude) to fix this issue in their codebase. Include the violating elements, what rule they break, how many instances there are, and exactly what change is needed. Be specific and actionable.
+- "wcagReference": the full criterion name, e.g. "WCAG 2.1 SC 1.1.1 Non-text Content (Level A)"
+- "optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude). Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated (e.g. "WCAG 2.1 SC 1.1.1 Non-text Content, Level A"), (2) list the affected selectors and HTML snippets, (3) state the exact code change needed to comply. Focus solely on the fix — do not explain why WCAG exists or what accessibility is. Be precise and actionable.
 
 Return ONLY a valid JSON array. No markdown, no code fences, no explanation outside the JSON.
 

package/dist/cli.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { loadConfig, initConfig } from './config.js';
 import { crawl } from './crawler.js';
 import { createAIProvider } from './ai/index.js';
+import { groupViolations } from './ai/group.js';
 import { printTerminalReport, printAIPrompts } from './reporter/terminal.js';
 import { generateMarkdownReport } from './reporter/markdown.js';
 import { runDemo } from './demo.js';
@@ -10,7 +11,7 @@ const program = new Command();
 program
     .name('wcag-a11y')
     .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
-    .version('0.2.0');
+    .version('0.3.0');
 program
     .command('init')
     .description('Create a11y.config.json in the current directory')
@@ -27,6 +28,8 @@ program
     .option('-r, --report', 'Save a full markdown report to a11y-report.md', false)
     .option('--no-ai', 'Skip AI fix generation (faster, violations only)')
     .option('--no-explain', 'Hide AI fix explanations in terminal output')
+    .option('--no-terminal', 'Suppress terminal output (violations summary)')
+    .option('--fast-mode', 'Output only AI fix prompts — no summaries or explanations', false)
     .option('--group <strategy>', 'Group violations by rule or show individually (rule|none)', 'rule')
     .option('--ci', 'Exit with code 1 if any violations are found (for CI/CD pipelines)', false)
     .option('--provider <name>', 'Override the AI provider from config (gemini|openai|ollama)')
@@ -34,7 +37,9 @@ program
     try {
         console.log(`\nScanning ${opts.url}...`);
         const result = await crawl({ url: opts.url, pages: opts.pages, crawl: opts.crawl });
-        printTerminalReport(result);
+        if (opts.terminal && !opts.fastMode) {
+            printTerminalReport(result);
+        }
         const strategy = opts.group === 'none' ? 'none' : 'rule';
         if (opts.ai && result.totalViolations > 0) {
             const config = loadConfig();
@@ -43,15 +48,20 @@ program
             }
             const provider = createAIProvider(config);
             const allViolations = result.pages.flatMap((p) => p.violations);
-            console.log(`\nGenerating AI fixes for ${allViolations.length} violations...`);
+            const ruleGroups = groupViolations(allViolations, strategy);
+            if (!opts.fastMode) {
+                console.log(`\nGenerating AI fixes for ${ruleGroups.length} rule groups (${allViolations.length} violations)...`);
+            }
             const fixes = await provider.generateFixes(allViolations, strategy);
-            printAIPrompts(fixes, { explain: opts.explain });
+            if (opts.terminal) {
+                printAIPrompts(fixes, { explain: opts.explain, fastMode: opts.fastMode });
+            }
             if (opts.report) {
-                generateMarkdownReport(result, fixes);
+                generateMarkdownReport(result, fixes, { fastMode: opts.fastMode });
             }
         }
         else if (opts.report) {
-            generateMarkdownReport(result, []);
+            generateMarkdownReport(result, [], { fastMode: opts.fastMode });
         }
         if (opts.ci && result.totalViolations > 0) {
             process.exit(1);

package/dist/reporter/markdown.js

@@ -5,7 +5,31 @@ const IMPACT_EMOJI = {
     moderate: '🟡',
     minor: '🟢',
 };
-export function generateMarkdownReport(result, fixes, outputPath = 'a11y-report.md') {
+export function generateMarkdownReport(result, fixes, opts = {}, outputPath = 'a11y-report.md') {
+    const lines = opts.fastMode
+        ? buildFastReport(fixes)
+        : buildFullReport(result, fixes);
+    writeFileSync(outputPath, lines.join('\n'), 'utf-8');
+    console.log(`\nReport saved → ${outputPath}`);
+}
+function buildFastReport(fixes) {
+    const lines = [
+        '# WCAG A11y — Fix Prompts',
+        `> Generated: ${new Date().toLocaleString()}`,
+        '',
+    ];
+    for (const fix of fixes) {
+        const countLabel = fix.instanceCount > 1 ? ` ×${fix.instanceCount}` : '';
+        lines.push(`## \`${fix.ruleId}\`${countLabel}`, '');
+        lines.push('**Selectors:**');
+        for (const sel of fix.selectors) {
+            lines.push(`- \`${sel}\``);
+        }
+        lines.push('', '```', fix.optimalPrompt, '```', '', '---', '');
+    }
+    return lines;
+}
+function buildFullReport(result, fixes) {
     const lines = [
         '# WCAG A11y Report',
         `> Generated: ${new Date().toLocaleString()}`,
@@ -37,6 +61,5 @@ export function generateMarkdownReport(result, fixes, outputPath = 'a11y-report.
             lines.push('---', '');
         }
     }
-    writeFileSync(outputPath, lines.join('\n'), 'utf-8');
-    console.log(`\nReport saved → ${outputPath}`);
+    return lines;
 }

package/dist/reporter/terminal.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { groupViolations } from '../ai/group.js';
 const IMPACT_COLOR = {
     critical: chalk.red,
     serious: chalk.yellow,
@@ -22,12 +23,17 @@ export function printTerminalReport(result) {
             m > 0 ? chalk.blue(`${m} moderate`) : '',
         ].filter(Boolean).join('  ');
         console.log(`\n  ${chalk.red('✖')}  ${url}  ${counts}`);
-        for (const v of page.violations) {
-            const color = IMPACT_COLOR[v.impact] ?? chalk.white;
-            const tag = color(`[${v.impact.toUpperCase()}]`);
-            const wcag = chalk.gray(`WCAG ${v.wcag}`);
-            console.log(`     ${tag} ${v.description}  ${wcag}`);
-            console.log(`     ${chalk.gray('→')} ${chalk.dim(v.selector)}`);
+        const groups = groupViolations(page.violations, 'rule');
+        for (const g of groups) {
+            const color = IMPACT_COLOR[g.impact] ?? chalk.white;
+            const countSuffix = g.count > 1 ? chalk.gray(` ×${g.count}`) : '';
+            const tag = color(`[${g.impact.toUpperCase()}]`) + countSuffix;
+            const wcag = chalk.gray(`WCAG ${g.wcag}`);
+            console.log(`     ${tag} ${g.description}  ${wcag}`);
+            console.log(`     ${chalk.gray('→')} ${chalk.dim(g.selectors[0])}`);
+            if (g.count > 1) {
+                console.log(`     ${chalk.gray(`   …and ${g.count - 1} more`)}`);
+            }
         }
     }
     console.log('\n' + chalk.gray('─'.repeat(60)));
@@ -37,6 +43,15 @@ export function printTerminalReport(result) {
 export function printAIPrompts(fixes, opts) {
     if (fixes.length === 0)
         return;
+    if (opts.fastMode) {
+        for (let i = 0; i < fixes.length; i++) {
+            console.log(fixes[i].optimalPrompt);
+            if (i < fixes.length - 1)
+                console.log('\n' + chalk.gray('─'.repeat(60)));
+        }
+        console.log('');
+        return;
+    }
     console.log('\n' + chalk.bold.magenta('AI Fix Prompts') + chalk.gray(' — paste any of these into Cursor, Copilot, or Claude'));
     console.log(chalk.gray('─'.repeat(60)));
     for (const fix of fixes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wcag-a11y",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes",
   "type": "module",
   "bin": {