@diegovelasquezweb/a11y-engine 0.6.0 → 0.6.2

package/README.md

@@ -37,6 +37,10 @@ import {
   getChecklist,
   getRemediationGuide,
   getSourcePatterns,
+  getScannerHelp,
+  getPersonaReference,
+  getUiHelp,
+  getKnowledge,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
@@ -113,6 +117,18 @@ These functions render final artifacts from scan payload data.
 | `getRemediationGuide(payload, options?)` | `{ markdown, contentType }` | Markdown remediation guide |
 | `getSourcePatterns(projectDir, options?)` | `{ findings, summary }` | Source code pattern analysis |
 
+### Knowledge API
+
+These functions expose scanner help content, persona explanations, and UI copy
+so frontends or agents can render tooltips and guidance from engine-owned data.
+
+| Function | Returns | Description |
+| :--- | :--- | :--- |
+| `getScannerHelp(options?)` | `{ locale, version, title, engines, options }` | Scanner option and engine help metadata |
+| `getPersonaReference(options?)` | `{ locale, version, personas }` | Persona labels, descriptions, and mapping hints |
+| `getUiHelp(options?)` | `{ locale, version, tooltips, glossary }` | Shared tooltip copy and glossary entries |
+| `getKnowledge(options?)` | `{ locale, version, scanner, personas, tooltips, glossary }` | Full documentation pack for UI or agent flows |
+
 See [API Reference](docs/api-reference.md) for exact options and return types.
 
 ## Optional CLI

package/assets/knowledge/knowledge.mjs

@@ -0,0 +1,385 @@
+export default {
+  version: "1.0.0",
+  locales: {
+    en: {
+      scanner: {
+        title: "Scanner Help",
+        engines: [
+          {
+            id: "axe",
+            label: "axe-core",
+            description: "Primary WCAG rule engine for rendered DOM violations.",
+            coverage: "Broadest WCAG rule coverage with over 90 checks across all four principles. Catches missing labels, contrast failures, landmark structure, and ARIA misuse.",
+            speed: "Fast",
+            defaultEnabled: true,
+          },
+          {
+            id: "cdp",
+            label: "CDP",
+            description: "Chrome accessibility tree checks for name/role/focus gaps.",
+            coverage: "Inspects the browser accessibility tree directly via Chrome DevTools Protocol. Catches name and role issues that axe misses at the DOM level.",
+            speed: "Medium",
+            defaultEnabled: true,
+          },
+          {
+            id: "pa11y",
+            label: "pa11y",
+            description: "HTML CodeSniffer checks to complement axe coverage.",
+            coverage: "Runs HTML CodeSniffer against the rendered page. Complements axe with additional HTML-level checks and alternative rule interpretations.",
+            speed: "Medium",
+            defaultEnabled: true,
+          },
+        ],
+        options: [
+          {
+            id: "maxRoutes",
+            label: "Max routes",
+            description: "Limits how many same-origin pages are scanned.",
+            defaultValue: 10,
+            type: "number",
+          },
+          {
+            id: "crawlDepth",
+            label: "Crawl depth",
+            description: "Controls how many link levels are explored from the start page.",
+            defaultValue: 1,
+            type: "number",
+          },
+          {
+            id: "waitUntil",
+            label: "Load strategy",
+            description: "Navigation readiness event before scanning each page.",
+            defaultValue: "domcontentloaded",
+            type: "enum",
+            allowedValues: [
+              {
+                value: "domcontentloaded",
+                label: "DOM Ready",
+                description: "Fires when the initial HTML is parsed. Fastest — use for server-rendered pages.",
+              },
+              {
+                value: "load",
+                label: "Page Load",
+                description: "Waits for all resources (images, scripts) to finish loading. Good for pages with critical above-the-fold assets.",
+              },
+              {
+                value: "networkidle",
+                label: "Network Idle",
+                description: "Waits until no network requests for 500ms. Best for SPAs and pages with deferred content loading.",
+              },
+            ],
+          },
+          {
+            id: "timeoutMs",
+            label: "Timeout",
+            description: "Maximum time to wait for each page to load before aborting.",
+            defaultValue: 30000,
+            type: "number",
+          },
+          {
+            id: "viewport",
+            label: "Viewport",
+            description: "Browser window size used during the audit.",
+            defaultValue: "1280x800",
+            type: "text",
+          },
+          {
+            id: "colorScheme",
+            label: "Color scheme",
+            description: "Emulates light or dark mode during the scan.",
+            defaultValue: "light",
+            type: "enum",
+            allowedValues: [
+              { value: "light", label: "Light" },
+              { value: "dark", label: "Dark" },
+            ],
+          },
+          {
+            id: "axeTags",
+            label: "Conformance tags",
+            description: "WCAG tag filters sent to axe-core.",
+            defaultValue: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"],
+            type: "string[]",
+          },
+        ],
+      },
+      conformanceLevels: [
+        {
+          id: "A",
+          label: "Level A",
+          badge: "Minimum",
+          description: "The baseline: essential requirements that remove the most severe barriers.",
+          shortDescription: "Minimum baseline",
+          hint: "Failing Level A means some users cannot access the content at all.",
+          tags: ["wcag2a", "wcag21a", "wcag22a"],
+        },
+        {
+          id: "AA",
+          label: "Level AA",
+          badge: "Standard",
+          description: "The recommended target for most websites — required by most accessibility laws.",
+          shortDescription: "Recommended for most websites",
+          hint: "Referenced by ADA, Section 508, EN 301 549, and EAA.",
+          tags: ["wcag2a", "wcag21a", "wcag22a", "wcag2aa", "wcag21aa", "wcag22aa"],
+        },
+        {
+          id: "AAA",
+          label: "Level AAA",
+          badge: "Enhanced",
+          description: "The highest conformance level — not required but beneficial for specialized audiences.",
+          shortDescription: "Strictest — not required by most regulations",
+          hint: "Full AAA conformance is not recommended as a general policy for entire sites.",
+          tags: ["wcag2a", "wcag21a", "wcag22a", "wcag2aa", "wcag21aa", "wcag22aa", "wcag2aaa"],
+        },
+      ],
+      wcagPrinciples: [
+        {
+          id: "perceivable",
+          name: "Perceivable",
+          description: "Information and UI components must be presentable to users in ways they can perceive.",
+          criterionPrefix: " 1.",
+          number: 1,
+        },
+        {
+          id: "operable",
+          name: "Operable",
+          description: "UI components and navigation must be operable.",
+          criterionPrefix: " 2.",
+          number: 2,
+        },
+        {
+          id: "understandable",
+          name: "Understandable",
+          description: "Information and the operation of the UI must be understandable.",
+          criterionPrefix: " 3.",
+          number: 3,
+        },
+        {
+          id: "robust",
+          name: "Robust",
+          description: "Content must be robust enough to be interpreted by a wide variety of user agents.",
+          criterionPrefix: " 4.",
+          number: 4,
+        },
+      ],
+      severityLevels: [
+        {
+          id: "Critical",
+          label: "Critical",
+          shortDescription: "Functional blockers",
+          description: "Blocks key user tasks with no practical workaround.",
+          order: 1,
+        },
+        {
+          id: "Serious",
+          label: "Serious",
+          shortDescription: "Serious impediments",
+          description: "Major barrier with difficult workaround or significant friction.",
+          order: 2,
+        },
+        {
+          id: "Moderate",
+          label: "Moderate",
+          shortDescription: "Significant friction",
+          description: "Usability degradation that still allows task completion.",
+          order: 3,
+        },
+        {
+          id: "Minor",
+          label: "Minor",
+          shortDescription: "Minor violations",
+          description: "Lower-impact issue that still reduces quality and consistency.",
+          order: 4,
+        },
+      ],
+      personas: {
+        screenReader: {
+          label: "Screen Reader Users",
+          description: "People who rely on spoken output and semantic structure.",
+        },
+        keyboard: {
+          label: "Keyboard-Only Users",
+          description: "People who navigate and operate controls using the keyboard only.",
+        },
+        vision: {
+          label: "Low Vision Users",
+          description: "People affected by low contrast, scaling, and visual clarity issues.",
+        },
+        cognitive: {
+          label: "Cognitive & Learning Users",
+          description: "People who benefit from predictable behavior and clear instructions.",
+        },
+      },
+      concepts: {
+        score: {
+          title: "Compliance Score",
+          body: "Weighted score from severity totals. It is a prioritization signal, not legal certification.",
+          context: "Based on automated accessibility technical checks.",
+        },
+        wcagStatus: {
+          title: "WCAG Status",
+          body: "Pass = no issues. Conditional Pass = only Moderate/Minor. Fail = any Critical/Serious remaining.",
+        },
+        severityBreakdown: {
+          title: "Severity Breakdown",
+          body: "Issue counts grouped by user impact and task completion risk.",
+        },
+        personaImpact: {
+          title: "Persona Impact",
+          body: "Shows which user groups are most affected by current findings.",
+        },
+        quickWins: {
+          title: "Quick Wins",
+          body: "Top Critical/Serious findings that already include concrete fix code.",
+          context: "High-priority issues with ready-to-use code fixes for immediate remediation.",
+        },
+        findingsFilter: {
+          title: "Findings Filter",
+          body: "Filter findings by severity or WCAG principle to focus remediation.",
+        },
+      },
+      outputs: {
+        pdf: {
+          title: "Stakeholder Report",
+          description: "A formal PDF accessibility compliance report.",
+          detail: "Designed for clients, non-technical stakeholders, project managers, and auditors. Includes the compliance score, WCAG status, severity breakdown, and a prioritized list of findings with recommended fixes — formatted for sharing and sign-off.",
+        },
+        checklist: {
+          title: "Manual Checklist",
+          description: "An interactive WCAG 2.2 AA manual testing checklist.",
+          detail: "Automated scanners catch around 30–40% of accessibility issues. This checklist covers the remaining manual checks — keyboard navigation, screen reader behavior, focus management, motion, zoom, and cognitive accessibility. Use it alongside the automated findings for a complete audit.",
+        },
+        json: {
+          title: "JSON Export",
+          description: "Machine-readable snapshot of all findings, scores, and metadata.",
+          detail: "Useful for integrating with CI/CD pipelines, tracking compliance over time, importing into dashboards, or diffing two audits programmatically. Includes all enriched findings with WCAG mappings, fix code, severity, and page location.",
+        },
+        remediation: {
+          title: "Remediation Guide",
+          description: "A structured Markdown guide for AI agents and developers.",
+          detail: "Contains prioritized fixes with ready-to-use code snippets, framework-specific guardrails, WCAG mappings, selector context, and verification commands. Designed to be fed directly into an AI coding agent (Claude, Copilot, Cursor) or used by developers for systematic remediation.",
+        },
+      },
+      docs: {
+        sections: [
+          {
+            id: "understanding-wcag",
+            heading: "Understanding WCAG",
+            groups: [
+              {
+                id: "wcag-versions",
+                label: "WCAG Versions",
+                articles: [
+                  {
+                    id: "wcag-2-0",
+                    title: "WCAG 2.0",
+                    badge: "2008",
+                    summary: "The original W3C recommendation that established the foundation for web accessibility.",
+                    body: "Introduced the four principles (Perceivable, Operable, Understandable, Robust) and three conformance levels (A, AA, AAA). Covers core requirements like text alternatives, keyboard access, color contrast, and form labels. Still widely referenced in legal frameworks worldwide.",
+                  },
+                  {
+                    id: "wcag-2-1",
+                    title: "WCAG 2.1",
+                    badge: "2018",
+                    summary: "Extended 2.0 with 17 new success criteria for mobile, low vision, and cognitive disabilities.",
+                    body: "Added criteria for touch targets (2.5.5), text spacing (1.4.12), content reflow (1.4.10), orientation (1.3.4), and input purpose (1.3.5). Required by the European Accessibility Act (EAA) and referenced in updated ADA guidance. All 2.0 criteria remain \u2014 2.1 is a superset.",
+                  },
+                  {
+                    id: "wcag-2-2",
+                    title: "WCAG 2.2",
+                    badge: "2023",
+                    summary: "The latest version, adding 9 new criteria focused on cognitive accessibility and consistent help.",
+                    body: "Key additions include consistent help (3.2.6), accessible authentication (3.3.8), dragging movements (2.5.7), and focus appearance (2.4.11/2.4.12). Removed criterion 4.1.1 (Parsing) as it\u2019s now handled by modern browsers. Supersedes both 2.0 and 2.1 \u2014 all prior criteria are included.",
+                  },
+                ],
+              },
+              {
+                id: "conformance-levels",
+                label: "Conformance Levels",
+                articles: [
+                  {
+                    id: "level-a",
+                    title: "Level A",
+                    badge: "Minimum",
+                    summary: "The baseline: essential requirements that remove the most severe barriers.",
+                    body: "Covers fundamentals like non-text content alternatives (1.1.1), keyboard operability (2.1.1), page titles (2.4.2), and language of the page (3.1.1). Failing Level A means some users cannot access the content at all. Every site should meet Level A at minimum.",
+                  },
+                  {
+                    id: "level-aa",
+                    title: "Level AA",
+                    badge: "Standard",
+                    summary: "The recommended target for most websites \u2014 required by most accessibility laws.",
+                    body: "Includes all Level A criteria plus requirements for color contrast (1.4.3 \u2014 4.5:1 ratio), resize text (1.4.4), focus visible (2.4.7), error suggestion (3.3.3), and consistent navigation (3.2.3). Referenced by ADA, Section 508, EN 301 549, and EAA. This is the standard the scanner defaults to.",
+                  },
+                  {
+                    id: "level-aaa",
+                    title: "Level AAA",
+                    badge: "Enhanced",
+                    summary: "The highest conformance level \u2014 not required but beneficial for specialized audiences.",
+                    body: "Adds stricter contrast (1.4.6 \u2014 7:1 ratio), sign language for audio (1.2.6), extended audio description (1.2.7), and reading level (3.1.5). Full AAA conformance is not recommended as a general policy because some criteria cannot be satisfied for all content types. Useful for targeted sections like education or government services.",
+                  },
+                ],
+              },
+            ],
+          },
+          {
+            id: "how-it-works",
+            heading: "How It Works",
+            articles: [
+              {
+                id: "load-render",
+                title: "Load & Render",
+                icon: "globe",
+                summary: "The scanner loads your URL in a real browser (Chromium) and waits for full render.",
+                body: "A headless Chromium instance navigates to the target URL, executes JavaScript, waits for network idle, and captures the fully rendered DOM. This ensures dynamic content (SPAs, lazy-loaded elements) is included in the analysis.",
+              },
+              {
+                id: "multi-engine-scan",
+                title: "Multi-Engine Scan",
+                icon: "cpu",
+                summary: "Multiple engines (axe-core, CDP, pa11y) run in parallel for broader coverage.",
+                body: "Each engine uses different detection techniques: axe-core runs DOM-based rule checks, CDP inspects accessibility tree properties via Chrome DevTools Protocol, and pa11y validates rendered HTML against WCAG criteria. Combined, they catch issues that any single engine would miss.",
+              },
+              {
+                id: "merge-deduplicate",
+                title: "Merge & Deduplicate",
+                icon: "git-merge",
+                summary: "Findings from all engines are normalized, deduplicated, and scored by severity.",
+                body: "Results are merged by selector + rule ID to eliminate duplicates. Each finding is mapped to its WCAG criterion, assigned a severity level (Critical/Serious/Moderate/Minor), and enriched with persona impact data showing which disability groups are affected.",
+              },
+              {
+                id: "ai-enrichment",
+                title: "AI Enrichment",
+                icon: "sparkles",
+                summary: "Each issue gets code fixes, MDN references, and framework-specific guidance.",
+                body: "The intelligence layer generates actionable fix descriptions, ready-to-use code snippets, links to relevant MDN documentation, and effort estimates. Quick Wins are identified as high-impact issues with low-effort fixes for immediate remediation.",
+              },
+            ],
+          },
+        ],
+      },
+      glossary: [
+        {
+          term: "Critical",
+          definition: "Blocks key user tasks with no practical workaround.",
+        },
+        {
+          term: "Serious",
+          definition: "Major barrier with difficult workaround or significant friction.",
+        },
+        {
+          term: "Moderate",
+          definition: "Usability degradation that still allows task completion.",
+        },
+        {
+          term: "Minor",
+          definition: "Lower-impact issue that still reduces quality and consistency.",
+        },
+        {
+          term: "Conditional Pass",
+          definition: "No Critical/Serious findings remain, but Moderate/Minor issues still exist.",
+        },
+      ],
+    },
+  },
+};

package/docs/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 
@@ -102,6 +102,36 @@ Returns: `Promise<RemediationGuide>` (`{ markdown, contentType }`)
 
 Returns: `Promise<SourcePatternResult>`
 
+## Knowledge API
+
+### `getScannerHelp(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `ScannerHelp` (`{ locale, version, title, engines, options }`)
+
+### `getPersonaReference(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `PersonaReference` (`{ locale, version, personas }`)
+
+### `getUiHelp(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `UiHelp` (`{ locale, version, tooltips, glossary }`)
+
+### `getKnowledge(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `EngineKnowledge` (`{ locale, version, scanner, personas, tooltips, glossary }`)
+
 ---
 
 Canonical type source: `src/index.d.mts`

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Engine Architecture
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/docs/cli-handbook.md

@@ -1,6 +1,6 @@
 # CLI Handbook
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/docs/engine-manifest.md

@@ -1,6 +1,6 @@
 # Engine Manifest
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/docs/intelligence.md

@@ -0,0 +1,209 @@
+# Intelligence & Enrichment
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Intelligence](intelligence.md) • [Testing](testing.md)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Enrichment Pipeline](#enrichment-pipeline)
+- [Intelligence Database](#intelligence-database)
+- [Finding Enrichment](#finding-enrichment)
+- [False Positive Filtering](#false-positive-filtering)
+- [Cross-Page Deduplication](#cross-page-deduplication)
+- [Ownership Classification](#ownership-classification)
+- [Persona Mapping](#persona-mapping)
+- [Scoring & Compliance](#scoring--compliance)
+- [Source Code Patterns](#source-code-patterns)
+- [Assets Reference](#assets-reference)
+
+---
+
+## Overview
+
+After the runtime engines (axe-core, CDP, pa11y) produce raw violations, the analyzer transforms them into enriched findings. This is the step that turns a list of rule IDs and selectors into actionable output with fix code, framework guidance, ownership hints, persona impact, and compliance scoring.
+
+The enrichment runs in `src/enrichment/analyzer.mjs` and is invoked by `runAudit` (programmatic) or `audit.mjs` (CLI).
+
+## Enrichment Pipeline
+
+```mermaid
+flowchart TD
+    RAW[Raw violations from dom-scanner] --> BUILD[buildFindings]
+    BUILD --> IGNORE[Apply ignoreFindings filter]
+    IGNORE --> FP[Filter false positives]
+    FP --> DEDUP[Cross-page deduplication]
+    DEDUP --> META[Compute metadata]
+
+    subgraph META[Metadata Computation]
+      OA[Overall assessment]
+      PC[Passed WCAG criteria]
+      OOS[Out of scope routes]
+      REC[Recommendations]
+      TM[Testing methodology]
+      INC[Incomplete findings]
+    end
+
+    DEDUP --> OUTPUT[Enriched payload]
+    META --> OUTPUT
+```
+
+## Intelligence Database
+
+The engine ships a bundled intelligence database at `assets/remediation/intelligence.mjs`. This contains per-rule entries keyed by axe rule ID (e.g. `color-contrast`, `image-alt`).
+
+Each rule entry can include:
+
+| Field | Purpose |
+| :--- | :--- |
+| `fix.description` | Plain-language explanation of how to fix |
+| `fix.code` | Ready-to-apply code snippet |
+| `category` | Grouping label (e.g. "Color & Contrast", "Forms") |
+| `related_rules` | Other rule IDs commonly seen together |
+| `managed_by_libraries` | UI libraries that handle this rule (e.g. `["radix-ui"]`) |
+| `false_positive_risk` | Known false positive patterns for this rule |
+| `fix_difficulty_notes` | Edge cases and pitfalls |
+| `framework_notes` | Framework-specific fix guidance (keyed by framework ID) |
+| `cms_notes` | CMS-specific fix guidance |
+| `preferred_relationship_checks` | axe check IDs to prioritize for relationship hints |
+| `guardrails` / `guardrails_overrides` | Must/must-not/verify constraints for automated fixes |
+
+When a framework is detected (e.g. `nextjs`), only the relevant framework notes are included in the output. React-based frameworks (`nextjs`, `gatsby`) resolve to `react` notes.
+
+## Finding Enrichment
+
+For each raw violation, `buildFindings` produces an enriched finding by:
+
+1. **Selector ranking** — scores all affected selectors by specificity (IDs > data attributes > ARIA > class names), penalizing Tailwind utility classes, and picks the most stable one as `primary_selector`.
+
+2. **WCAG mapping** — maps axe tags to human-readable WCAG labels (e.g. "WCAG 2.1 AA") and resolves the criterion ID (e.g. `1.4.3`) from the WCAG reference database.
+
+3. **Classification** — tags each finding as `A`, `AA`, `AAA`, or `Best Practice` based on its axe tags.
+
+4. **Intelligence lookup** — matches the rule ID against the intelligence database to pull fix description, fix code, category, related rules, guardrails, and difficulty notes.
+
+5. **ARIA role detection** — extracts explicit roles from HTML or infers implicit roles from tag names (e.g. `<nav>` → `navigation`), then links to APG pattern documentation.
+
+6. **Code language detection** — analyzes fix code snippets to determine language (`html`, `jsx`, `css`) for syntax highlighting.
+
+7. **Failure analysis** — extracts the primary failure mode, relationship hints (e.g. "label is not associated with input"), failure check messages, and related DOM context from axe node data.
+
+8. **Component hint** — extracts a semantic component name from the selector (skipping Tailwind utilities) or derives a page hint from the route path.
+
+9. **Impacted users** — looks up which disability groups are affected, first by rule ID, then by axe tag fallback.
+
+10. **File search pattern** — resolves framework-specific glob patterns (from source boundaries) so developers know where to search for the source file.
+
+11. **Stable ID** — generates a deterministic hash (`A11Y-xxxxxx`) from rule ID + URL + selector so findings are stable across scans.
+
+## False Positive Filtering
+
+After enrichment, confirmed false positives are removed. Currently covers:
+
+- `color-contrast` violations where the evidence HTML contains CSS gradients (`linear-gradient`, `radial-gradient`) — axe cannot compute contrast against gradients.
+- `color-contrast` violations where the element is hidden (`visibility: hidden`, `display: none`).
+
+The count of removed false positives is stored in `metadata.fpFiltered`.
+
+## Cross-Page Deduplication
+
+When scanning multiple routes, the same component often produces identical violations on every page. The deduplicator groups findings by `rule_id` + normalized `primary_selector` and collapses them into a single representative finding with:
+
+- `pages_affected` — number of pages where this violation appears
+- `affected_urls` — list of all affected URLs
+- `total_instances` — sum of DOM element instances across all pages
+
+Selectors like `html`, `body`, and `:root` are never grouped (they're too generic).
+
+## Ownership Classification
+
+Each finding is classified by whether the violation lives in the project's editable source or outside it:
+
+| Status | Meaning |
+| :--- | :--- |
+| `primary` | The finding should be fixed in the project source tree |
+| `outside_primary_source` | The element comes from a WordPress plugin, cross-origin iframe, or external embed |
+| `unknown` | Source scope could not be determined (no `projectDir` or framework boundaries) |
+
+This drives the `search_strategy` field: `direct_source_patch` for primary findings, `verify_ownership_before_search` for outside/unknown.
+
+## Persona Mapping
+
+The engine maps each finding to disability groups using three layers:
+
+1. **Rule-based** — the WCAG reference database (`assets/reporting/wcag-reference.mjs`) contains a `personaMapping` object that maps persona keys to lists of axe rule IDs. If a finding's `ruleId` matches, it's counted for that persona.
+
+2. **Criterion-based** — if no rule match is found, the engine checks if the finding's WCAG criterion ID is associated with a persona through the rule-to-criterion map.
+
+3. **Keyword fallback** — if neither rule nor criterion matches, the `impactedUsers` text is searched for persona keywords (e.g. "blind", "keyboard", "cognitive").
+
+A single finding can match multiple personas. The persona configuration (`personaConfig`) defines the labels and icons:
+
+| Key | Label |
+| :--- | :--- |
+| `screenReader` | Screen Readers |
+| `keyboard` | Keyboard Only |
+| `vision` | Color/Low Vision |
+| `cognitive` | Cognitive/Motor |
+
+## Scoring & Compliance
+
+The compliance score is computed from severity totals using weights defined in `assets/reporting/compliance-config.mjs`:
+
+1. **Severity totals** — counts findings by `Critical`, `Serious`, `Moderate`, `Minor` (excluding AAA and Best Practice findings).
+2. **Score** — starts at 100, deducts weighted points per finding.
+3. **Label** — maps score ranges to grades (`Excellent`, `Good Compliance`, `Needs Improvement`, `Poor`, `Critical`).
+4. **WCAG status** — `Pass` (no findings), `Conditional Pass` (only Moderate/Minor), or `Fail` (any Critical/Serious).
+
+The `overallAssessment` in metadata follows the same logic for the formal compliance verdict.
+
+Additionally, `passedCriteria` lists all WCAG criterion IDs that had explicit axe passes and no active violations — used in reports to show what the site does well.
+
+## Source Code Patterns
+
+The source scanner (`src/source-patterns/source-scanner.mjs`) detects accessibility issues that runtime engines cannot see because they exist only in source code.
+
+### How it works
+
+1. Loads pattern definitions from `assets/remediation/code-patterns.mjs`. Each pattern has:
+   - `id` — unique identifier (e.g. `no-aria-hidden-on-focusable`)
+   - `regex` — the pattern to search for
+   - `globs` — file extensions to scan (e.g. `**/*.tsx`)
+   - `title`, `severity`, `wcag`, `wcag_criterion`, `wcag_level`
+   - `fix_description` — how to fix matches
+   - `requires_manual_verification` — whether context analysis is needed
+   - `context_reject_regex` — regex that, if found near the match, means it's not a violation
+   - `context_window` — lines of context to check (default 5)
+
+2. Resolves scan directories using framework source boundaries (`assets/remediation/source-boundaries.mjs`). For example, Next.js projects scope to `src/`, `app/`, `pages/`, `components/`.
+
+3. Walks the file tree, skipping `node_modules`, `.git`, `dist`, build outputs, and minified files.
+
+4. For each file matching the pattern's globs, runs the regex line by line. When a match is found:
+   - Captures 3 lines of context above and below
+   - Runs context validation if `requires_manual_verification` is set — checks if `context_reject_regex` appears nearby. If it does, the finding is marked `potential` instead of `confirmed`.
+   - Generates a stable ID (`PAT-xxxxxx`)
+
+5. Output includes a summary with `total`, `confirmed`, and `potential` counts.
+
+### Integration with the audit pipeline
+
+When `runAudit` is called with `projectDir` and without `skipPatterns`:
+
+1. The analyzer runs first to detect the framework.
+2. Source patterns run after enrichment.
+3. Pattern findings are attached to the payload as `patternFindings` with their own `generated_at`, `project_dir`, `findings`, and `summary`.
+4. The remediation guide (`getRemediationGuide`) renders pattern findings in a dedicated section.
+
+## Assets Reference
+
+| Asset | Used by | Purpose |
+| :--- | :--- | :--- |
+| `remediation/intelligence.mjs` | analyzer | Per-rule fix descriptions, code, guardrails, framework notes |
+| `remediation/axe-check-maps.mjs` | analyzer | Failure mode and relationship hint mappings from axe check IDs |
+| `remediation/guardrails.mjs` | analyzer | Shared guardrail constraints for safe automated fixes |
+| `remediation/source-boundaries.mjs` | analyzer, source-scanner | Framework-specific source directory scoping |
+| `remediation/code-patterns.mjs` | source-scanner | Regex pattern definitions for source code scanning |
+| `reporting/wcag-reference.mjs` | analyzer, reports | WCAG criterion map, persona mapping, impacted users, APG patterns, MDN links |
+| `reporting/compliance-config.mjs` | analyzer, reports | Severity weights, score thresholds, impact mapping |

package/docs/outputs.md

@@ -1,6 +1,6 @@
 # Output Artifacts
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/docs/testing.md

@@ -1,6 +1,6 @@
 # Testing Strategy
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [Intelligence](intelligence.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/core/asset-loader.mjs

@@ -17,6 +17,7 @@ import sourceBoundaries from "../../assets/remediation/source-boundaries.mjs";
 import complianceConfig from "../../assets/reporting/compliance-config.mjs";
 import manualChecks from "../../assets/reporting/manual-checks.mjs";
 import wcagReference from "../../assets/reporting/wcag-reference.mjs";
+import knowledgeData from "../../assets/knowledge/knowledge.mjs";
 
 /**
  * Pre-loaded asset map. Each value is the parsed JSON object, ready to use.
@@ -46,6 +47,9 @@ export const ASSETS = {
     wcagReference,
     manualChecks,
   },
+  knowledge: {
+    knowledge: knowledgeData,
+  },
 };
 
 /**
@@ -78,6 +82,9 @@ export const ASSET_PATHS = {
     wcagReference: "reporting.wcagReference",
     manualChecks: "reporting.manualChecks",
   },
+  knowledge: {
+    knowledge: "knowledge.knowledge",
+  },
 };
 
 /**

package/src/enrichment/analyzer.mjs

@@ -832,7 +832,7 @@ function buildFindings(inputPayload, cliArgs) {
 
         findings.push({
           id: "",
-          rule_id: v.id,
+          rule_id: v.source === "cdp" ? v.id.replace(/^cdp-/, "") : v.id,
           source_rule_id: v.source_rule_id || null,
           source: v.source || "axe",
           title: v.help,

package/src/index.d.mts

@@ -209,6 +209,186 @@ export interface SourcePatternOptions {
   onlyPattern?: string;
 }
 
+// ---------------------------------------------------------------------------
+// Knowledge APIs
+// ---------------------------------------------------------------------------
+
+export interface ScannerEngineHelp {
+  id: "axe" | "cdp" | "pa11y" | string;
+  label: string;
+  description: string;
+  coverage: string;
+  speed: "Fast" | "Medium" | "Slow" | string;
+  defaultEnabled: boolean;
+}
+
+export interface EnumOptionValue {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface ScannerOptionHelp {
+  id: string;
+  label: string;
+  description: string;
+  defaultValue: unknown;
+  type: string;
+  allowedValues?: unknown[] | EnumOptionValue[];
+}
+
+export interface ConformanceLevel {
+  id: "A" | "AA" | "AAA";
+  label: string;
+  badge: string;
+  description: string;
+  shortDescription: string;
+  hint: string;
+  tags: string[];
+}
+
+export interface WcagPrinciple {
+  id: string;
+  name: string;
+  description: string;
+  criterionPrefix: string;
+  number: number;
+}
+
+export interface SeverityLevel {
+  id: "Critical" | "Serious" | "Moderate" | "Minor";
+  label: string;
+  shortDescription: string;
+  description: string;
+  order: number;
+}
+
+export interface OutputFormatInfo {
+  title: string;
+  description: string;
+  detail: string;
+}
+
+export interface OutputsInfo {
+  pdf: OutputFormatInfo;
+  checklist: OutputFormatInfo;
+  json: OutputFormatInfo;
+  remediation: OutputFormatInfo;
+}
+
+export interface ConformanceLevelsResult {
+  locale: string;
+  version: string;
+  conformanceLevels: ConformanceLevel[];
+}
+
+export interface WcagPrinciplesResult {
+  locale: string;
+  version: string;
+  wcagPrinciples: WcagPrinciple[];
+}
+
+export interface SeverityLevelsResult {
+  locale: string;
+  version: string;
+  severityLevels: SeverityLevel[];
+}
+
+export interface OutputsInfoResult {
+  locale: string;
+  version: string;
+  outputs: OutputsInfo;
+}
+
+export interface ScannerHelp {
+  locale: string;
+  version: string;
+  title: string;
+  engines: ScannerEngineHelp[];
+  options: ScannerOptionHelp[];
+}
+
+export interface PersonaReferenceItem {
+  id: string;
+  icon: string;
+  label: string;
+  description: string;
+  keywords: string[];
+  mappedRules: string[];
+}
+
+export interface PersonaReference {
+  locale: string;
+  version: string;
+  personas: PersonaReferenceItem[];
+}
+
+export interface ConceptEntry {
+  title: string;
+  body: string;
+  context?: string;
+}
+
+export interface GlossaryEntry {
+  term: string;
+  definition: string;
+}
+
+export interface DocArticle {
+  id: string;
+  title: string;
+  icon?: string;
+  badge?: string;
+  summary: string;
+  body: string;
+}
+
+export interface DocGroup {
+  id: string;
+  label: string;
+  articles: DocArticle[];
+}
+
+export interface DocSection {
+  id: string;
+  heading: string;
+  articles?: DocArticle[];
+  groups?: DocGroup[];
+}
+
+export interface KnowledgeDocs {
+  sections: DocSection[];
+}
+
+export interface UiHelp {
+  locale: string;
+  version: string;
+  concepts: Record<string, ConceptEntry>;
+  glossary: GlossaryEntry[];
+}
+
+export interface EngineKnowledge {
+  locale: string;
+  version: string;
+  scanner: {
+    title: string;
+    engines: ScannerEngineHelp[];
+    options: ScannerOptionHelp[];
+  };
+  personas: PersonaReferenceItem[];
+  concepts: Record<string, ConceptEntry>;
+  glossary: GlossaryEntry[];
+  docs: KnowledgeDocs;
+  conformanceLevels: ConformanceLevel[];
+  wcagPrinciples: WcagPrinciple[];
+  severityLevels: SeverityLevel[];
+  outputs: OutputsInfo;
+}
+
+export interface KnowledgeOptions {
+  locale?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Engine selection
 // ---------------------------------------------------------------------------
@@ -293,3 +473,19 @@ export function getSourcePatterns(
   projectDir: string,
   options?: SourcePatternOptions
 ): Promise<SourcePatternResult>;
+
+export function getScannerHelp(options?: KnowledgeOptions): ScannerHelp;
+
+export function getPersonaReference(options?: KnowledgeOptions): PersonaReference;
+
+export function getUiHelp(options?: KnowledgeOptions): UiHelp;
+
+export function getConformanceLevels(options?: KnowledgeOptions): ConformanceLevelsResult;
+
+export function getWcagPrinciples(options?: KnowledgeOptions): WcagPrinciplesResult;
+
+export function getSeverityLevels(options?: KnowledgeOptions): SeverityLevelsResult;
+
+export function getOutputsInfo(options?: KnowledgeOptions): OutputsInfoResult;
+
+export function getKnowledge(options?: KnowledgeOptions): EngineKnowledge;

package/src/index.mjs

@@ -14,6 +14,7 @@ let _intelligence = null;
 let _pa11yConfig = null;
 let _complianceConfig = null;
 let _wcagReference = null;
+let _knowledge = null;
 
 function getIntelligence() {
   if (!_intelligence) _intelligence = loadAssetJson(ASSET_PATHS.remediation.intelligence, "intelligence.json");
@@ -41,6 +42,22 @@ function getWcagReference() {
   return _wcagReference;
 }
 
+function getKnowledgeData() {
+  if (!_knowledge) _knowledge = loadAssetJson(ASSET_PATHS.knowledge.knowledge, "knowledge.json");
+  return _knowledge;
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function resolveKnowledgeLocale(locale = "en") {
+  const payload = getKnowledgeData();
+  const locales = payload.locales || {};
+  if (locale && locales[locale]) return locale;
+  return "en";
+}
+
 // ---------------------------------------------------------------------------
 // Pa11y rule canonicalization (internal)
 // ---------------------------------------------------------------------------
@@ -421,6 +438,194 @@ export function getOverview(findings, payload = null) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Knowledge APIs
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns scanner-facing help metadata including engine descriptions,
+ * advanced option hints, and defaults.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, title: string, engines: object[], options: object[] }}
+ */
+export function getScannerHelp(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const scanner = payload.locales[locale]?.scanner || { title: "Scanner Help", engines: [], options: [] };
+
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    title: scanner.title,
+    engines: clone(scanner.engines || []),
+    options: clone(scanner.options || []),
+  };
+}
+
+/**
+ * Returns persona explanations with labels, descriptions, and the WCAG rule/
+ * keyword mappings used for impact grouping.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, personas: object[] }}
+ */
+export function getPersonaReference(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const wcagRef = getWcagReference();
+
+  const copyMap = payload.locales[locale]?.personas || {};
+  const personaConfig = wcagRef.personaConfig || {};
+  const personaMapping = wcagRef.personaMapping || {};
+
+  const personas = Object.keys(copyMap).map((id) => {
+    const copy = copyMap[id] || {};
+    const config = personaConfig[id] || {};
+    const mapping = personaMapping[id] || {};
+
+    return {
+      id,
+      icon: id,
+      label: copy.label || config.label || id,
+      description: copy.description || "",
+      keywords: Array.isArray(mapping.keywords) ? clone(mapping.keywords) : [],
+      mappedRules: Array.isArray(mapping.rules) ? clone(mapping.rules) : [],
+    };
+  });
+
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    personas,
+  };
+}
+
+/**
+ * Returns UI tooltip copy and glossary terms for scanner cards and labels.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, tooltips: Record<string, object>, glossary: object[] }}
+ */
+export function getUiHelp(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const localePayload = payload.locales[locale] || {};
+
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    concepts: clone(localePayload.concepts || {}),
+    glossary: clone(localePayload.glossary || []),
+  };
+}
+
+/**
+ * Returns the full documentation package that frontends or agents can render
+ * as help content next to findings and scores.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, scanner: object, personas: object[], tooltips: Record<string, object>, glossary: object[] }}
+ */
+/**
+ * Returns conformance level definitions with WCAG axe-core tag mappings.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, conformanceLevels: object[] }}
+ */
+export function getConformanceLevels(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const levels = payload.locales[locale]?.conformanceLevels || [];
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    conformanceLevels: clone(levels),
+  };
+}
+
+/**
+ * Returns the four WCAG principles with their criterion prefix patterns.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, wcagPrinciples: object[] }}
+ */
+export function getWcagPrinciples(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const principles = payload.locales[locale]?.wcagPrinciples || [];
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    wcagPrinciples: clone(principles),
+  };
+}
+
+/**
+ * Returns severity level definitions with labels, descriptions, and ordering.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, severityLevels: object[] }}
+ */
+export function getSeverityLevels(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const levels = payload.locales[locale]?.severityLevels || [];
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    severityLevels: clone(levels),
+  };
+}
+
+/**
+ * Returns output format descriptions for each report type the engine produces.
+ *
+ * @param {{ locale?: string }} [options={}]
+ * @returns {{ locale: string, version: string, outputs: object }}
+ */
+export function getOutputsInfo(options = {}) {
+  const locale = resolveKnowledgeLocale(options.locale || "en");
+  const payload = getKnowledgeData();
+  const outputs = payload.locales[locale]?.outputs || {};
+  return {
+    locale,
+    version: payload.version || "1.0.0",
+    outputs: clone(outputs),
+  };
+}
+
+export function getKnowledge(options = {}) {
+  const scanner = getScannerHelp(options);
+  const personas = getPersonaReference(options);
+  const ui = getUiHelp(options);
+  const conformance = getConformanceLevels(options);
+  const principles = getWcagPrinciples(options);
+  const severity = getSeverityLevels(options);
+  const outputsInfo = getOutputsInfo(options);
+
+  const payload = getKnowledgeData();
+  const docs = clone(payload.locales[scanner.locale]?.docs ?? { sections: [] });
+
+  return {
+    locale: scanner.locale,
+    version: scanner.version,
+    scanner: {
+      title: scanner.title,
+      engines: scanner.engines,
+      options: scanner.options,
+    },
+    personas: personas.personas,
+    concepts: ui.concepts,
+    glossary: ui.glossary,
+    docs,
+    conformanceLevels: conformance.conformanceLevels,
+    wcagPrinciples: principles.wcagPrinciples,
+    severityLevels: severity.severityLevels,
+    outputs: outputsInfo.outputs,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Full audit pipeline
 // ---------------------------------------------------------------------------

package/src/reports/html.mjs

@@ -285,7 +285,7 @@ function buildHtml(args, findings, metadata = {}) {
               </div>
             </div>
             <h3 class="text-xl font-bold text-slate-900 mb-1">${label} Compliance</h3>
-            <p class="text-xs font-medium text-slate-500 max-w-[200px] leading-snug">Automated testing coverage based on ${escapeHtml(args.target)} technical checks.</p>
+            <p class="text-xs font-medium text-slate-500 max-w-50 leading-snug">Automated testing coverage based on ${escapeHtml(args.target)} technical checks.</p>
           </div>
 
           <div class="md:col-span-7 grid grid-cols-2 gap-4">
@@ -334,13 +334,13 @@ function buildHtml(args, findings, metadata = {}) {
             <div class="group">
               <div class="flex items-center justify-between mb-2">
                 <div class="flex items-center gap-3">
-                  <div class="w-8 h-8 rounded-lg bg-slate-50 flex items-center justify-center text-slate-600 group-hover:bg-[var(--primary-light)] group-hover:text-[var(--primary)] transition-colors">${p.icon}</div>
+                  <div class="w-8 h-8 rounded-lg bg-slate-50 flex items-center justify-center text-slate-600 group-hover:bg-(--primary-light) group-hover:text-(--primary) transition-colors">${p.icon}</div>
                   <span class="text-sm font-bold text-slate-700">${p.label}</span>
                 </div>
                 <span class="text-xs font-black text-slate-900">${p.count} issues</span>
               </div>
               <div class="w-full bg-slate-100 rounded-full h-1.5 overflow-hidden">
-                <div class="bg-[var(--primary)] h-full rounded-full transition-all duration-500" style="width: ${findings.length > 0 ? (p.count / findings.length) * 100 : 0}%"></div>
+                <div class="bg-(--primary) h-full rounded-full transition-all duration-500" style="width: ${findings.length > 0 ? (p.count / findings.length) * 100 : 0}%"></div>
               </div>
             </div>`,
               )
@@ -355,14 +355,14 @@ function buildHtml(args, findings, metadata = {}) {
           ? `
       <div class="premium-card rounded-2xl bg-slate-900 p-6 mb-12 relative overflow-hidden">
         <div class="absolute -right-4 -bottom-4 opacity-10">
-          <svg class="w-32 h-32 text-[var(--primary)]" fill="currentColor" viewBox="0 0 24 24"><path d="M13 10V3L4 14h7v7l9-11h-7z"/></svg>
+          <svg class="w-32 h-32 text-(--primary)" fill="currentColor" viewBox="0 0 24 24"><path d="M13 10V3L4 14h7v7l9-11h-7z"/></svg>
         </div>
         <div class="relative z-10">
           <div class="flex items-center gap-3 mb-4">
-            <span class="px-2 py-0.5 rounded bg-[var(--primary)] text-[10px] font-black text-white uppercase tracking-tighter">AI Analysis</span>
+            <span class="px-2 py-0.5 rounded bg-(--primary) text-[10px] font-black text-white uppercase tracking-tighter">AI Analysis</span>
             <h3 class="text-xl font-bold text-white">Recommended Quick Wins</h3>
           </div>
-          <p class="text-xs text-[var(--primary)]/80 mb-6 -mt-2 leading-relaxed italic">High-priority issues with ready-to-use code fixes for immediate remediation.</p>
+          <p class="text-xs text-(--primary)/80 mb-6 -mt-2 leading-relaxed italic">High-priority issues with ready-to-use code fixes for immediate remediation.</p>
           <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
             ${quickWins
               .map(
@@ -393,7 +393,7 @@ function buildHtml(args, findings, metadata = {}) {
           <div class="flex items-center gap-4">
             <h3 class="text-xl font-extrabold text-slate-900 tracking-tight">Findings <span class="text-slate-600 font-bold ml-1">${findings.length}</span></h3>
             <div class="flex gap-1 bg-white border border-slate-200 rounded-xl p-1 shadow-sm">
-              <button onclick="setView('severity')" id="view-severity" class="view-btn px-4 py-1.5 rounded-lg text-xs font-bold uppercase tracking-widest bg-[var(--primary-light)] text-[var(--primary)] transition-all">By Severity</button>
+              <button onclick="setView('severity')" id="view-severity" class="view-btn px-4 py-1.5 rounded-lg text-xs font-bold uppercase tracking-widest bg-(--primary-light) text-(--primary) transition-all">By Severity</button>
               ${
                 Object.keys(_pageCounts).length > 1
                   ? `<button onclick="setView('page')" id="view-page" class="view-btn px-4 py-1.5 rounded-lg text-xs font-bold uppercase tracking-widest text-slate-500 hover:text-slate-700 transition-all">By Page</button>`
@@ -407,7 +407,7 @@ function buildHtml(args, findings, metadata = {}) {
         <!-- Row 2: Search & Filter Select -->
         <div class="flex items-center gap-4 w-full">
           <div class="relative flex-1">
-            <input type="text" id="search-input" oninput="handleSearch(this.value)" placeholder="Search violations..." class="w-full pl-11 pr-4 py-3 bg-white border border-slate-200 rounded-2xl text-sm font-medium focus:outline-none focus:ring-4 focus:ring-[var(--primary)]/10 focus:border-[var(--primary)] transition-all shadow-sm">
+            <input type="text" id="search-input" oninput="handleSearch(this.value)" placeholder="Search violations..." class="w-full pl-11 pr-4 py-3 bg-white border border-slate-200 rounded-2xl text-sm font-medium focus:outline-none focus:ring-4 focus:ring-(--primary)/10 focus:border-(--primary) transition-all shadow-sm">
             <svg class="absolute left-4 top-3.5 w-5 h-5 text-slate-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
           </div>
           
@@ -444,7 +444,7 @@ function buildHtml(args, findings, metadata = {}) {
       </div>
 
       <footer class="mt-10 py-6 border-t border-slate-200 text-center">
-        <p class="text-slate-600 text-sm font-medium">Generated by <a href="https://github.com/diegovelasquezweb/a11y" target="_blank" class="text-slate-700 hover:text-[var(--primary)] font-semibold transition-colors">a11y</a> &bull; <span class="text-slate-700">${escapeHtml(args.target)}</span></p>
+        <p class="text-slate-600 text-sm font-medium">Generated by <a href="https://github.com/diegovelasquezweb/a11y" target="_blank" class="text-slate-700 hover:text-(--primary) font-semibold transition-colors">a11y</a> &bull; <span class="text-slate-700">${escapeHtml(args.target)}</span></p>
       </footer>
     </main>