pour-engine 1.1.0

package/engine/rules/best-practice/positive-tabindex.js

@@ -0,0 +1,17 @@
+export default {
+  id: 'positive-tabindex',
+  impact: 'serious',
+  tags: ['best-practice'],
+  help: 'Positive tabindex values disrupt the natural focus order',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html',
+  selector: '[tabindex]',
+  evaluate(element) {
+    const tabindex = parseInt(element.getAttribute('tabindex'), 10);
+    if (!(tabindex > 0)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `tabindex="${tabindex}" overrides the natural focus order, which almost always creates a confusing keyboard path.`,
+      fix: 'Use tabindex="0" and place the element where it belongs in the document order instead.',
+    };
+  },
+};

package/engine/rules/best-practice/redundant-alt-phrase.js

@@ -0,0 +1,22 @@
+// "photo of"/"photograph of" is deliberately NOT flagged: for portraits it
+// conveys the medium (a photo of a person vs. a logo or illustration),
+// which is widely accepted alt style — flagging it is noise.
+const REDUNDANT_PHRASE = /^(image|picture|graphic|icon)\b( of\b)?/i;
+
+export default {
+  id: 'redundant-alt-phrase',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'alt text should not start with "image of" or similar',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/images/tips/',
+  selector: 'img[alt]',
+  evaluate(element) {
+    const alt = element.getAttribute('alt').trim();
+    if (!alt || !REDUNDANT_PHRASE.test(alt)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `alt="${alt}" — screen readers already announce this element as an image, so users hear "image, ${alt}".`,
+      fix: `Describe the content directly, e.g. alt="${alt.replace(REDUNDANT_PHRASE, '').trim() || '…'}".`,
+    };
+  },
+};

package/engine/rules/best-practice/redundant-aria-label.js

@@ -0,0 +1,18 @@
+export default {
+  id: 'redundant-aria-label',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'aria-label should not repeat the visible text',
+  helpUrl: 'https://www.w3.org/TR/using-aria/#rule2',
+  selector: '[aria-label]',
+  evaluate(element) {
+    const label = element.getAttribute('aria-label').replace(/\s+/g, ' ').trim().toLowerCase();
+    const visible = element.textContent.replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!visible || label !== visible) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `aria-label="${element.getAttribute('aria-label')}" is identical to the element's visible text — it adds nothing and will drift out of sync when the text changes.`,
+      fix: 'Remove the aria-label and let the visible text be the accessible name.',
+    };
+  },
+};

package/engine/rules/best-practice/redundant-aria.js

@@ -0,0 +1,32 @@
+// "Overdoing it" family: aria-* attributes that duplicate a native HTML
+// attribute the browser already exposes to assistive technology.
+const NATIVE_PAIRS = [
+  { aria: 'aria-required', native: 'required' },
+  { aria: 'aria-disabled', native: 'disabled' },
+  { aria: 'aria-readonly', native: 'readonly' },
+  { aria: 'aria-placeholder', native: 'placeholder' },
+  { aria: 'aria-checked', native: 'checked' },
+];
+
+export default {
+  id: 'redundant-aria',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'aria attributes should not duplicate native HTML attributes',
+  helpUrl: 'https://www.w3.org/TR/using-aria/#rule2',
+  selector: '[aria-required], [aria-disabled], [aria-readonly], [aria-placeholder], [aria-checked], [aria-hidden="false"]',
+  evaluate(element) {
+    const redundant = NATIVE_PAIRS
+      .filter(({ aria, native }) => element.hasAttribute(aria) && element.hasAttribute(native))
+      .map(({ aria, native }) => `${aria} duplicates ${native}`);
+    if (element.getAttribute('aria-hidden') === 'false') {
+      redundant.push('aria-hidden="false" does nothing reliable — elements are visible to AT by default');
+    }
+    if (!redundant.length) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `Redundant ARIA: ${redundant.join('; ')}. The native attribute already tells assistive technology everything.`,
+      fix: 'Remove the aria-* attribute(s) and keep the native HTML attribute.',
+    };
+  },
+};

package/engine/rules/best-practice/redundant-image-alt.js

