wcag-a11y 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,62 @@
 # WCAG A11y
 
-WCAG 2.1/2.2 accessibility CLI auditor with AI-powered fixes.
+[![CI](https://github.com/Dannyplusplus12/WCAG-A11y/actions/workflows/ci.yml/badge.svg)](https://github.com/Dannyplusplus12/WCAG-A11y/actions/workflows/ci.yml)
+
+Most accessibility auditors stop at detection — they tell you *what* is broken and leave the rest to you. `wcag-a11y` goes further. It crawls your running dev server with Playwright, runs 40+ WCAG 2.1/2.2 checks, and uses AI to generate a ready-to-paste fix prompt for each violation. You paste it into Cursor, Copilot, or Claude and the fix writes itself.
+
+The goal is to close the loop between finding an accessibility issue and actually fixing it, without interrupting your existing workflow.
+
+---
+
+## Try it instantly
+
+No dev server, no config, no setup:
+
+```bash
+npx wcag-a11y demo
+```
+
+---
+
+## What the output looks like
+
+Running a scan prints a violation summary per page, then AI-generated fixes for each rule:
+
+```
+Scanning http://localhost:3000...
+
+  /
+  ✖  critical   img-alt                  3 violations
+  ✖  serious    color-contrast-text      2 violations
+  ✖  serious    label-missing            1 violation
+  ✖  moderate   no-positive-tabindex     1 violation
+
+  7 violations across 1 page
+
+Generating AI fixes for 7 violations...
+
+────────────────────────────────────────────
+[img-alt] — 3 elements affected
+  #hero-img  #logo  #banner
+
+  Why it matters:
+  Screen readers cannot describe the image to blind users without an alt attribute.
+  Users relying on assistive technology receive no information about the image content.
+
+  Fixed HTML:
+  <img src="banner.jpg" alt="Summer sale — up to 50% off">
+
+  Prompt for your AI editor:
+  Fix accessibility: 3 <img> elements (#hero-img, #logo, #banner) are missing alt
+  attributes, violating WCAG 1.1.1. Add descriptive alt text to each image.
+────────────────────────────────────────────
+```
+
+The **prompt** at the end of each fix is what you copy into Cursor, Copilot, or Claude. It includes the affected selectors, the WCAG rule, and exactly what needs to change — no rewriting needed.
+
+With `--report`, the full output is also saved to `a11y-report.md`.
+
+---
 
 ## Install
 
@@ -11,34 +67,232 @@ npm install -g wcag-a11y
 ## Setup
 
 ```bash
-wcag-a11y init          # creates a11y.config.json
-# Add your free Gemini API key from https://aistudio.google.com
+wcag-a11y init                       # Gemini (free, default)
+wcag-a11y init --provider openai     # OpenAI
+wcag-a11y init --provider ollama     # Local — no API key needed
+```
+
+Each command creates an `a11y.config.json` pre-wired for that provider. Fill in your API key, then scan.
+
+**Get a free Gemini key:** https://aistudio.google.com  
+**Get an OpenAI key:** https://platform.openai.com/api-keys  
+**Ollama (local):** install from https://ollama.com, then run `ollama serve`
+
+---
+
+## Commands
+
+### `wcag-a11y demo`
+
+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 + AI fixes (default, requires config)
+wcag-a11y demo --no-ai          # violations only, no AI — faster
+wcag-a11y demo --report         # + save a11y-report.md
 ```
 
-## Usage
+| Flag | Description |
+|---|---|
+| `--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 |
+
+---
+
+### `wcag-a11y init`
+
+Create `a11y.config.json` in the current directory, pre-configured for your chosen provider.
 
 ```bash
-# Scan a single page
-wcag-a11y scan --url http://localhost:3000
+wcag-a11y init                       # Gemini (default)
+wcag-a11y init --provider openai     # OpenAI
+wcag-a11y init --provider ollama     # Ollama (local)
+```
+
+| Flag | Description |
+|---|---|
+| `--provider <name>` | Which provider to configure: `gemini` (default), `openai`, or `ollama`. Determines which fields are written to the config file. |
 
-# Scan specific pages
-wcag-a11y scan --url http://localhost:3000 --pages / /about /contact
+---
 
-# Auto-crawl all pages + generate report
-wcag-a11y scan --url http://localhost:3000 --crawl --report
+### `wcag-a11y scan`
 
-# Skip AI (violations only, no fixes)
-wcag-a11y scan --url http://localhost:3000 --no-ai
+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 --report
+wcag-a11y scan -u http://localhost:3000 --no-ai --ci
 ```
 
+| Flag | Default | Description |
+|---|---|---|
+| `-u, --url <url>` | required | Base URL of your running dev server |
+| `-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` |
+| `--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 |
+| `--provider <name>` | from config | Override the AI provider for this run: `gemini`, `openai`, or `ollama`. Does not modify the config file |
+
+---
+
+## AI Providers
+
+| Provider | Model | Cost | API Key |
+|---|---|---|---|
+| `gemini` (default) | `gemini-2.5-flash` | Free tier | [aistudio.google.com](https://aistudio.google.com) |
+| `openai` | `gpt-4o-mini` | Pay-per-use | [platform.openai.com](https://platform.openai.com/api-keys) |
+| `ollama` | `llama3` | Free (local) | None — run `ollama serve` |
+
+Set your provider in `a11y.config.json` or override it per-run with `--provider`. If the AI response is unparseable, the tool generates a fix prompt directly from the violation data so you always get something actionable.
+
+---
+
 ## Config (`a11y.config.json`)
 
 ```json
 {
   "provider": "gemini",
-  "apiKey": "YOUR_FREE_KEY",
-  "model": "gemini-2.0-flash"
+
+  "apiKey": "YOUR_GEMINI_API_KEY",
+  "model": "gemini-2.5-flash",
+
+  "openaiApiKey": "YOUR_OPENAI_API_KEY",
+  "openaiModel": "gpt-4o-mini",
+
+  "ollamaBaseUrl": "http://localhost:11434",
+  "ollamaModel": "llama3"
 }
 ```
 
-For local AI (no API key): set `"provider": "ollama"` and run `ollama serve`.
+Only the fields for your active provider are required. This file is gitignored by default.
+
+---
+
+## What it checks
+
+40+ rules across 10 categories, mapped to WCAG 2.1/2.2 success criteria.
+
+### Text Alternatives — WCAG 1.1.1
+
+| Rule | Impact | Description |
+|---|---|---|
+| `img-alt` | critical | Images must have an `alt` attribute |
+| `input-image-alt` | critical | `<input type="image">` must have `alt` |
+| `svg-title` | serious | Inline SVGs must have `<title>` or `aria-label` |
+| `object-alt` | serious | `<object>` must have fallback text content |
+| `role-img-alt` | serious | Elements with `role="img"` must have an accessible name |
+| `image-redundant-alt` | minor | Image `alt` must not duplicate nearby visible text |
+
+### Color Contrast — WCAG 1.4.3 / 1.4.6
+
+| Rule | Impact | Description |
+|---|---|---|
+| `color-contrast-text` | serious | Normal text must meet 4.5:1 contrast ratio |
+| `color-contrast-large-text` | serious | Large text must meet 3:1 contrast ratio |
+
+### Forms — WCAG 1.3.1, 1.3.5, 3.3.1, 3.3.2, 4.1.2
+
+| Rule | Impact | Description |
+|---|---|---|
+| `label-missing` | critical | Form inputs must have an associated label |
+| `label-empty` | serious | `<label>` elements must have text content |
+| `error-identification` | serious | Invalid inputs must link to an error message via `aria-describedby` |
+| `input-button-name` | critical | Input buttons must have a discernible label |
+| `fieldset-legend` | moderate | `<fieldset>` must have a `<legend>` with text |
+| `autocomplete` | moderate | Common fields (name, email, phone) should declare `autocomplete` |
+| `form-field-required-label` | moderate | Required inputs should expose state via `aria-required` |
+
+### Keyboard — WCAG 2.1.1, 2.4.1, 2.4.3, 2.4.7
+
+| Rule | Impact | Description |
+|---|---|---|
+| `no-positive-tabindex` | serious | `tabindex` > 0 disrupts natural tab order |
+| `interactive-not-focusable` | serious | Clickable `div`/`span` elements must be keyboard accessible |
+| `skip-link` | moderate | Pages should have a skip navigation link |
+| `focus-visible` | serious | Focusable elements must not hide the focus indicator |
+| `scrollable-region-focusable` | moderate | Scrollable regions must be keyboard reachable |
+| `accesskey-unique` | moderate | `accesskey` values must be unique per page |
+
+### ARIA — WCAG 4.1.2
+
+| Rule | Impact | Description |
+|---|---|---|
+| `aria-valid-role` | critical | Elements must use valid ARIA roles |
+| `aria-required-attr` | critical | Roles must include all required attributes |
+| `aria-hidden-focus` | serious | `aria-hidden` elements must not be focusable |
+| `button-name` | critical | Buttons must have an accessible name |
+| `aria-required-children` | serious | Roles must contain required child roles |
+| `aria-required-parent` | serious | Roles must be inside a required parent role |
+| `aria-prohibited-attr` | moderate | ARIA attributes must be allowed on the element |
+
+### Structure — WCAG 1.3.1, 2.4.2, 4.1.1
+
+| Rule | Impact | Description |
+|---|---|---|
+| `heading-order` | moderate | Heading levels must not skip (e.g. h1 → h4) |
+| `page-title` | serious | Pages must have a non-empty `<title>` |
+| `landmark-one-main` | moderate | Page must have exactly one `<main>` landmark |
+| `list-structure` | serious | `<li>`, `<dt>`, `<dd>` must be inside the correct parent |
+| `region-landmark` | moderate | Content must be inside a landmark region |
+| `duplicate-id` | serious | `id` attributes must be unique per page |
+| `frame-title` | serious | `<iframe>` elements must have a `title` attribute |
+| `meta-viewport` | critical | Viewport must not block user scaling |
+| `marquee` | serious | `<marquee>` is deprecated and inaccessible |
+| `p-as-heading` | moderate | Paragraphs styled as headings should use heading elements |
+
+### Links — WCAG 2.4.4, 2.4.9
+
+| Rule | Impact | Description |
+|---|---|---|
+| `link-name` | serious | Links must have descriptive text (not "click here", "read more") |
+| `link-empty` | critical | Links must not be empty |
+| `identical-links-different-purpose` | moderate | Links with the same text must go to the same destination |
+| `link-new-window-warn` | moderate | Links opening a new tab must warn users |
+
+### Media — WCAG 1.2.2, 1.2.3, 1.2.5
+
+| Rule | Impact | Description |
+|---|---|---|
+| `video-captions` | critical | `<video>` elements must have a captions track |
+| `audio-description` | serious | Videos must have an audio description track |
+| `audio-transcript` | serious | `<audio>` elements must have a transcript |
+
+### Tables — WCAG 1.3.1
+
+| Rule | Impact | Description |
+|---|---|---|
+| `table-headers` | serious | Data tables must have `<th>` header cells |
+| `table-scope-valid` | moderate | `scope` attribute values must be valid |
+| `td-headers-attr` | serious | `headers` attribute must reference valid `th` IDs |
+| `table-duplicate-name` | minor | Table `summary` must not duplicate the `<caption>` |
+
+### Language — WCAG 3.1.1
+
+| Rule | Impact | Description |
+|---|---|---|
+| `html-lang` | serious | `<html>` must have a `lang` attribute |
+| `html-lang-valid` | serious | `lang` attribute must be a valid BCP 47 language tag |
+
+---
+
+## Use in CI/CD
+
+```yaml
+# .github/workflows/a11y.yml
+steps:
+  - name: Start dev server
+    run: npm run dev &
+
+  - name: Wait for server
+    run: npx wait-on http://localhost:3000
+
+  - name: Accessibility audit
+    run: npx wcag-a11y scan -u http://localhost:3000 --no-ai --ci
+```
+
+Exits `0` when clean, `1` when violations are found — gates merges on accessibility.

package/dist/ai/gemini.js

@@ -1,15 +1,17 @@
 import { buildPrompt } from './prompt.js';
+import { groupViolations } from './group.js';
 export class GeminiProvider {
     apiKey;
     model;
-    constructor(apiKey, model = 'gemini-2.0-flash') {
+    constructor(apiKey, model = 'gemini-2.5-flash') {
         this.apiKey = apiKey;
         this.model = model;
     }
-    async generateFixes(violations) {
+    async generateFixes(violations, strategy = 'rule') {
         if (violations.length === 0)
             return [];
-        const prompt = buildPrompt(violations);
+        const groups = groupViolations(violations, strategy);
+        const prompt = buildPrompt(groups);
         const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`;
         const response = await fetch(url, {
             method: 'POST',
@@ -24,34 +26,38 @@ export class GeminiProvider {
         }
         const data = await response.json();
         const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? '[]';
-        return this.parse(text, violations);
+        return this.parse(text, groups);
     }
-    parse(text, violations) {
+    parse(text, groups) {
         try {
             const jsonMatch = text.match(/\[[\s\S]*\]/);
             const fixes = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
-            return violations.map((v) => {
-                const found = fixes.find((f) => f.ruleId === v.ruleId && f.selector === v.selector)
-                    ?? fixes.find((f) => f.ruleId === v.ruleId);
-                return found ?? {
-                    ruleId: v.ruleId,
-                    selector: v.selector,
-                    explanation: v.description,
-                    fixedCode: v.html,
-                    wcagReference: `WCAG 2.1 SC ${v.wcag}`,
-                    optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
-                };
+            return groups.map((g) => {
+                const found = fixes.find((f) => f.ruleId === g.ruleId);
+                return found
+                    ? { ...found, selectors: g.selectors, instanceCount: g.count }
+                    : this.fallbackFix(g);
             });
         }
         catch {
-            return violations.map((v) => ({
-                ruleId: v.ruleId,
-                selector: v.selector,
-                explanation: v.description,
-                fixedCode: v.html,
-                wcagReference: `WCAG 2.1 SC ${v.wcag}`,
-                optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
-            }));
+            return groups.map((g) => this.fallbackFix(g));
         }
     }
+    fallbackFix(g) {
+        const v = g.representative;
+        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,
+            fixedCode: v.html,
+            wcagReference: `WCAG 2.1 SC ${g.wcag}`,
+            optimalPrompt: prompt,
+        };
+    }
 }

package/dist/ai/group.js

@@ -0,0 +1,37 @@
+export function groupViolations(violations, strategy) {
+    if (strategy === 'none') {
+        return violations.map((v) => ({
+            ruleId: v.ruleId,
+            wcag: v.wcag,
+            level: v.level,
+            impact: v.impact,
+            description: v.description,
+            page: v.page,
+            representative: v,
+            selectors: [v.selector],
+            count: 1,
+        }));
+    }
+    const map = new Map();
+    for (const v of violations) {
+        const existing = map.get(v.ruleId);
+        if (existing) {
+            existing.selectors.push(v.selector);
+            existing.count++;
+        }
+        else {
+            map.set(v.ruleId, {
+                ruleId: v.ruleId,
+                wcag: v.wcag,
+                level: v.level,
+                impact: v.impact,
+                description: v.description,
+                page: v.page,
+                representative: v,
+                selectors: [v.selector],
+                count: 1,
+            });
+        }
+    }
+    return Array.from(map.values());
+}

package/dist/ai/index.js

@@ -1,9 +1,17 @@
 import { GeminiProvider } from './gemini.js';
 import { OllamaProvider } from './ollama.js';
+import { OpenAIProvider } from './openai.js';
 export function createAIProvider(config) {
     if (config.provider === 'ollama') {
         return new OllamaProvider(config.ollamaBaseUrl, config.ollamaModel);
     }
+    if (config.provider === 'openai') {
+        if (!config.openaiApiKey) {
+            console.error('No OpenAI API key found. Add "openaiApiKey" to a11y.config.json.');
+            process.exit(1);
+        }
+        return new OpenAIProvider(config.openaiApiKey, config.openaiModel);
+    }
     if (!config.apiKey) {
         console.error('No API key found. Run: wcag-a11y init');
         process.exit(1);

package/dist/ai/ollama.js

@@ -1,4 +1,5 @@
 import { buildPrompt } from './prompt.js';
+import { groupViolations } from './group.js';
 export class OllamaProvider {
     baseUrl;
     model;
@@ -6,10 +7,11 @@ export class OllamaProvider {
         this.baseUrl = baseUrl;
         this.model = model;
     }
-    async generateFixes(violations) {
+    async generateFixes(violations, strategy = 'rule') {
         if (violations.length === 0)
             return [];
-        const prompt = buildPrompt(violations);
+        const groups = groupViolations(violations, strategy);
+        const prompt = buildPrompt(groups);
         const response = await fetch(`${this.baseUrl}/api/generate`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -23,33 +25,37 @@ export class OllamaProvider {
         try {
             const jsonMatch = text.match(/\[[\s\S]*\]/);
             if (!jsonMatch)
-                return this.fallback(violations);
+                return this.fallback(groups);
             const fixes = JSON.parse(jsonMatch[0]);
-            return violations.map((v) => {
-                const found = fixes.find((f) => f.ruleId === v.ruleId && f.selector === v.selector)
-                    ?? fixes.find((f) => f.ruleId === v.ruleId);
-                return found ?? {
-                    ruleId: v.ruleId,
-                    selector: v.selector,
-                    explanation: v.description,
-                    fixedCode: v.html,
-                    wcagReference: `WCAG 2.1 SC ${v.wcag}`,
-                    optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
-                };
+            return groups.map((g) => {
+                const found = fixes.find((f) => f.ruleId === g.ruleId);
+                return found
+                    ? { ...found, selectors: g.selectors, instanceCount: g.count }
+                    : this.fallbackFix(g);
             });
         }
         catch {
-            return this.fallback(violations);
+            return this.fallback(groups);
         }
     }
-    fallback(violations) {
-        return violations.map((v) => ({
-            ruleId: v.ruleId,
-            selector: v.selector,
-            explanation: v.description,
+    fallback(groups) {
+        return groups.map((g) => this.fallbackFix(g));
+    }
+    fallbackFix(g) {
+        const v = g.representative;
+        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,
             fixedCode: v.html,
-            wcagReference: `WCAG 2.1 SC ${v.wcag}`,
-            optimalPrompt: `Fix this accessibility violation: The element \`${v.html.slice(0, 120)}\` at selector \`${v.selector}\` violates ${v.wcag} — ${v.description}. Please fix it in the codebase.`,
-        }));
+            wcagReference: `WCAG 2.1 SC ${g.wcag}`,
+            optimalPrompt: prompt,
+        };
     }
 }

package/dist/ai/openai.js

@@ -0,0 +1,67 @@
+import { buildPrompt } from './prompt.js';
+import { groupViolations } from './group.js';
+export class OpenAIProvider {
+    apiKey;
+    model;
+    constructor(apiKey, model = 'gpt-4o-mini') {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async generateFixes(violations, strategy = 'rule') {
+        if (violations.length === 0)
+            return [];
+        const groups = groupViolations(violations, strategy);
+        const prompt = buildPrompt(groups);
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.model,
+                messages: [{ role: 'user', content: prompt }],
+                temperature: 0.2,
+                max_tokens: 8192,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI API error: ${response.status} ${await response.text()}`);
+        }
+        const data = await response.json();
+        const text = data.choices?.[0]?.message?.content ?? '[]';
+        return this.parse(text, groups);
+    }
+    parse(text, groups) {
+        try {
+            const jsonMatch = text.match(/\[[\s\S]*\]/);
+            const fixes = jsonMatch ? JSON.parse(jsonMatch[0]) : [];
+            return groups.map((g) => {
+                const found = fixes.find((f) => f.ruleId === g.ruleId);
+                return found
+                    ? { ...found, selectors: g.selectors, instanceCount: g.count }
+                    : this.fallbackFix(g);
+            });
+        }
+        catch {
+            return groups.map((g) => this.fallbackFix(g));
+        }
+    }
+    fallbackFix(g) {
+        const v = g.representative;
+        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,
+            fixedCode: v.html,
+            wcagReference: `WCAG 2.1 SC ${g.wcag}`,
+            optimalPrompt: prompt,
+        };
+    }
+}

package/dist/ai/prompt.js

@@ -1,17 +1,20 @@
-export function buildPrompt(violations) {
-    const items = violations
-        .map((v, i) => `${i + 1}. Rule: ${v.ruleId} | WCAG ${v.wcag} (Level ${v.level}) | Impact: ${v.impact}
-   Page: ${v.page}
-   Element: ${v.html}
-   Problem: ${v.description}`)
+export function buildPrompt(groups) {
+    const items = groups
+        .map((g, i) => `${i + 1}. Rule: ${g.ruleId} | WCAG ${g.wcag} (Level ${g.level}) | Impact: ${g.impact}
+   Page: ${g.page}
+   Instances: ${g.count} element(s)
+   Selectors: ${g.selectors.join(', ')}
+   Representative Element: ${g.representative.html}
+   Problem: ${g.description}`)
         .join('\n\n');
     return `You are a WCAG accessibility expert. Analyze these violations and return a JSON array.
 Each item must have:
 - "ruleId": the rule id from the input
-- "explanation": 1-2 sentences explaining why this matters for users with disabilities (plain English, no jargon)
+- "selectors": array of CSS selectors affected (copy from input)
+- "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 element, what rule it breaks, 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,12 +11,13 @@ const program = new Command();
 program
     .name('wcag-a11y')
     .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
-    .version('0.1.0');
+    .version('0.3.0');
 program
     .command('init')
     .description('Create a11y.config.json in the current directory')
-    .action(() => {
-    initConfig();
+    .option('--provider <name>', 'AI provider to configure (gemini|openai|ollama)', 'gemini')
+    .action((opts) => {
+    initConfig(opts.provider);
 });
 program
     .command('scan')
@@ -25,24 +27,44 @@ program
     .option('-c, --crawl', 'Auto-discover pages by following same-origin links', false)
     .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)')
     .action(async (opts) => {
     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();
+            if (opts.provider) {
+                config.provider = opts.provider;
+            }
             const provider = createAIProvider(config);
             const allViolations = result.pages.flatMap((p) => p.violations);
-            console.log(`\nGenerating AI fixes for ${allViolations.length} violations...`);
-            const fixes = await provider.generateFixes(allViolations);
-            printAIPrompts(fixes);
+            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);
+            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);
         }
     }
     catch (err) {

package/dist/config.js

@@ -3,9 +3,10 @@ import { join } from 'path';
 const CONFIG_FILE = 'a11y.config.json';
 const DEFAULTS = {
     provider: 'gemini',
-    model: 'gemini-2.0-flash',
+    model: 'gemini-2.5-flash',
     ollamaBaseUrl: 'http://localhost:11434',
     ollamaModel: 'llama3',
+    openaiModel: 'gpt-4o-mini',
 };
 export function loadConfig() {
     const configPath = join(process.cwd(), CONFIG_FILE);
@@ -16,17 +17,27 @@ export function loadConfig() {
     const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
     return { ...DEFAULTS, ...raw };
 }
-export function initConfig() {
+const STARTER_CONFIGS = {
+    gemini: [
+        { provider: 'gemini', apiKey: 'YOUR_GEMINI_API_KEY', model: 'gemini-2.5-flash' },
+        `Created ${CONFIG_FILE} — add your Gemini API key from https://aistudio.google.com`,
+    ],
+    openai: [
+        { provider: 'openai', openaiApiKey: 'YOUR_OPENAI_API_KEY', openaiModel: 'gpt-4o-mini' },
+        `Created ${CONFIG_FILE} — add your OpenAI API key from https://platform.openai.com/api-keys`,
+    ],
+    ollama: [
+        { provider: 'ollama', ollamaBaseUrl: 'http://localhost:11434', ollamaModel: 'llama3' },
+        `Created ${CONFIG_FILE} — run \`ollama serve\` to start the local model server`,
+    ],
+};
+export function initConfig(provider = 'gemini') {
     const configPath = join(process.cwd(), CONFIG_FILE);
     if (existsSync(configPath)) {
         console.log(`${CONFIG_FILE} already exists.`);
         return;
     }
-    const starter = {
-        provider: 'gemini',
-        apiKey: 'YOUR_GEMINI_API_KEY',
-        model: 'gemini-2.0-flash',
-    };
+    const [starter, message] = STARTER_CONFIGS[provider];
     writeFileSync(configPath, JSON.stringify(starter, null, 2));
-    console.log(`Created ${CONFIG_FILE} — add your Gemini API key from https://aistudio.google.com`);
+    console.log(message);
 }

package/dist/demo.js

@@ -74,8 +74,8 @@ export async function runDemo(opts) {
             const provider = createAIProvider(config);
             const violations = result.pages.flatMap((p) => p.violations);
             console.log(`\nGenerating AI fixes for ${violations.length} violations...`);
-            const fixes = await provider.generateFixes(violations);
-            printAIPrompts(fixes);
+            const fixes = await provider.generateFixes(violations, 'rule');
+            printAIPrompts(fixes, { explain: true });
             if (opts.report)
                 generateMarkdownReport(result, fixes);
         }

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()}`,
@@ -29,7 +53,7 @@ export function generateMarkdownReport(result, fixes, outputPath = 'a11y-report.
             continue;
         }
         for (const v of page.violations) {
-            const fix = fixes.find((f) => f.ruleId === v.ruleId && v.selector.includes(f.selector?.split(' ')[0] ?? ''));
+            const fix = fixes.find((f) => f.ruleId === v.ruleId);
             lines.push(`### ${IMPACT_EMOJI[v.impact] ?? '⚪'} [${v.impact.toUpperCase()}] ${v.description}`, '', `**Rule:** \`${v.ruleId}\`  `, `**WCAG:** ${fix?.wcagReference ?? `SC ${v.wcag} (Level ${v.level})`}  `, `**Selector:** \`${v.selector}\``, '', '**Violating element:**', '```html', v.html, '```', '');
             if (fix) {
                 lines.push('**Why it matters:**', fix.explanation, '', '**Fixed code:**', '```html', fix.fixedCode, '```', '', '**📋 Prompt for your AI assistant (Cursor / Copilot / Claude):**', '```', fix.optimalPrompt, '```', '');
@@ -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,27 +23,44 @@ 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)));
     console.log(`Total: ${chalk.red(result.criticalCount + ' critical')} · ${chalk.yellow(result.seriousCount + ' serious')} · ${chalk.blue(result.moderateCount + ' moderate')}`);
     console.log(chalk.gray('Run with --report to save a full markdown report with AI fix suggestions.\n'));
 }
-export function printAIPrompts(fixes) {
+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) {
-        const header = chalk.bold(`[${fix.ruleId}]`) + (fix.selector ? chalk.gray(` ${fix.selector}`) : '');
-        console.log('\n' + header);
-        if (fix.explanation) {
+        const countLabel = fix.instanceCount > 1 ? chalk.gray(` × ${fix.instanceCount} instances`) : '';
+        console.log('\n' + chalk.bold(`[${fix.ruleId}]`) + countLabel);
+        for (const sel of fix.selectors) {
+            console.log(chalk.gray(`  → ${sel}`));
+        }
+        if (opts.explain && fix.explanation) {
             console.log(chalk.gray(fix.explanation));
         }
         console.log(chalk.cyan('┌─ Copy this prompt ──────────────────────────────────────'));

package/package.json

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