@diegovelasquezweb/a11y-engine 0.6.1 → 0.6.2

package/assets/knowledge/knowledge.mjs

@@ -9,18 +9,24 @@ export default {
             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,
           },
         ],
@@ -36,7 +42,7 @@ export default {
             id: "crawlDepth",
             label: "Crawl depth",
             description: "Controls how many link levels are explored from the start page.",
-            defaultValue: 2,
+            defaultValue: 1,
             type: "number",
           },
           {
@@ -45,29 +51,48 @@ export default {
             description: "Navigation readiness event before scanning each page.",
             defaultValue: "domcontentloaded",
             type: "enum",
-            allowedValues: ["domcontentloaded", "load", "networkidle"],
+            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 navigation wait time per route in milliseconds.",
+            description: "Maximum time to wait for each page to load before aborting.",
             defaultValue: 30000,
             type: "number",
           },
           {
             id: "viewport",
             label: "Viewport",
-            description: "Browser viewport used during scan emulation.",
+            description: "Browser window size used during the audit.",
             defaultValue: "1280x800",
             type: "text",
           },
           {
             id: "colorScheme",
             label: "Color scheme",
-            description: "Emulated light or dark color-scheme preference.",
+            description: "Emulates light or dark mode during the scan.",
             defaultValue: "light",
             type: "enum",
-            allowedValues: ["light", "dark"],
+            allowedValues: [
+              { value: "light", label: "Light" },
+              { value: "dark", label: "Dark" },
+            ],
           },
           {
             id: "axeTags",
@@ -78,6 +103,95 @@ export default {
           },
         ],
       },
+      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",
@@ -96,16 +210,17 @@ export default {
           description: "People who benefit from predictable behavior and clear instructions.",
         },
       },
-      tooltips: {
-        scoreGauge: {
+      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.",
         },
-        severityCards: {
+        severityBreakdown: {
           title: "Severity Breakdown",
           body: "Issue counts grouped by user impact and task completion risk.",
         },
@@ -116,12 +231,35 @@ export default {
         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: [
           {
@@ -135,24 +273,21 @@ export default {
                   {
                     id: "wcag-2-0",
                     title: "WCAG 2.0",
-                    tag: "2008",
-                    tagVariant: "neutral",
+                    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",
-                    tag: "2018",
-                    tagVariant: "info",
+                    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",
-                    tag: "2023",
-                    tagVariant: "violet",
+                    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.",
                   },
@@ -165,24 +300,21 @@ export default {
                   {
                     id: "level-a",
                     title: "Level A",
-                    tag: "Minimum",
-                    tagVariant: "warning",
+                    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",
-                    tag: "Standard",
-                    tagVariant: "success",
+                    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",
-                    tag: "Enhanced",
-                    tagVariant: "purple",
+                    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.",
                   },

package/package.json

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

package/src/index.d.mts

@@ -217,16 +217,87 @@ 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[];
+  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 {
@@ -252,9 +323,10 @@ export interface PersonaReference {
   personas: PersonaReferenceItem[];
 }
 
-export interface UiTooltip {
+export interface ConceptEntry {
   title: string;
   body: string;
+  context?: string;
 }
 
 export interface GlossaryEntry {
@@ -266,8 +338,7 @@ export interface DocArticle {
   id: string;
   title: string;
   icon?: string;
-  tag?: string;
-  tagVariant?: string;
+  badge?: string;
   summary: string;
   body: string;
 }
@@ -292,7 +363,7 @@ export interface KnowledgeDocs {
 export interface UiHelp {
   locale: string;
   version: string;
-  tooltips: Record<string, UiTooltip>;
+  concepts: Record<string, ConceptEntry>;
   glossary: GlossaryEntry[];
 }
 
@@ -305,9 +376,13 @@ export interface EngineKnowledge {
     options: ScannerOptionHelp[];
   };
   personas: PersonaReferenceItem[];
-  tooltips: Record<string, UiTooltip>;
+  concepts: Record<string, ConceptEntry>;
   glossary: GlossaryEntry[];
   docs: KnowledgeDocs;
+  conformanceLevels: ConformanceLevel[];
+  wcagPrinciples: WcagPrinciple[];
+  severityLevels: SeverityLevel[];
+  outputs: OutputsInfo;
 }
 
 export interface KnowledgeOptions {
@@ -405,4 +480,12 @@ export function getPersonaReference(options?: KnowledgeOptions): PersonaReferenc
 
 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

@@ -515,7 +515,7 @@ export function getUiHelp(options = {}) {
   return {
     locale,
     version: payload.version || "1.0.0",
-    tooltips: clone(localePayload.tooltips || {}),
+    concepts: clone(localePayload.concepts || {}),
     glossary: clone(localePayload.glossary || []),
   };
 }
@@ -527,10 +527,82 @@ export function getUiHelp(options = {}) {
  * @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: [] });
@@ -544,9 +616,13 @@ export function getKnowledge(options = {}) {
       options: scanner.options,
     },
     personas: personas.personas,
-    tooltips: ui.tooltips,
+    concepts: ui.concepts,
     glossary: ui.glossary,
     docs,
+    conformanceLevels: conformance.conformanceLevels,
+    wcagPrinciples: principles.wcagPrinciples,
+    severityLevels: severity.severityLevels,
+    outputs: outputsInfo.outputs,
   };
 }