@@ -0,0 +1,20 @@
+export default {
+  id: 'redundant-image-alt',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'Image alt should not repeat adjacent link or button text',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/images/functional/',
+  selector: 'a[href] img[alt], button img[alt]',
+  evaluate(element) {
+    const alt = element.getAttribute('alt').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!alt) return { status: 'pass' };
+    const container = element.closest('a[href], button');
+    const text = container.textContent.replace(/\s+/g, ' ').trim().toLowerCase();
+    if (alt !== text) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `The image alt repeats the ${container.tagName === 'A' ? 'link' : 'button'} text — screen readers announce "${element.getAttribute('alt')}" twice.`,
+      fix: 'Use alt="" on the image; the visible text already names the control.',
+    };
+  },
+};

package/engine/rules/best-practice/redundant-role.js

@@ -0,0 +1,62 @@
+// "Overdoing it" family: explicit role attributes that duplicate the
+// element's built-in (implicit) ARIA role are noise — they add maintenance
+// risk without helping assistive technology.
+const IMPLICIT_ROLES = {
+  ul: 'list', ol: 'list', li: 'listitem',
+  button: 'button', nav: 'navigation', main: 'main', aside: 'complementary',
+  form: 'form', table: 'table', article: 'article', img: 'img', hr: 'separator',
+  progress: 'progressbar', textarea: 'textbox', dialog: 'dialog', option: 'option',
+  h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+  // Table structure (th is skipped: its implicit role is contextual —
+  // columnheader or rowheader). header/footer/section are contextual too.
+  tr: 'row', thead: 'rowgroup', tbody: 'rowgroup', tfoot: 'rowgroup', td: 'cell',
+  fieldset: 'group',
+};
+
+const INPUT_ROLES = {
+  checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button',
+  text: 'textbox', email: 'textbox', tel: 'textbox', url: 'textbox',
+  range: 'slider', number: 'spinbutton', search: 'searchbox',
+};
+
+function implicitRole(element) {
+  const tag = element.tagName.toLowerCase();
+  if (tag === 'a') return element.hasAttribute('href') ? 'link' : null;
+  if (tag === 'input') return INPUT_ROLES[element.type] ?? null;
+  return IMPLICIT_ROLES[tag] ?? null;
+}
+
+export default {
+  id: 'redundant-role',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'role attributes should not repeat the element’s built-in role',
+  helpUrl: 'https://www.w3.org/TR/using-aria/#firstrule',
+  selector: '[role]',
+  evaluate(element) {
+    const explicit = element.getAttribute('role').trim().split(/\s+/)[0]?.toLowerCase();
+    const implicit = implicitRole(element);
+    if (!implicit || explicit !== implicit) return { status: 'pass' };
+    // The exceptions this rule's own advice describes are honoured, not
+    // just documented:
+    //  - role="list"/"listitem" on list-style:none lists is the standard
+    //    fix for Safari/VoiceOver dropping list semantics — keep it.
+    //  - role="img" on an SVG-source <img> is the standard fix for
+    //    VoiceOver skipping the alt text of SVG images — keep it.
+    if (explicit === 'list' && getComputedStyle(element).listStyleType === 'none') return { status: 'pass' };
+    if (explicit === 'listitem') {
+      const list = element.closest('ul, ol');
+      if (list && getComputedStyle(list).listStyleType === 'none') return { status: 'pass' };
+    }
+    if (explicit === 'img' && /\.svg([?#]|$)/i.test(element.currentSrc || element.src || '')) return { status: 'pass' };
+    const tag = element.tagName.toLowerCase();
+    const caveat = implicit === 'list'
+      ? ' (Exception: keep it if you set list-style: none — Safari/VoiceOver drops list semantics without it.)'
+      : '';
+    return {
+      status: 'fail',
+      message: `role="${explicit}" is redundant: <${tag}> already has that role built in. Redundant ARIA adds noise and drift risk, not accessibility.${caveat}`,
+      fix: `Remove role="${explicit}" from the <${tag}>.`,
+    };
+  },
+};

package/engine/rules/best-practice/redundant-tabindex.js

@@ -0,0 +1,15 @@
+export default {
+  id: 'redundant-tabindex',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'tabindex="0" is unnecessary on natively focusable elements',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html',
+  selector: 'button[tabindex="0"], a[href][tabindex="0"], input[tabindex="0"], select[tabindex="0"], textarea[tabindex="0"], summary[tabindex="0"]',
+  evaluate(element) {
+    return {
+      status: 'fail',
+      message: `<${element.tagName.toLowerCase()}> is focusable by default — tabindex="0" adds nothing.`,
+      fix: 'Remove the tabindex attribute.',
+    };
+  },
+};

package/engine/rules/best-practice/region.js

@@ -0,0 +1,73 @@
+const LANDMARK =
+  'main, nav, header, footer, aside, form[aria-label], form[aria-labelledby], ' +
+  'section[aria-label], section[aria-labelledby], [role="main"], [role="navigation"], ' +
+  '[role="banner"], [role="contentinfo"], [role="complementary"], [role="region"], ' +
+  '[role="search"], [role="form"], [role="dialog"]';
+
+export default {
+  id: 'region',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'All readable content belongs inside a landmark region',
+  helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
+  // Any element with its own text — wrapper elements without direct text are
+  // skipped, so each offending text block is reported exactly once.
+  selector: 'body *:not(script):not(style):not(template):not(noscript)',
+  // evaluateAll so document-level facts are computed ONCE per audit: a
+  // page with NO landmarks at all has one structural problem, not one per
+  // text block — landmark-one-main reports it once; flagging every
+  // paragraph (30k times on a single-page spec) is noise at ruinous
+  // serialization cost. region's per-block value is for pages that HAVE
+  // landmarks but leave content outside them.
+  evaluateAll(elements, helpers) {
+    const doc = elements[0]?.ownerDocument ?? document;
+    if (!doc.querySelector(LANDMARK)) return elements.map(() => ({ status: 'pass' }));
+    return elements.map((element) => this.judge(element, helpers));
+  },
+  judge(element, { ownText }) {
+    // Any perceivable content counts, not just text — but only content in
+    // the accessibility tree: decorative images (alt="", presentation) and
+    // unnamed inline svg are invisible to AT, so they can't be "unreachable".
+    const isMedia = element.matches(
+      'img:not([alt=""]):not([role="presentation"]):not([role="none"]), svg[role="img"], video, audio, canvas, iframe',
+    );
+    if (!ownText(element) && !isMedia) return { status: 'pass' };
+    if (element.closest(LANDMARK)) return { status: 'pass' };
+    const doc = element.ownerDocument;
+    // Skip links are the exception the spec itself creates: technique G1/G124
+    // (SC 2.4.1) requires them to be the first focusable controls on the
+    // page, which puts them before any landmark by construction. A same-page
+    // fragment link with a real target, sitting before the first landmark,
+    // is that pattern — not stray content. Anything after the first landmark
+    // (a floating table of contents, say) still counts.
+    const link = element.closest('a[href*="#"]');
+    if (link) {
+      // Anchors in the wild contain raw '%' that isn't valid
+      // percent-encoding (spec section links, e.g. "#sec-%-operator") —
+      // decodeURIComponent THROWS on those; fall back to the raw fragment.
+      let id = link.getAttribute('href').split('#')[1] ?? '';
+      try { id = decodeURIComponent(id); } catch { /* raw % in fragment: use as-is */ }
+      const target = id && (doc.getElementById(id) || doc.getElementsByName(id)[0]);
+      // "Skip to …" wording is the G1 pattern even when the target lives
+      // in a shadow root or the href routes through the page URL — the
+      // wording plus position-before-landmarks is evidence enough.
+      const looksLikeSkip = /^skip\b/i.test(link.textContent.trim());
+      const firstLandmark = doc.querySelector(LANDMARK);
+      const beforeLandmarks =
+        !firstLandmark ||
+        link.compareDocumentPosition(firstLandmark) & Node.DOCUMENT_POSITION_FOLLOWING;
+      if ((target || looksLikeSkip) && beforeLandmarks) return { status: 'pass' };
+    }
+    // One finding per branch: if an ancestor also has stray content it will
+    // be flagged itself — reporting the child too is duplicate noise
+    // (e.g. a link AND the span inside it).
+    for (let parent = element.parentElement; parent && parent !== doc.body; parent = parent.parentElement) {
+      if (ownText(parent)) return { status: 'pass' };
+    }
+    return {
+      status: 'fail',
+      message: 'This content sits outside any landmark, so screen-reader users navigating by regions never reach it.',
+      fix: 'Move it into <main>, <nav>, <header>, <footer>, <aside>, or a labelled <section>.',
+    };
+  },
+};

package/engine/rules/index.js

@@ -0,0 +1,179 @@
+// Rule registry. Add a rule: create the file in the right folder, import
+// it, add it here.
+//
+//   wcag/          — rules mapped to WCAG success criteria (spec-required;
+//                    tagged with wcag* criterion tags)
+//   best-practice/ — opt-in extras tagged 'best-practice': ARIA Authoring
+//                    Practices, WAI tutorial guidance, and our "overdoing
+//                    it" redundancy family. Never tagged as WCAG.
+
+// --- WCAG ---
+import documentTitle from './wcag/2.4.2-document-title.js';
+import htmlLang from './wcag/3.1.1-html-lang.js';
+import validLangParts from './wcag/3.1.2-valid-lang-parts.js';
+import imageAlt from './wcag/1.1.1-image-alt.js';
+import svgImgAlt from './wcag/1.1.1-svg-img-alt.js';
+import buttonName from './wcag/4.1.2-button-name.js';
+import linkName from './wcag/2.4.4-link-name.js';
+// Parked by product decision (2026-07-29): label-in-name excluded from runs
+// for now — restore the import and registry entry below to bring it back.
+// import labelInName from './wcag/2.5.3-label-in-name.js';
+import formLabel from './wcag/1.3.1-form-label.js';
+import autocompleteValid from './wcag/1.3.5-autocomplete-valid.js';
+import metaViewport from './wcag/1.4.4-meta-viewport.js';
+import colorContrast from './wcag/1.4.3-color-contrast.js';
+import frameTitle from './wcag/4.1.2-frame-title.js';
+import ariaValidRefs from './wcag/4.1.2-aria-valid-refs.js';
+import validRole from './wcag/4.1.2-valid-role.js';
+import ariaHiddenFocus from './wcag/4.1.2-aria-hidden-focus.js';
+import listStructure from './wcag/1.3.1-list-structure.js';
+import nestedInteractive from './wcag/4.1.2-nested-interactive.js';
+import bypassBlocks from './wcag/2.4.1-bypass-blocks.js';
+import targetSize from './wcag/2.5.8-target-size.js';
+import audioControl from './wcag/1.4.2-audio-control.js';
+import pauseStopHide from './wcag/2.2.2-pause-stop-hide.js';
+import mediaCaptions from './wcag/1.2.2-media-captions.js';
+import ariaAttrValid from './wcag/4.1.2-aria-attr-valid.js';
+import ariaAllowedAttr from './wcag/4.1.2-aria-allowed-attr.js';
+import ariaFieldName from './wcag/4.1.2-aria-field-name.js';
+// Demoted to best-practice: prohibited-but-inert ARIA on a generic element
+// fails no success criterion (see the note in the rule file).
+import ariaLabelMisuse from './best-practice/aria-label-misuse.js';
+import roleRequiredAria from './wcag/4.1.2-role-required-aria.js';
+import labelForValid from './wcag/4.1.2-label-for-valid.js';
+import listitemParent from './wcag/1.3.1-listitem-parent.js';
+import definitionList from './wcag/1.3.1-definition-list.js';
+import dlitemParent from './wcag/1.3.1-dlitem-parent.js';
+import areaAlt from './wcag/1.1.1-area-alt.js';
+import objectAlt from './wcag/1.1.1-object-alt.js';
+import inputImageAlt from './wcag/1.1.1-input-image-alt.js';
+// Demoted to best-practice: multiple labels are valid HTML that 3.3.2
+// does not prohibit (see the note in the rule file).
+import multipleLabels from './best-practice/multiple-labels.js';
+import metaRefresh from './wcag/2.2.1-meta-refresh.js';
+import linkInTextBlock from './wcag/1.4.1-link-in-text-block.js';
+import pAsHeading from './wcag/1.3.1-p-as-heading.js';
+import ariaRequiredChildren from './wcag/1.3.1-aria-required-children.js';
+import ariaRequiredParent from './wcag/1.3.1-aria-required-parent.js';
+import scrollableRegionFocusable from './wcag/2.1.1-scrollable-region-focusable.js';
+import tableHeaders from './wcag/1.3.1-table-headers.js';
+import contrastEnhanced from './wcag/1.4.6-contrast-enhanced.js';
+import targetSizeEnhanced from './wcag/2.5.5-target-size-enhanced.js';
+import dialogName from './wcag/4.1.2-dialog-name.js';
+import controlContrast from './wcag/1.4.3-control-contrast.js';
+import nonTextContrast from './wcag/1.4.11-non-text-contrast.js';
+import textSpacing from './wcag/1.4.12-text-spacing.js';
+import reflow from './wcag/1.4.10-reflow.js';
+import focusVisible from './wcag/2.4.7-focus-visible.js';
+import focusNotObscured from './wcag/2.4.11-focus-not-obscured.js';
+import authFieldObstruction from './wcag/3.3.8-auth-field-obstruction.js';
+
+// --- Best practice ---
+import headingOrder from './best-practice/heading-order.js';
+import emptyHeading from './best-practice/empty-heading.js';
+import positiveTabindex from './best-practice/positive-tabindex.js';
+import region from './best-practice/region.js';
+import landmarkOneMain from './best-practice/landmark-one-main.js';
+import pageHeadingOne from './best-practice/page-heading-one.js';
+import landmarkUnique from './best-practice/landmark-unique.js';
+import redundantRole from './best-practice/redundant-role.js';
+import redundantAria from './best-practice/redundant-aria.js';
+import redundantAriaLabel from './best-practice/redundant-aria-label.js';
+import redundantAltPhrase from './best-practice/redundant-alt-phrase.js';
+import redundantTabindex from './best-practice/redundant-tabindex.js';
+import redundantImageAlt from './best-practice/redundant-image-alt.js';
+import landmarkTopLevel from './best-practice/landmark-top-level.js';
+import accesskeys from './best-practice/accesskeys.js';
+import buttonType from './best-practice/button-type.js';
+import noAutofocus from './best-practice/no-autofocus.js';
+import newWindowLink from './best-practice/new-window-link.js';
+import fieldsetLegend from './best-practice/fieldset-legend.js';
+
+/** Sort key: primary WCAG SC (numeric), best-practice rules after all WCAG
+ *  rules, ties by rule id. Execution order doesn't change any verdict —
+ *  spec order just makes progress display and reports predictable. */
+function scKey(rule) {
+  const tag = rule.tags.find((t) => /^wcag\d{3,4}$/.test(t));
+  if (!tag) return [9, 9, 99];
+  const digits = tag.slice(4);
+  return [+digits[0], +digits[1], +digits.slice(2)];
+}
+
+export default [
+  documentTitle,
+  htmlLang,
+  validLangParts,
+  imageAlt,
+  svgImgAlt,
+  buttonName,
+  linkName,
+  // labelInName, — parked 2026-07-29, see note at the import
+  formLabel,
+  autocompleteValid,
+  metaViewport,
+  colorContrast,
+  frameTitle,
+  ariaValidRefs,
+  validRole,
+  ariaHiddenFocus,
+  listStructure,
+  nestedInteractive,
+  bypassBlocks,
+  targetSize,
+  audioControl,
+  pauseStopHide,
+  mediaCaptions,
+  ariaAttrValid,
+  ariaAllowedAttr,
+  ariaFieldName,
+  ariaLabelMisuse,
+  roleRequiredAria,
+  labelForValid,
+  listitemParent,
+  definitionList,
+  dlitemParent,
+  areaAlt,
+  objectAlt,
+  inputImageAlt,
+  multipleLabels,
+  metaRefresh,
+  linkInTextBlock,
+  pAsHeading,
+  ariaRequiredChildren,
+  ariaRequiredParent,
+  scrollableRegionFocusable,
+  tableHeaders,
+  dialogName,
+  controlContrast,
+  nonTextContrast,
+  textSpacing,
+  reflow,
+  focusVisible,
+  focusNotObscured,
+  authFieldObstruction,
+  contrastEnhanced,
+  targetSizeEnhanced,
+  headingOrder,
+  emptyHeading,
+  positiveTabindex,
+  region,
+  landmarkOneMain,
+  pageHeadingOne,
+  landmarkUnique,
+  redundantRole,
+  redundantAria,
+  redundantAriaLabel,
+  redundantAltPhrase,
+  redundantTabindex,
+  redundantImageAlt,
+  landmarkTopLevel,
+  accesskeys,
+  buttonType,
+  noAutofocus,
+  newWindowLink,
+  fieldsetLegend,
+].sort((a, b) => {
+  const ka = scKey(a);
+  const kb = scKey(b);
+  return (ka[0] - kb[0]) || (ka[1] - kb[1]) || (ka[2] - kb[2]) || a.id.localeCompare(b.id);
+});

package/engine/rules/wcag/1.1.1-area-alt.js

@@ -0,0 +1,18 @@
+// WCAG SC 1.1.1 Non-text Content (Level A) · SC 2.4.4 Link Purpose (In Context) (Level A)
+export default {
+  id: 'area-alt',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag111', 'wcag244'],
+  help: 'Image map areas must have alternative text',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
+  selector: 'map area[href]',
+  visibleOnly: false,
+  evaluate(element, { accessibleName }) {
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This clickable map area has no alt text — screen readers announce nothing for it.',
+      fix: 'Add alt="Where this area links to".',
+    };
+  },
+};

package/engine/rules/wcag/1.1.1-image-alt.js

@@ -0,0 +1,48 @@
+// WCAG SC 1.1.1 Non-text Content (Level A)
+// alt="" (exactly empty) is the CONFORMING decorative marker (H67) — it
+// hides the image from screen readers on purpose and passes. A
+// whitespace-only alt is neither a text alternative nor that marker:
+// assistive technology handles it inconsistently (some announce the file
+// name, some skip it) — that fails. Filename/generic alts technically
+// satisfy presence but tell the user nothing (F30/F39) — flagged for eyes.
+const FILENAME_ALT = /\.(png|jpe?g|gif|webp|svg|avif|bmp|ico)([?#].*)?$/i;
+const GENERIC_ALT = /^(image|img|photo|photograph|picture|graphic|icon|untitled|placeholder|spacer|\d+)$/i;
+
+export default {
+  id: 'image-alt',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag111'],
+  help: 'Every <img> needs a text alternative',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
+  selector: 'img',
+  evaluate(element, { accessibleName }) {
+    const role = element.getAttribute('role');
+    if (role === 'presentation' || role === 'none') return { status: 'pass' };
+    if (element.hasAttribute('alt')) {
+      const alt = element.getAttribute('alt');
+      // alt="" marks the image decorative — valid and deliberate.
+      if (alt === '') return { status: 'pass' };
+      if (!alt.trim()) {
+        return {
+          status: 'fail',
+          message: `alt="${alt}" is only whitespace — neither a text alternative nor the decorative marker (alt="" exactly); screen readers handle it unpredictably, some falling back to the file name.`,
+          fix: 'Use alt="" (nothing between the quotes) for decorative images, or write a real description.',
+        };
+      }
+      const trimmed = alt.trim();
+      if (FILENAME_ALT.test(trimmed) || GENERIC_ALT.test(trimmed)) {
+        return {
+          status: 'incomplete',
+          message: `alt="${trimmed}" looks like a file name or placeholder, not a description — screen-reader users learn nothing from it. If the image carries meaning, describe it; if not, use alt="".`,
+        };
+      }
+      return { status: 'pass' };
+    }
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This image has no alt attribute, so screen readers announce its file name or nothing at all.',
+      fix: `Describe the image: <img alt="…" src="${element.getAttribute('src') ?? ''}">, or mark it decorative with alt="".`,
+    };
+  },
+};

package/engine/rules/wcag/1.1.1-input-image-alt.js

@@ -0,0 +1,17 @@
+// WCAG SC 1.1.1 Non-text Content (Level A) · SC 4.1.2 Name, Role, Value (Level A)
+export default {
+  id: 'input-image-alt',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag111', 'wcag412'],
+  help: 'Image inputs need alt text describing their action',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
+  selector: 'input[type="image"]',
+  evaluate(element, { accessibleName }) {
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This image button has no alt text — screen readers announce just "button".',
+      fix: 'Add alt="What the button does", e.g. alt="Search".',
+    };
+  },
+};

package/engine/rules/wcag/1.1.1-object-alt.js

@@ -0,0 +1,17 @@
+// WCAG SC 1.1.1 Non-text Content (Level A)
+export default {
+  id: 'object-alt',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag111'],
+  help: '<object> embeds must have a text alternative',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
+  selector: 'object',
+  evaluate(element, { accessibleName }) {
+    if (accessibleName(element) || element.textContent.trim()) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This embedded object has no text alternative — users who can’t see it get nothing.',
+      fix: 'Add aria-label="…", or fallback content inside the <object> element.',
+    };
+  },
+};

package/engine/rules/wcag/1.1.1-svg-img-alt.js

@@ -0,0 +1,34 @@
+// WCAG SC 1.1.1 Non-text Content (Level A)
+export default {
+  id: 'svg-img-alt',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag111'],
+  help: 'Inline SVG and role="img" graphics need an accessible name',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
+  // <img> itself is handled by image-alt; this covers SVG (with or without a
+  // role) and role="img" divs/spans. Top-level plain <svg> is included
+  // because browsers expose it to AT as a graphic even without a role.
+  selector: 'svg[role="img"], svg[role="graphics-document"], svg[role="graphics-symbol"], [role="img"]:not(img):not(svg), svg:not([role])',
+  evaluate(element, { accessibleName }) {
+    if (accessibleName(element)) return { status: 'pass' };
+    if (!element.getAttribute('role') && element.tagName.toLowerCase() === 'svg') {
+      if (element.parentNode instanceof SVGElement) return { status: 'pass' }; // nested svg: part of the outer graphic
+      // Inside a control that already has a name, the svg is effectively
+      // decorative icon-work — the name covers it.
+      const control = element.closest('a[href], button, [role="button"], [role="link"]');
+      if (control && accessibleName(control)) return { status: 'pass' };
+      // Unlabeled and roleless: AT behaviour varies, and we can't tell
+      // meaningful from decorative — a human call, not an automatic fail.
+      return {
+        status: 'incomplete',
+        message: 'This SVG has no accessible name and is not marked decorative — some screen readers announce it as an unlabeled graphic.',
+        fix: 'Add aria-hidden="true" if decorative; if meaningful, add role="img" and aria-label="…" (or a <title> as the first child).',
+      };
+    }
+    return {
+      status: 'fail',
+      message: 'This element is marked as an image but has no accessible name.',
+      fix: 'Add aria-label="…" (for SVG, a <title> as the first child also works).',
+    };
+  },
+};

package/engine/rules/wcag/1.2.2-media-captions.js

@@ -0,0 +1,19 @@
+// WCAG SC 1.2.2 Captions (Prerecorded) (Level A)
+export default {
+  id: 'media-captions',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag122'],
+  help: 'Video content must have captions',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/captions-prerecorded.html',
+  selector: 'video',
+  visibleOnly: false,
+  evaluate(element) {
+    if (element.querySelector('track[kind="captions"], track[kind="subtitles"]')) return { status: 'pass' };
+    // Captions may be burned in or provided by the player — a human must check.
+    return {
+      status: 'incomplete',
+      message: 'No caption track found on this video. If captions aren’t burned in or provided by the player, deaf and hard-of-hearing users are excluded — please verify.',
+      fix: 'Add <track kind="captions" src="…" srclang="…" label="…"> with a WebVTT file.',
+    };
+  },
+};