wcag-a11y 0.4.0 → 0.4.1

package/README.md

@@ -2,17 +2,17 @@
 
 [![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 ready-to-paste fix prompts **or write the fixes directly into your source files**.
+Most accessibility auditors stop at detection — they tell you *what* is broken and leave the rest to you. `wcag-a11y` crawls your running dev server with Playwright, runs 40+ WCAG 2.1/2.2 checks, and uses AI to generate ready-to-paste fix prompts **or write the fixes directly into your source files**.
 
 Two modes:
-- **`scan`** — find violations + generate AI prompts you paste into Cursor, Copilot, or Claude
+- **`scan`** — find violations + get AI prompts you paste into Cursor, Copilot, or Claude
 - **`fix`** — find violations + patch source files automatically (dry-run by default, `--apply` to write)
 
 ---
 
 ## Try it instantly
 
-No dev server, no config, no setup:
+No dev server, no config:
 
 ```bash
 npx wcag-a11y demo
@@ -22,41 +22,50 @@ 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.
-────────────────────────────────────────────
+WCAG A11y — scan complete
+────────────────────────────────────────────────────────────
+
+  ✖  http://localhost:3000  3 critical  4 serious  3 moderate
+
+     [CRITICAL] Images must have an alt attribute  WCAG 1.1.1
+     → img
+     [CRITICAL] Form inputs must have an associated label  WCAG 1.3.1
+     → input[type="email"]
+     [CRITICAL] Buttons must have an accessible name  WCAG 4.1.2
+     → button[type="submit"]
+     [SERIOUS]  Normal text must meet 4.5:1 contrast ratio  WCAG 1.4.3
+     → p
+     [SERIOUS]  Links must have descriptive text  WCAG 2.4.4
+     → a[href="/sale"]
+     … and 5 more
+
+────────────────────────────────────────────────────────────
+Total: 3 critical · 4 serious · 3 moderate
+
+AI Fix Prompts — paste any of these into Cursor, Copilot, or Claude
+────────────────────────────────────────────────────────────
+
+[img-alt]
+  → img
+  Screen reader users hear nothing for this image — branding, instructions,
+  or data it conveys is completely invisible to them.
+┌─ Copy this prompt ──────────────────────────────────────
+│ Fix WCAG 1.1.1 (Level A) — img is missing an alt attribute
+│
+│ Current HTML:
+│   <img src="banner.jpg">
+│
+│ How to fix:
+│   Add alt text describing the image content.
+│   Use alt="" if the image is purely decorative.
+│   Example: <img src="banner.jpg" alt="Summer sale — 50% off">
+└─────────────────────────────────────────────────────────
+
+… 9 more prompts — full report saved to a11y-report.md
 ```
 
-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.
-
-The full output is saved to `a11y-report.md` by default. Pass `--no-report` to skip.
+Each prompt tells you the WCAG criterion, shows the broken element, and gives the exact fix — ready to paste into your AI editor.
 
 ---
 
@@ -66,61 +75,21 @@ The full output is saved to `a11y-report.md` by default. Pass `--no-report` to s
 npm install -g wcag-a11y
 ```
 
-## Setup
+## Quick start
 
 ```bash
-wcag-a11y init                            # Gemini (free, default)
-wcag-a11y init --provider openai          # OpenAI
-wcag-a11y init --provider anthropic       # Anthropic Claude
-wcag-a11y init --provider mistral         # Mistral
-wcag-a11y init --provider groq            # Groq (fast inference)
-wcag-a11y init --provider cohere          # Cohere
-wcag-a11y init --provider xai             # xAI Grok
-wcag-a11y init --provider deepseek        # DeepSeek
-wcag-a11y init --provider together        # Together AI (open-source models)
-wcag-a11y init --provider perplexity      # Perplexity
-wcag-a11y init --provider azure-openai    # Azure 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.
-
----
-
-## Commands
+# 1. Configure your AI provider (Gemini is free, no credit card)
+wcag-a11y init
 
-### `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 --no-report      # skip saving a11y-report.md
+# 2. Start your dev server, then scan
+wcag-a11y scan -u http://localhost:3000
 ```
 
-| Flag | Description |
-|---|---|
-| `--no-ai` | Skip AI fix generation — prints violations only, no prompts |
-| `--no-report` | Skip saving report to `a11y-report.md` (report is saved by default) |
+Add `--pages / /about /contact` to scan specific routes, or `--crawl` to follow links automatically.
 
 ---
 
-### `wcag-a11y init`
-
-Create `a11y.config.json` in the current directory, pre-configured for your chosen provider.
-
-```bash
-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. Valid values: `gemini` (default), `openai`, `anthropic`, `mistral`, `groq`, `cohere`, `xai`, `deepseek`, `together`, `perplexity`, `azure-openai`, `ollama`. Determines which fields are written to the config file. |
-
----
+## Commands
 
 ### `wcag-a11y scan`
 
@@ -137,16 +106,16 @@ wcag-a11y scan -u http://localhost:3000 --terminal --fast-mode
 | 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 |
-| `--no-report` | on | Skip saving scan output to `a11y-report.md` (report is saved by default) |
-| `--no-ai` | on | Skip AI fix generation — scan runs faster and prints violations only |
-| `--no-explain` | on | Print only the ready-to-paste prompt for each fix, without the AI explanation |
-| `--terminal` | off | Print violations summary and AI fix prompts to terminal |
-| `--fast-mode` | off | Output only AI fix prompts — no summaries, explanations, or progress messages |
-| `--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. See [AI Providers](#ai-providers) for valid names. Does not modify the config file |
+| `-p, --pages <paths...>` | `/` | Paths to scan. Space-separated: `--pages / /about /contact` |
+| `-c, --crawl` | off | Follow same-origin links and scan all reachable pages |
+| `--no-ai` | — | Skip AI fix generation — scan runs faster, violations only |
+| `--no-report` | — | Skip saving `a11y-report.md` |
+| `--no-explain` | — | Omit explanations, show prompts only |
+| `--terminal` | off | Print violations and AI prompts to terminal |
+| `--fast-mode` | off | Output only the raw prompts — no summaries or decoration |
+| `--group <strategy>` | `rule` | `rule`: one prompt per rule type. `none`: one prompt per element |
+| `--ci` | off | Exit with code `1` if any violations are found |
+| `--provider <name>` | from config | Override AI provider for this run |
 
 ---
 
@@ -155,34 +124,13 @@ wcag-a11y scan -u http://localhost:3000 --terminal --fast-mode
 Scan for violations and apply AI-generated patches directly to your source files. Works with any framework — React, Vue, Angular, Svelte, or plain HTML.
 
 ```bash
-# Dry-run: scan and show what would change (safe, no files written)
-wcag-a11y fix -u http://localhost:3000
-
-# Preview specific pages
-wcag-a11y fix -u http://localhost:3000 --pages / /about /contact
-
-# Write fixes to disk
-wcag-a11y fix -u http://localhost:3000 --apply
-
-# Auto-discover pages + write fixes
-wcag-a11y fix -u http://localhost:3000 --crawl --apply
-
-# Skip rescanning — load violations from an existing report
-wcag-a11y fix --from-report
-wcag-a11y fix --from-report ./reports/a11y-report.md --apply
+wcag-a11y fix -u http://localhost:3000               # dry-run: show diff, nothing written
+wcag-a11y fix -u http://localhost:3000 --apply       # write fixes to disk
+wcag-a11y fix --from-report --apply                  # patch from an existing report
 ```
 
-**How it works:**
-
-1. Runs the same scan as `wcag-a11y scan` (or loads an existing report with `--from-report`)
-2. For each violation, locates the source file — checks `violation.source` (React dev mode) first, then falls back to grepping `./src` for unique identifiers in the HTML snippet (`id=`, `name=`, `for=`, local `src=`, text content)
-3. Groups violations by file (multiple violations in the same file → one AI call)
-4. Sends the full file content + violation list to your configured AI provider and asks for the corrected file
-5. Shows a colored diff before writing anything
-6. With `--apply`, overwrites the file; without it, only prints the diff
-
 ```
-src/components/Navbar.jsx — 2 violation(s)
+src/components/Navbar.jsx — 2 violations
   · [button-name] Buttons must have an accessible name
   · [aria-valid-role] Elements must use valid ARIA roles
 
@@ -196,52 +144,85 @@ src/components/Navbar.jsx — 2 violation(s)
   +     <li>Home</li>
 ```
 
+**Common workflow:** scan first to review, then patch:
+
+```bash
+wcag-a11y scan -u http://localhost:3000   # generates a11y-report.md
+wcag-a11y fix --from-report --apply       # patches files from that report, no second crawl
+```
+
 | Flag | Default | Description |
 |---|---|---|
-| `-u, --url <url>` | — | Base URL of your running dev server. Required unless `--from-report` is used |
-| `-p, --pages <pages...>` | `/` | Specific pages to scan |
+| `-u, --url <url>` | — | Base URL. Required unless `--from-report` is used |
+| `-p, --pages <paths...>` | `/` | Paths to scan |
 | `-c, --crawl` | off | Auto-discover pages by following same-origin links |
-| `--from-report [path]` | `a11y-report.md` | Load violations from an existing report instead of scanning. Useful when you already ran `scan --report` and just want to apply fixes |
-| `--apply` | off | Write patched files to disk (dry-run without this flag) |
-| `--provider <name>` | from config | Override AI provider for this run. See [AI Providers](#ai-providers) for valid names |
+| `--from-report [path]` | `a11y-report.md` | Load violations from an existing report instead of rescanning |
+| `--apply` | off | Write fixes to disk (dry-run without this flag) |
+| `--provider <name>` | from config | Override AI provider for this run |
+
+---
 
-> **Tip:** Always run without `--apply` first to review the diff. The dry-run is safe — nothing is written to disk.
+### `wcag-a11y init`
 
-**Common workflow:** run `scan --report` to generate a report for review, then run `fix --from-report --apply` to patch the files — no second browser crawl needed.
+Create `a11y.config.json` pre-configured for your chosen provider.
 
 ```bash
-wcag-a11y scan -u http://localhost:3000            # generates a11y-report.md automatically
-wcag-a11y fix --from-report --apply                # patch files from that report
+wcag-a11y init                          # Gemini (free, default)
+wcag-a11y init --provider openai
+wcag-a11y init --provider anthropic
+wcag-a11y init --provider ollama        # local — no API key needed
+# … and 8 more providers
+```
+
+---
+
+### `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 fix prompts (requires config)
+wcag-a11y demo --no-ai  # violations only, no AI
 ```
 
 ---
 
 ## AI Providers
 
-12 providers are supported. Set your provider in `a11y.config.json` or override per-run with `--provider <name>`.
+12 providers supported. Configure once in `a11y.config.json`, or override per-run with `--provider`.
 
-| Provider | `--provider` name | Default model | API key source |
+| Provider | `--provider` | Default model | Notes |
 |---|---|---|---|
-| Google Gemini | `gemini` *(default)* | `gemini-2.5-flash` | [aistudio.google.com](https://aistudio.google.com) — free tier |
-| OpenAI | `openai` | `gpt-4o-mini` | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
-| Anthropic | `anthropic` | `claude-sonnet-4-6` | [console.anthropic.com](https://console.anthropic.com) |
-| Mistral | `mistral` | `mistral-large-latest` | [console.mistral.ai](https://console.mistral.ai) |
-| Groq | `groq` | `llama-3.3-70b-versatile` | [console.groq.com](https://console.groq.com) |
-| Cohere | `cohere` | `command-r-plus` | [dashboard.cohere.com](https://dashboard.cohere.com) |
-| xAI | `xai` | `grok-2` | [console.x.ai](https://console.x.ai) |
-| DeepSeek | `deepseek` | `deepseek-chat` | [platform.deepseek.com](https://platform.deepseek.com) |
-| Together AI | `together` | `meta-llama/Llama-3-70b-chat-hf` | [api.together.xyz](https://api.together.xyz) |
-| Perplexity | `perplexity` | `llama-3.1-sonar-large-128k-online` | [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) |
-| Azure OpenAI | `azure-openai` | *(your deployment)* | [portal.azure.com](https://portal.azure.com) |
-| Ollama | `ollama` | `llama3` | None — run `ollama serve` locally |
-
-All models are configurable. Change the model field in `a11y.config.json` to use any model your API key has access to. If the AI response is unparseable, the tool generates a fix prompt directly from the violation data so you always get something actionable.
+| Google Gemini | `gemini` *(default)* | `gemini-2.5-flash` | Free tier available |
+| OpenAI | `openai` | `gpt-4o-mini` | |
+| Anthropic | `anthropic` | `claude-sonnet-4-6` | |
+| Mistral | `mistral` | `mistral-large-latest` | |
+| Groq | `groq` | `llama-3.3-70b-versatile` | Fast inference |
+| Cohere | `cohere` | `command-r-plus` | |
+| xAI | `xai` | `grok-2` | |
+| DeepSeek | `deepseek` | `deepseek-chat` | |
+| Together AI | `together` | `meta-llama/Llama-3-70b-chat-hf` | Open-source models |
+| Perplexity | `perplexity` | `llama-3.1-sonar-large-128k-online` | |
+| Azure OpenAI | `azure-openai` | *(your deployment)* | |
+| Ollama | `ollama` | `llama3` | Local — no API key |
+
+All models are configurable. If the AI response is unparseable, the tool generates a fix prompt directly from the violation data — you always get something actionable.
 
 ---
 
-## Config (`a11y.config.json`)
+## Config
 
-Only the fields for your active `provider` are required. This file is gitignored by default.
+Run `wcag-a11y init` to generate `a11y.config.json`. Only fill in the fields for your chosen provider. This file is gitignored by default.
+
+```json
+{
+  "provider": "gemini",
+  "apiKey": "YOUR_GEMINI_API_KEY"
+}
+```
+
+<details>
+<summary>Full config reference (all 12 providers)</summary>
 
 ```json
 {
@@ -287,11 +268,16 @@ Only the fields for your active `provider` are required. This file is gitignored
 }
 ```
 
+</details>
+
 ---
 
 ## What it checks
 
-40+ rules across 10 categories, mapped to WCAG 2.1/2.2 success criteria.
+40+ rules across 10 WCAG 2.1/2.2 categories: Text Alternatives, Color Contrast, Forms, Keyboard, ARIA, Structure, Links, Media, Tables, and Language.
+
+<details>
+<summary>Full rule list</summary>
 
 ### Text Alternatives — WCAG 1.1.1
 
@@ -394,6 +380,8 @@ Only the fields for your active `provider` are required. This file is gitignored
 | `html-lang` | serious | `<html>` must have a `lang` attribute |
 | `html-lang-valid` | serious | `lang` attribute must be a valid BCP 47 language tag |
 
+</details>
+
 ---
 
 ## Use in CI/CD

package/dist/ai/base.js

@@ -1,4 +1,5 @@
 import { fallbackExplanation } from './fallback-explanation.js';
+import { getFix, getFixCategory } from './fallback-fix.js';
 export class BaseAIProvider {
     parse(text, groups, framework) {
         try {
@@ -7,7 +8,7 @@ export class BaseAIProvider {
             return groups.map((g) => {
                 const found = fixes.find((f) => f.ruleId === g.ruleId);
                 return found
-                    ? { ...found, selectors: g.selectors, instanceCount: g.count }
+                    ? { ...found, selectors: g.selectors, instanceCount: g.count, fixCategory: getFixCategory(g.ruleId) }
                     : this.fallbackFix(g, framework);
             });
         }
@@ -20,18 +21,23 @@ export class BaseAIProvider {
     }
     fallbackFix(g, framework) {
         const v = g.representative;
-        const selectorList = g.selectors.map((s) => `- ${s}`).join('\n');
+        const selectorList = g.selectors.map((s) => `- \`${s}\``).join('\n');
         const explanation = fallbackExplanation(g.ruleId, g.description, g.wcag, g.level);
-        const fwNote = framework ? `This project uses ${framework}. ` : '';
+        const fwNote = framework ? `This project uses ${framework}.\n\n` : '';
+        const fixInstructions = getFix(g.ruleId);
+        const fixSection = fixInstructions ? `\n\nHow to fix:\n${fixInstructions}` : '';
         const prompt = g.count > 1
-            ? `${fwNote}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}.`
-            : `${fwNote}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}.`;
+            ? `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected elements (${g.count} instances):\n${selectorList}\n\nRepresentative HTML:\n\`\`\`html\n${v.html.slice(0, 400)}\n\`\`\`${fixSection}\n\nApply this fix to all ${g.count} instances across the codebase.`
+            : `${fwNote}Fix WCAG 2.1 SC ${g.wcag} (Level ${g.level}) — ${g.description}\n\nAffected element:\n- Selector: \`${g.selectors[0]}\`\n\nCurrent HTML:\n\`\`\`html\n${v.html.slice(0, 400)}\n\`\`\`${fixSection}`;
+        const category = getFixCategory(g.ruleId);
+        const fixedCode = category === 'edit-element' || !category ? v.html : undefined;
         return {
             ruleId: g.ruleId,
             selectors: g.selectors,
             instanceCount: g.count,
             explanation,
-            fixedCode: v.html,
+            fixedCode,
+            fixCategory: getFixCategory(g.ruleId),
             wcagReference: `WCAG 2.1 SC ${g.wcag}`,
             optimalPrompt: prompt,
         };

package/dist/ai/fallback-fix.js

@@ -0,0 +1,126 @@
+const RULE_FIX_INSTRUCTIONS = {
+    // Text alternatives
+    'img-alt': 'Add an `alt` attribute describing the image content. Use `alt=""` for decorative images.\nExample: `<img src="photo.jpg" alt="Team photo at the 2024 company retreat">`',
+    'input-image-alt': 'Add an `alt` attribute to the `<input type="image">` describing the button\'s action.\nExample: `<input type="image" src="submit.png" alt="Submit form">`',
+    'svg-title': 'Add a `<title>` element as the first child of `<svg>` and add `aria-labelledby` pointing to its `id`.\nExample: `<svg aria-labelledby="chartTitle" role="img"><title id="chartTitle">Monthly sales bar chart</title>...</svg>`',
+    'object-alt': 'Add descriptive fallback content inside the `<object>` tag, or use `aria-label`.\nExample: `<object data="report.pdf"><p>Download the Q4 2024 report (PDF)</p></object>`',
+    'role-img-alt': 'Add `aria-label` or `aria-labelledby` to the element with `role="img"`.\nExample: `<div role="img" aria-label="Star rating: 4 out of 5"></div>`',
+    'image-redundant-alt': 'Change the `alt` to `alt=""` (empty string) since the image\'s meaning is already conveyed by adjacent text — screen readers skip empty-alt images automatically.',
+    // Tables
+    'table-headers': 'Add `<th scope="col">` for column headers and `<th scope="row">` for row headers.\nExample: `<thead><tr><th scope="col">Name</th><th scope="col">Price</th></tr></thead>`',
+    'table-scope-valid': 'Change the `scope` attribute to a valid value: `"col"`, `"row"`, `"colgroup"`, or `"rowgroup"`. Remove it if the element is not a header.',
+    'td-headers-attr': 'Either add matching `id` attributes to the referenced `<th>` elements, or remove the invalid `headers` attributes from the `<td>` elements.',
+    'table-duplicate-name': 'Make the `<caption>` and `summary` convey different information: use `<caption>` for a short visible title and `summary` for an extended description, or remove the redundant attribute.',
+    // Structure
+    'heading-order': 'Restructure headings so levels are never skipped. Change the offending tag to the correct level (e.g., change `<h4>` directly under `<h2>` to `<h3>`). Use CSS for visual sizing — never pick heading levels for appearance.',
+    'page-title': 'Add or update `<title>` in `<head>` with a unique, descriptive title.\nUse the format: `<title>Page Name — Site Name</title>`',
+    'landmark-one-main': 'Wrap primary page content in exactly one `<main id="main-content">` element. Remove any duplicate `<main>` elements.',
+    'list-structure': 'Replace non-semantic markup with proper list structure.\nExample: change `<div class="item">` repeated items into `<ul><li>...</li><li>...</li></ul>` for unordered, or `<ol>` for ordered lists.',
+    'region-landmark': 'Wrap the content in the appropriate landmark element: `<header>`, `<nav aria-label="...">`, `<main>`, `<aside aria-label="...">`, or `<footer>`. For generic sections: `<section aria-label="Section name">`.',
+    'duplicate-id': 'Make each `id` unique across the page. If the ID is referenced by `aria-labelledby` or `aria-describedby`, update those references to match the new unique IDs. Append a suffix like `-nav`, `-footer`, or a number to disambiguate.',
+    'frame-title': 'Add a `title` attribute to the `<iframe>` describing its content.\nExample: `<iframe title="Product demo video" src="..."></iframe>`',
+    'meta-viewport': 'Remove `user-scalable=no` and ensure `maximum-scale` is not below 5.\nChange to: `<meta name="viewport" content="width=device-width, initial-scale=1">`',
+    'marquee': 'Replace `<marquee>` with a CSS-animated element. Respect `prefers-reduced-motion`:\n`@media (prefers-reduced-motion: reduce) { .marquee { animation: none; } }`\nProvide static fallback content for motion-sensitive users.',
+    'p-as-heading': 'Replace the visually bold `<p>` with the appropriate heading tag (`<h2>`, `<h3>`, etc.) matching its position in the document outline. Apply visual styles via CSS, not `<b>` or `<strong>` tags inside `<p>`.',
+    // Media
+    'video-captions': 'Add a `<track kind="captions">` element inside the `<video>` pointing to a WebVTT (.vtt) file.\nExample: `<track kind="captions" src="/captions-en.vtt" srclang="en" label="English" default>`',
+    'audio-description': 'Add a `<track kind="descriptions">` element inside `<video>` for audio descriptions.\nExample: `<track kind="descriptions" src="/descriptions-en.vtt" srclang="en" label="Audio description">`',
+    'audio-transcript': 'Provide a text transcript immediately after the `<audio>` element, either as a link or inline.\nExample: `<a href="/transcript.html">Read transcript</a>`',
+    // Links
+    'link-name': 'Add descriptive text inside the `<a>`, or use `aria-label` to describe the destination.\nExample: `<a href="/products" aria-label="View all products">View all</a>`. Avoid "click here" or "read more".',
+    'link-empty': 'Add descriptive text or `aria-label` to the empty anchor. If it is a decorative icon, add `aria-label`. If non-functional, remove the `<a>` element entirely.',
+    'identical-links-different-purpose': 'Add unique `aria-label` to each link to distinguish its destination.\nExample: `<a href="/product-a" aria-label="Read more about Product A">Read more</a>` and `<a href="/product-b" aria-label="Read more about Product B">Read more</a>`',
+    'link-new-window-warn': 'Add `rel="noopener noreferrer"` and warn users the link opens a new tab.\nExample: `<a href="..." target="_blank" rel="noopener noreferrer">Download PDF <span class="sr-only">(opens in new tab)</span></a>`',
+    // Forms
+    'label-missing': 'Add a `<label>` linked via `for`/`id`, or add `aria-label` directly to the input.\nExample: `<label for="user-email">Email address</label><input id="user-email" type="email">`',
+    'label-empty': 'Add descriptive text inside the existing `<label>`.\nExample: change `<label for="q"></label>` to `<label for="q">Search</label>`',
+    'error-identification': 'Link error messages to their fields using `aria-describedby` and add `role="alert"` to the error container.\nExample: `<input aria-describedby="email-error"><span id="email-error" role="alert">Please enter a valid email address</span>`',
+    'autocomplete': 'Add the correct `autocomplete` attribute to the input. Common values: `name`, `email`, `tel`, `current-password`, `new-password`, `given-name`, `family-name`, `street-address`, `postal-code`.\nExample: `<input type="email" autocomplete="email">`',
+    'input-button-name': 'Add a descriptive `value` to `<input type="button/submit/reset">` or `aria-label` to icon buttons.\nExample: `<input type="submit" value="Submit registration form">` or `<button aria-label="Search"><svg aria-hidden="true">...</svg></button>`',
+    'fieldset-legend': 'Wrap related controls in `<fieldset>` with `<legend>` as its first child.\nExample: `<fieldset><legend>Shipping address</legend><label>...</label><input>...</fieldset>`',
+    'form-field-required-label': 'Add `required` and `aria-required="true"` to the input. Indicate required status in the label text.\nExample: `<label for="name">Full name <span aria-hidden="true">*</span><span class="sr-only">(required)</span></label><input id="name" required aria-required="true">`',
+    // Language
+    'html-lang': 'Add a `lang` attribute to the `<html>` element with the correct BCP 47 language tag.\nExample: `<html lang="en">` for English, `<html lang="vi">` for Vietnamese, `<html lang="fr">` for French.',
+    'html-lang-valid': 'Replace the invalid `lang` value with a valid BCP 47 language tag.\nValid examples: `"en"`, `"en-US"`, `"fr"`, `"de"`, `"es"`, `"zh"`, `"ja"`, `"ko"`, `"vi"`, `"ar"`.',
+    // Color contrast
+    'color-contrast-text': 'Increase the contrast ratio between the text and background to at least 4.5:1. Darken the text color or lighten the background. Verify with the WebAIM Contrast Checker.\nExample: change `color: #999` on a white background to `color: #767676` (minimum passing value).',
+    'color-contrast-large-text': 'Increase the contrast ratio to at least 3:1 for large text (18pt/24px+ regular, or 14pt/18.67px+ bold). Adjust the text or background color and verify with a contrast checker.',
+    // Keyboard
+    'no-positive-tabindex': 'Remove the `tabindex` attribute or set it to `tabindex="0"`. Reorder DOM elements to create the correct focus sequence — never use positive tabindex values to manage tab order.',
+    'interactive-not-focusable': 'Add `role="button"` (or the correct role) and `tabindex="0"`. Add keyboard event handlers for Enter and Space to match the click handler.\nExample: `<div role="button" tabindex="0" onclick="handleClick()" onkeydown="if(event.key===\'Enter\'||event.key===\' \')handleClick()">`',
+    'skip-link': 'Add a skip link as the very first child of `<body>`:\n`<a href="#main-content" class="skip-link">Skip to main content</a>`\nEnsure the target exists: `<main id="main-content">` (add `id="main-content"` to your existing `<main>` element).\nAdd CSS: `.skip-link { position: absolute; left: -9999px; } .skip-link:focus { position: static; left: 0; top: 0; z-index: 9999; padding: 8px; background: #fff; color: #000; }`',
+    'focus-visible': 'Remove `outline: none` or `outline: 0` from `:focus` styles. Add a clearly visible focus indicator.\nExample: `a:focus-visible, button:focus-visible { outline: 3px solid #005fcc; outline-offset: 2px; }`. Never suppress focus outlines without an equally visible replacement.',
+    'scrollable-region-focusable': 'Add `tabindex="0"` to the scrollable container so keyboard users can focus and scroll it.\nExample: `<div class="overflow-auto" tabindex="0" aria-label="Scrollable content">...</div>`',
+    'accesskey-unique': 'Change duplicate `accesskey` values so each one is unique across the page. If shortcuts are not needed, remove the `accesskey` attribute entirely.',
+    // ARIA
+    'aria-valid-role': 'Remove the invalid `role` value or replace it with a valid WAI-ARIA role such as `button`, `checkbox`, `dialog`, `listbox`, `menu`, `menuitem`, `option`, `radio`, `tab`, `tabpanel`, or `tooltip`.',
+    'aria-required-attr': 'Add the missing required ARIA state or property for this role.\nExamples: `role="checkbox"` needs `aria-checked`; `role="combobox"` needs `aria-expanded`; `role="slider"` needs `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.',
+    'aria-hidden-focus': 'Remove `aria-hidden="true"` from any ancestor of a focusable element, or move `aria-hidden` to a sibling that contains no focusable descendants. Never place interactive elements inside `aria-hidden="true"` containers.',
+    'button-name': 'Add visible text content or `aria-label` to the `<button>`.\nExample: `<button aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>` or `<button>Submit order</button>`',
+    'aria-required-children': 'Add the required child elements with the correct ARIA roles inside this container.\nExamples: `role="listbox"` must contain `role="option"` children; `role="menu"` must contain `role="menuitem"` children; `role="grid"` must contain `role="row"` children.',
+    'aria-required-parent': 'Move this element inside its required ARIA parent container.\nExamples: `role="option"` must be inside `role="listbox"`; `role="tab"` must be inside `role="tablist"`; `role="menuitem"` must be inside `role="menu"`.',
+    'aria-prohibited-attr': 'Remove the prohibited ARIA attribute from this element. Elements with `role="presentation"` or `role="none"` must not have naming attributes like `aria-label` or `aria-labelledby`. Check the WAI-ARIA spec for the element\'s prohibited attributes.',
+};
+export function getFix(ruleId) {
+    return RULE_FIX_INSTRUCTIONS[ruleId];
+}
+const RULE_FIX_CATEGORY = {
+    // edit-element — fix targets the flagged element's own attributes or content
+    'img-alt': 'edit-element',
+    'input-image-alt': 'edit-element',
+    'svg-title': 'edit-element',
+    'object-alt': 'edit-element',
+    'role-img-alt': 'edit-element',
+    'image-redundant-alt': 'edit-element',
+    'table-scope-valid': 'edit-element',
+    'table-duplicate-name': 'edit-element',
+    'page-title': 'edit-element',
+    'frame-title': 'edit-element',
+    'meta-viewport': 'edit-element',
+    'p-as-heading': 'edit-element',
+    'heading-order': 'edit-element',
+    'duplicate-id': 'edit-element',
+    'link-name': 'edit-element',
+    'link-empty': 'edit-element',
+    'identical-links-different-purpose': 'edit-element',
+    'link-new-window-warn': 'edit-element',
+    'label-empty': 'edit-element',
+    'autocomplete': 'edit-element',
+    'input-button-name': 'edit-element',
+    'html-lang': 'edit-element',
+    'html-lang-valid': 'edit-element',
+    'no-positive-tabindex': 'edit-element',
+    'interactive-not-focusable': 'edit-element',
+    'scrollable-region-focusable': 'edit-element',
+    'accesskey-unique': 'edit-element',
+    'aria-valid-role': 'edit-element',
+    'aria-required-attr': 'edit-element',
+    'aria-prohibited-attr': 'edit-element',
+    'button-name': 'edit-element',
+    'aria-required-children': 'edit-element',
+    'video-captions': 'edit-element',
+    'audio-description': 'edit-element',
+    // add-elsewhere — fix inserts a new element at a different location
+    'skip-link': 'add-elsewhere',
+    'audio-transcript': 'add-elsewhere',
+    'label-missing': 'add-elsewhere',
+    'error-identification': 'add-elsewhere',
+    // change-css — fix lives in a stylesheet, not in the flagged element's markup
+    'color-contrast-text': 'change-css',
+    'color-contrast-large-text': 'change-css',
+    'focus-visible': 'change-css',
+    'marquee': 'change-css',
+    // restructure — fix touches multiple elements or wraps / moves content
+    'table-headers': 'restructure',
+    'td-headers-attr': 'restructure',
+    'landmark-one-main': 'restructure',
+    'list-structure': 'restructure',
+    'region-landmark': 'restructure',
+    'fieldset-legend': 'restructure',
+    'form-field-required-label': 'restructure',
+    'aria-hidden-focus': 'restructure',
+    'aria-required-parent': 'restructure',
+};
+export function getFixCategory(ruleId) {
+    return RULE_FIX_CATEGORY[ruleId];
+}

package/dist/ai/prompt.js

@@ -1,3 +1,4 @@
+import { getFix, getFixCategory } from './fallback-fix.js';
 const FRAMEWORK_SYNTAX = {
     'Next.js': 'React/TSX (JSX)',
     'Gatsby': 'React/JSX',
@@ -12,22 +13,28 @@ const FRAMEWORK_SYNTAX = {
 export function buildPrompt(groups, framework) {
     const syntax = framework ? (FRAMEWORK_SYNTAX[framework] ?? 'JSX/TSX') : null;
     const items = groups
-        .map((g, i) => `${i + 1}. Rule: ${g.ruleId} | WCAG ${g.wcag} (Level ${g.level}) | Impact: ${g.impact}
+        .map((g, i) => {
+        const fixHint = getFix(g.ruleId);
+        const category = getFixCategory(g.ruleId) ?? 'edit-element';
+        const fixLine = fixHint ? `\n   Fix guidance: ${fixHint}` : '';
+        const categoryLine = `\n   Fix type: ${category}`;
+        return `${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}`)
+   Problem: ${g.description}${categoryLine}${fixLine}`;
+    })
         .join('\n\n');
     const frameworkLine = framework
         ? `\nFramework: ${framework}. All "fixedCode" values must use ${syntax} syntax — not raw HTML.\n`
         : '';
     const fixedCodeInstruction = syntax
-        ? `"fixedCode": the corrected snippet in ${syntax} syntax (component/template code only — no imports, no surrounding boilerplate)`
-        : `"fixedCode": the corrected HTML snippet only (no explanation, just code)`;
+        ? `"fixedCode": include ONLY when the violation's "Fix type" is "edit-element". Show the corrected ${syntax} snippet — NOT a copy of the original broken element. Omit this field entirely for "add-elsewhere", "change-css", and "restructure" violations.`
+        : `"fixedCode": include ONLY when the violation's "Fix type" is "edit-element". Show the corrected HTML snippet — NOT a copy of the original broken element. Omit this field entirely for "add-elsewhere", "change-css", and "restructure" violations.`;
     const optimalPromptInstruction = framework
-        ? `"optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude) working in a ${framework} codebase. Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated, (2) list the affected selectors and HTML snippets, (3) state the exact change needed in ${syntax} syntax. Focus solely on the fix.`
-        : `"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, (2) list the affected selectors and HTML snippets, (3) state the exact change needed. Focus solely on the fix.`;
+        ? `"optimalPrompt": a ready-to-paste prompt for an AI coding assistant (Cursor, Copilot, Claude) working in a ${framework} codebase. Structure it as: (1) state the WCAG 2.1/2.2 criterion being violated, (2) quote the affected selector and current HTML, (3) provide the exact code change required in ${syntax} syntax — include a concrete before/after snippet or the specific element to add/modify/remove. The prompt must be actionable without requiring additional research.`
+        : `"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, (2) quote the affected selector and current HTML, (3) provide the exact code change required — include a concrete before/after snippet or the specific element to add/modify/remove. The prompt must be fully actionable: tell the developer exactly what to write, not just that something needs fixing.`;
     return `You are a WCAG accessibility expert. Analyze these violations and return a JSON array.${frameworkLine}
 Each item must have:
 - "ruleId": the rule id from the input

package/dist/cli.js

@@ -13,7 +13,7 @@ const program = new Command();
 program
     .name('wcag-a11y')
     .description('WCAG 2.1/2.2 accessibility auditor with AI-powered fixes')
-    .version('0.4.0');
+    .version('0.4.1');
 program
     .command('init')
     .description('Create a11y.config.json in the current directory')

package/dist/reporter/markdown.js

@@ -74,7 +74,11 @@ function buildFullReport(result, fixes) {
                 lines.push('');
             }
             if (fix) {
-                lines.push('**Why it matters:**', fix.explanation, '', '**Fixed code:**', '```html', fix.fixedCode, '```', '', '**📋 Prompt for your AI assistant (Cursor / Copilot / Claude):**', '```', fix.optimalPrompt, '```', '');
+                lines.push('**Why it matters:**', fix.explanation, '');
+                if ((!fix.fixCategory || fix.fixCategory === 'edit-element') && fix.fixedCode) {
+                    lines.push('**Fixed code:**', '```html', fix.fixedCode, '```', '');
+                }
+                lines.push('**📋 Prompt for your AI assistant (Cursor / Copilot / Claude):**', '```', fix.optimalPrompt, '```', '');
             }
             lines.push('---', '');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wcag-a11y",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "WCAG 2.1/2.2 accessibility auditor with AI-powered fixes. Crawls your dev server with Playwright, runs 40+ checks, and uses AI (12 providers) to generate fix prompts or patch source files directly.",
   "keywords": [
     "wcag",