@wcag-audit/cli 1.0.0-alpha.3

package/src/wcag-criteria.js

@@ -0,0 +1,256 @@
+// Catalogue of WCAG success criteria (2.0 / 2.1 / 2.2) with the automation
+// status of each one against this CLI's three engines:
+//
+//   automation:        what axe-core can detect statically
+//                      "automated" | "partial" | "manual"
+//   aiReviewable:      what Claude vision can judge from a still snapshot
+//   playwrightCheckable: what we can verify by driving the browser (keyboard,
+//                      viewport, hover, form submit, motion timelapse, etc.)
+//
+// `addedIn` is the WCAG version that introduced the criterion. `removedIn`
+// marks criteria dropped in a later version (4.1.1 in 2.2).
+
+export const WCAG_CRITERIA = [
+  // ─────────────────────────── 1. Perceivable ───────────────────────────
+  { id: "1.1.1", title: "Non-text Content", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["image-alt", "input-image-alt", "area-alt", "role-img-alt", "svg-img-alt", "object-alt", "input-button-name"] },
+
+  { id: "1.2.1", title: "Audio-only and Video-only (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["audio-caption", "video-caption"],
+    playwrightCheckable: true,
+    notes: "CLI detects <audio>/<video> presence; transcript accuracy is human-only." },
+  { id: "1.2.2", title: "Captions (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["video-caption"],
+    playwrightCheckable: true,
+    notes: "CLI checks for <track kind=captions>; caption correctness is human." },
+  { id: "1.2.3", title: "Audio Description or Media Alternative (Prerecorded)", level: "A", addedIn: "2.0",
+    automation: "manual",
+    notes: "Quality of description is human-only." },
+  { id: "1.2.4", title: "Captions (Live)", level: "AA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.5", title: "Audio Description (Prerecorded)", level: "AA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.6", title: "Sign Language (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.7", title: "Extended Audio Description (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.8", title: "Media Alternative (Prerecorded)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.2.9", title: "Audio-only (Live)", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+
+  { id: "1.3.1", title: "Info and Relationships", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["definition-list", "dlitem", "list", "listitem", "table-fake-caption", "td-headers-attr", "th-has-data-cells", "scope-attr-valid", "aria-required-parent", "aria-required-children", "label", "form-field-multiple-labels", "p-as-heading"] },
+  { id: "1.3.2", title: "Meaningful Sequence", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["tabindex"], playwrightCheckable: true,
+    notes: "CLI compares DOM order to visual order via bounding boxes." },
+  { id: "1.3.3", title: "Sensory Characteristics", level: "A", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.3.4", title: "Orientation", level: "AA", addedIn: "2.1",
+    automation: "automated", axeRules: ["css-orientation-lock"] },
+  { id: "1.3.5", title: "Identify Input Purpose", level: "AA", addedIn: "2.1",
+    automation: "automated", axeRules: ["autocomplete-valid"] },
+  { id: "1.3.6", title: "Identify Purpose", level: "AAA", addedIn: "2.1",
+    automation: "manual" },
+
+  { id: "1.4.1", title: "Use of Color", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["link-in-text-block"], aiReviewable: true },
+  { id: "1.4.2", title: "Audio Control", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["no-autoplay-audio"], playwrightCheckable: true },
+  { id: "1.4.3", title: "Contrast (Minimum)", level: "AA", addedIn: "2.0",
+    automation: "automated", axeRules: ["color-contrast"] },
+  { id: "1.4.4", title: "Resize Text", level: "AA", addedIn: "2.0",
+    automation: "partial", axeRules: ["meta-viewport"], playwrightCheckable: true,
+    notes: "CLI zooms to 200% and checks for content loss / overflow." },
+  { id: "1.4.5", title: "Images of Text", level: "AA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.6", title: "Contrast (Enhanced)", level: "AAA", addedIn: "2.0",
+    automation: "automated", axeRules: ["color-contrast-enhanced"] },
+  { id: "1.4.7", title: "Low or No Background Audio", level: "AAA", addedIn: "2.0",
+    automation: "manual" },
+  { id: "1.4.8", title: "Visual Presentation", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.9", title: "Images of Text (No Exception)", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.10", title: "Reflow", level: "AA", addedIn: "2.1",
+    automation: "partial", axeRules: ["meta-viewport"], playwrightCheckable: true,
+    notes: "CLI shrinks viewport to 320 CSS px and checks for horizontal scroll." },
+  { id: "1.4.11", title: "Non-text Contrast", level: "AA", addedIn: "2.1",
+    automation: "manual", aiReviewable: true },
+  { id: "1.4.12", title: "Text Spacing", level: "AA", addedIn: "2.1",
+    automation: "manual", aiReviewable: true, playwrightCheckable: true,
+    notes: "CLI injects WCAG-required spacing CSS and checks for clipped text." },
+  { id: "1.4.13", title: "Content on Hover or Focus", level: "AA", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI hovers tooltip triggers and verifies dismissible/persistent/hoverable." },
+
+  // ─────────────────────────── 2. Operable ───────────────────────────
+  { id: "2.1.1", title: "Keyboard", level: "A", addedIn: "2.0",
+    automation: "partial",
+    axeRules: ["frame-focusable-content", "scrollable-region-focusable", "nested-interactive"],
+    playwrightCheckable: true,
+    notes: "CLI tabs through every interactive element." },
+  { id: "2.1.2", title: "No Keyboard Trap", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects Tab cycles where focus never leaves a region." },
+  { id: "2.1.3", title: "Keyboard (No Exception)", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.1.4", title: "Character Key Shortcuts", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for global single-key keydown listeners." },
+
+  { id: "2.2.1", title: "Timing Adjustable", level: "A", addedIn: "2.0",
+    automation: "manual", axeRules: ["meta-refresh"], playwrightCheckable: true },
+  { id: "2.2.2", title: "Pause, Stop, Hide", level: "A", addedIn: "2.0",
+    automation: "partial", axeRules: ["blink", "marquee", "no-autoplay-audio"],
+    playwrightCheckable: true,
+    notes: "CLI records a timelapse and detects auto-updating content / autoplay." },
+  { id: "2.2.3", title: "No Timing", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.4", title: "Interruptions", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.5", title: "Re-authenticating", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "2.2.6", title: "Timeouts", level: "AAA", addedIn: "2.1", automation: "manual" },
+
+  { id: "2.3.1", title: "Three Flashes or Below Threshold", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI captures a 10s timelapse and counts large frame-to-frame deltas." },
+  { id: "2.3.2", title: "Three Flashes", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.3.3", title: "Animation from Interactions", level: "AAA", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true },
+
+  { id: "2.4.1", title: "Bypass Blocks", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["bypass", "region", "landmark-one-main", "skip-link"] },
+  { id: "2.4.2", title: "Page Titled", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["document-title"] },
+  { id: "2.4.3", title: "Focus Order", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI compares Tab order to visual reading order." },
+  { id: "2.4.4", title: "Link Purpose (In Context)", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["link-name"] },
+  { id: "2.4.5", title: "Multiple Ways", level: "AA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true, playwrightCheckable: true },
+  { id: "2.4.6", title: "Headings and Labels", level: "AA", addedIn: "2.0",
+    automation: "partial", axeRules: ["empty-heading", "heading-order", "empty-table-header"], aiReviewable: true },
+  { id: "2.4.7", title: "Focus Visible", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI captures before/after focus state and pixel-diffs each control." },
+  { id: "2.4.8", title: "Location", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "2.4.9", title: "Link Purpose (Link Only)", level: "AAA", addedIn: "2.0",
+    automation: "automated", axeRules: ["link-name"] },
+  { id: "2.4.10", title: "Section Headings", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "2.4.11", title: "Focus Not Obscured (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI checks focused element rect vs sticky/fixed element rects." },
+  { id: "2.4.12", title: "Focus Not Obscured (Enhanced)", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.4.13", title: "Focus Appearance", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+
+  { id: "2.5.1", title: "Pointer Gestures", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for multi-touch / path gesture event listeners." },
+  { id: "2.5.2", title: "Pointer Cancellation", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects elements that act on pointerdown without an undo path." },
+  { id: "2.5.3", title: "Label in Name", level: "A", addedIn: "2.1",
+    automation: "automated", axeRules: ["label-content-name-mismatch"] },
+  { id: "2.5.4", title: "Motion Actuation", level: "A", addedIn: "2.1",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI scans for deviceorientation/devicemotion listeners." },
+  { id: "2.5.5", title: "Target Size (Enhanced)", level: "AAA", addedIn: "2.1",
+    automation: "automated", axeRules: ["target-size"] },
+  { id: "2.5.6", title: "Concurrent Input Mechanisms", level: "AAA", addedIn: "2.1",
+    automation: "manual" },
+  { id: "2.5.7", title: "Dragging Movements", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+  { id: "2.5.8", title: "Target Size (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "automated", axeRules: ["target-size"] },
+
+  // ─────────────────────────── 3. Understandable ───────────────────────────
+  { id: "3.1.1", title: "Language of Page", level: "A", addedIn: "2.0",
+    automation: "automated", axeRules: ["html-has-lang", "html-lang-valid", "html-xml-lang-mismatch"] },
+  { id: "3.1.2", title: "Language of Parts", level: "AA", addedIn: "2.0",
+    automation: "automated", axeRules: ["valid-lang"] },
+  { id: "3.1.3", title: "Unusual Words", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.4", title: "Abbreviations", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.5", title: "Reading Level", level: "AAA", addedIn: "2.0",
+    automation: "manual", aiReviewable: true },
+  { id: "3.1.6", title: "Pronunciation", level: "AAA", addedIn: "2.0", automation: "manual" },
+
+  { id: "3.2.1", title: "On Focus", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI focuses each control and watches for navigation / context change." },
+  { id: "3.2.2", title: "On Input", level: "A", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI types into each input and watches for navigation / context change." },
+  { id: "3.2.3", title: "Consistent Navigation", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI crawls multiple pages and compares navigation structure." },
+  { id: "3.2.4", title: "Consistent Identification", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.2.5", title: "Change on Request", level: "AAA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.2.6", title: "Consistent Help", level: "A", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI looks for a help mechanism in the same location across pages." },
+
+  { id: "3.3.1", title: "Error Identification", level: "A", addedIn: "2.0",
+    automation: "manual", axeRules: ["aria-required-attr"], playwrightCheckable: true,
+    notes: "CLI submits forms invalid and checks errors are announced." },
+  { id: "3.3.2", title: "Labels or Instructions", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["label", "form-field-multiple-labels", "select-name", "input-button-name"] },
+  { id: "3.3.3", title: "Error Suggestion", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI submits forms invalid and asks AI whether the error provides a fix." },
+  { id: "3.3.4", title: "Error Prevention (Legal, Financial, Data)", level: "AA", addedIn: "2.0",
+    automation: "manual", playwrightCheckable: true },
+  { id: "3.3.5", title: "Help", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "3.3.6", title: "Error Prevention (All)", level: "AAA", addedIn: "2.0", automation: "manual" },
+  { id: "3.3.7", title: "Redundant Entry", level: "A", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI walks multi-step forms and detects duplicate fields." },
+  { id: "3.3.8", title: "Accessible Authentication (Minimum)", level: "AA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true,
+    notes: "CLI detects CAPTCHAs and other cognitive function tests." },
+  { id: "3.3.9", title: "Accessible Authentication (Enhanced)", level: "AAA", addedIn: "2.2",
+    automation: "manual", playwrightCheckable: true },
+
+  // ─────────────────────────── 4. Robust ───────────────────────────
+  { id: "4.1.1", title: "Parsing", level: "A", addedIn: "2.0", removedIn: "2.2",
+    automation: "automated", axeRules: ["duplicate-id", "duplicate-id-active", "duplicate-id-aria"] },
+  { id: "4.1.2", title: "Name, Role, Value", level: "A", addedIn: "2.0",
+    automation: "automated",
+    axeRules: ["aria-allowed-attr", "aria-allowed-role", "aria-command-name", "aria-hidden-body", "aria-hidden-focus", "aria-input-field-name", "aria-meter-name", "aria-progressbar-name", "aria-required-attr", "aria-required-children", "aria-required-parent", "aria-roles", "aria-toggle-field-name", "aria-tooltip-name", "aria-valid-attr", "aria-valid-attr-value", "button-name", "link-name", "select-name", "summary-name"] },
+  { id: "4.1.3", title: "Status Messages", level: "AA", addedIn: "2.1",
+    automation: "partial", axeRules: ["aria-allowed-role", "aria-valid-attr-value"] },
+];
+
+export function filterCriteriaForScope(version, levels) {
+  const upper = new Set(levels.map((l) => l.toUpperCase()));
+  return WCAG_CRITERIA.filter((c) => {
+    if (!upper.has(c.level)) return false;
+    if (version === "2.1" && c.addedIn === "2.2") return false;
+    if (version === "2.2" && c.removedIn === "2.2") return false;
+    return true;
+  });
+}
+
+export function buildAxeTags(version, levels, includeBP = false) {
+  const versions = version === "2.2" ? ["wcag2", "wcag21", "wcag22"] : ["wcag2", "wcag21"];
+  const tags = [];
+  for (const v of versions) {
+    for (const lvl of levels) {
+      const suffix = v === "wcag2" ? "" : v.slice(4);
+      tags.push(`wcag${suffix}${lvl.toLowerCase()}`);
+    }
+  }
+  if (includeBP) tags.push("best-practice");
+  return tags;
+}