pour-engine 1.1.0

package/engine/rules/wcag/1.3.1-aria-required-children.js

@@ -0,0 +1,66 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+// Composite roles are meaningless without their required child roles —
+// role="list" with no listitems announces as an empty list.
+const REQUIRED_CHILDREN = {
+  list: ['listitem'],
+  listbox: ['option', 'group'],
+  menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'group'],
+  menubar: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'group'],
+  radiogroup: ['radio'],
+  tablist: ['tab'],
+  tree: ['treeitem', 'group'],
+  table: ['row', 'rowgroup'],
+  grid: ['row', 'rowgroup'],
+  treegrid: ['row', 'rowgroup'],
+  rowgroup: ['row'],
+};
+
+const IMPLICIT = { li: 'listitem', option: 'option', tr: 'row', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup' };
+
+const roleOf = (element) =>
+  element.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
+  IMPLICIT[element.tagName.toLowerCase()];
+
+/**
+ * The children a composite role OWNS in the accessibility tree — not the
+ * DOM children. role="presentation"/"none" removes an element but leaves
+ * its children in place, and role-less div/span wrappers are generic nodes
+ * the required-ownership relation passes straight through (tabs inside a
+ * styling wrapper inside a tablist are still the tablist's tabs).
+ */
+function ownedChildren(element) {
+  const owned = [];
+  for (const child of element.children) {
+    if (child.matches('script, style, template')) continue;
+    const role = child.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase();
+    const passThrough = role === 'presentation' || role === 'none'
+      || (!role && (child.tagName === 'DIV' || child.tagName === 'SPAN'));
+    if (passThrough) owned.push(...ownedChildren(child));
+    else owned.push(child);
+  }
+  return owned;
+}
+
+export default {
+  id: 'aria-required-children',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag131'],
+  help: 'Composite ARIA roles must contain their required children',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: Object.keys(REQUIRED_CHILDREN).map((role) => `[role="${role}"]`).join(', '),
+  evaluate(element) {
+    if (element.getAttribute('aria-busy') === 'true') return { status: 'pass' }; // still loading
+    const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
+    const required = REQUIRED_CHILDREN[role];
+    const children = [...element.children].filter((c) => !c.matches('script, style, template'));
+    // A completely empty container is a lazy-load placeholder more often
+    // than a defect — it announces as an empty list, which is accurate.
+    if (!children.length) return { status: 'pass' };
+    if (ownedChildren(element).some((child) => required.includes(roleOf(child)))) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `role="${role}" contains no ${required.join('/')} children (not even through wrapper elements) — screen readers announce a broken, empty ${role}.`,
+      fix: `Give the item elements role="${required[0]}", or remove role="${role}" from the container.`,
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-aria-required-parent.js

@@ -0,0 +1,49 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+// Child roles that only make sense inside a specific container role.
+// Explicit roles only — native elements (li outside ul) are covered by
+// listitem-parent/dlitem-parent.
+const REQUIRED_PARENT = {
+  listitem: ['list'],
+  option: ['listbox'],
+  menuitem: ['menu', 'menubar'],
+  menuitemcheckbox: ['menu', 'menubar'],
+  menuitemradio: ['menu', 'menubar'],
+  tab: ['tablist'],
+  treeitem: ['tree'],
+  row: ['table', 'grid', 'treegrid', 'rowgroup'],
+  rowgroup: ['table', 'grid', 'treegrid'],
+  cell: ['row'],
+  gridcell: ['row'],
+};
+
+const IMPLICIT_CONTAINER = { ul: 'list', ol: 'list', menu: 'list', table: 'table', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup', tr: 'row' };
+
+export default {
+  id: 'aria-required-parent',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag131'],
+  help: 'ARIA child roles must be inside their required container role',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: Object.keys(REQUIRED_PARENT).map((role) => `[role="${role}"]`).join(', '),
+  evaluate(element) {
+    const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
+    const containers = REQUIRED_PARENT[role];
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+      const parentRole =
+        parent.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
+        IMPLICIT_CONTAINER[parent.tagName.toLowerCase()];
+      if (parentRole === 'group') continue; // group is transparent in these structures
+      // presentation/none removes the wrapper from the tree but leaves its
+      // children owned by the next real ancestor — li[role=presentation]
+      // between a tablist and its tabs is the canonical pattern.
+      if (parentRole === 'presentation' || parentRole === 'none') continue;
+      if (containers.includes(parentRole)) return { status: 'pass' };
+      if (parentRole) break; // a different role interrupts the required structure
+    }
+    return {
+      status: 'fail',
+      message: `role="${role}" is not inside a ${containers.join('/')} — assistive technology loses the structure entirely.`,
+      fix: `Wrap it in an element with role="${containers[0]}", or fix the intervening roles.`,
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-definition-list.js

@@ -0,0 +1,21 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+const ALLOWED = new Set(['DT', 'DD', 'DIV', 'SCRIPT', 'TEMPLATE']);
+
+export default {
+  id: 'definition-list',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: '<dl> must be structured as term/description pairs',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'dl:not([role])', // a role attribute replaces the dl semantics
+  evaluate(element) {
+    const invalid = [...element.children].filter((child) => !ALLOWED.has(child.tagName));
+    if (!invalid.length) return { status: 'pass' };
+    const tags = [...new Set(invalid.map((child) => `<${child.tagName.toLowerCase()}>`))].join(', ');
+    return {
+      status: 'fail',
+      message: `This <dl> contains ${tags} directly — only <dt>, <dd> (optionally grouped in <div>) are allowed, otherwise the term/description pairing breaks.`,
+      fix: 'Restructure the list into <dt>/<dd> pairs, or use a different element.',
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-dlitem-parent.js

@@ -0,0 +1,17 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+export default {
+  id: 'dlitem-parent',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: '<dt> and <dd> must be inside a <dl>',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'dt:not([role]), dd:not([role])', // role overrides the dt/dd semantics
+  evaluate(element) {
+    if (element.closest('dl')) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `<${element.tagName.toLowerCase()}> outside a <dl> has no term/description semantics.`,
+      fix: 'Wrap the terms and descriptions in a <dl>, or use different elements.',
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-form-label.js

@@ -0,0 +1,81 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A) · SC 3.3.2 Labels or
+// Instructions (Level A) · SC 4.1.2 Name, Role, Value (Level A)
+// 3.3.2 mapping: a field with no label at all, or only a vanishing
+// placeholder, is failure F82 — the classic 3.3.2 pattern.
+export default {
+  id: 'form-label',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag131', 'wcag332', 'wcag412'],
+  help: 'Every form field needs a visible label',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector:
+    'input:not([type="hidden"]):not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="image"]), select, textarea',
+  evaluate(element) {
+    // Only perceivable labels count: a display:none / aria-hidden label
+    // technically feeds the accessible name, but nobody can see it and
+    // that defeats the point of a label.
+    const visibleLabels = [...(element.labels ?? [])].filter((label) => {
+      if (label.closest('[aria-hidden="true"]')) return false;
+      const style = getComputedStyle(label);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+    // Label content includes aria-labels on things inside it (icon-only
+    // labels like <label><svg aria-label="Dark mode"/></label> still name)
+    // and image alts (<label><img alt="…"></label> is a visible, named
+    // label — alt text feeds name-from-contents per accname).
+    const labelsText = visibleLabels
+      .map((l) =>
+        `${l.textContent} ${[...l.querySelectorAll('[aria-label], img[alt], area[alt]')]
+          .map((e) => e.getAttribute('aria-label') ?? e.getAttribute('alt')).join(' ')}`)
+      .join(' ')
+      .trim();
+    const ariaLabel = element.getAttribute('aria-label')?.trim();
+    const labelledby = (element.getAttribute('aria-labelledby') ?? '')
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((id) => element.getRootNode().getElementById?.(id)?.textContent ?? '')
+      .join(' ')
+      .trim();
+    if (labelsText || ariaLabel || labelledby) return { status: 'pass' };
+
+    const id = element.id ? ` (it already has id="${element.id}")` : ' (give it an id first)';
+
+    // A title-only name is published sufficient technique H65 — conformant,
+    // but invisible until hover and ignored by some tools, so it's flagged
+    // for eyes rather than failed.
+    if (element.getAttribute('title') && !element.getAttribute('placeholder')) {
+      return {
+        status: 'incomplete',
+        message: 'This field is named only by its title attribute (technique H65) — conformant, but the label is invisible until hover and some tools skip it. Check a visible label isn’t needed here.',
+      };
+    }
+    // A placeholder-only "label" vanishes as soon as the user types (F82
+    // territory) — that one stays a failure.
+    if (element.getAttribute('placeholder')) {
+      return {
+        status: 'fail',
+        message: 'This field relies on its placeholder as the only label — the name vanishes as soon as the user types.',
+        fix: `Add <label for="…">Field name</label> pointing at this field${id}; keep the placeholder as an example value only.`,
+      };
+    }
+    if (element.labels?.length && !visibleLabels.length) {
+      return {
+        status: 'fail',
+        message: 'This field\'s only <label> is hidden (display:none or aria-hidden) — no one can see or rely on it.',
+        fix: 'Make the label visible, or use a visually-hidden-but-rendered technique (clip/sr-only) if it must not show.',
+      };
+    }
+    if (element.labels?.length) {
+      return {
+        status: 'fail',
+        message: 'This field has a <label>, but the label is empty — it announces nothing.',
+        fix: 'Put visible text inside the label.',
+      };
+    }
+    return {
+      status: 'fail',
+      message: 'This form field has no label — users cannot tell what to enter.',
+      fix: `Add <label for="…">Field name</label> pointing at this field${id}.`,
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-list-structure.js

@@ -0,0 +1,59 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE']);
+const ITEM_ROLES = ['listitem', 'presentation', 'none'];
+
+export default {
+  id: 'list-structure',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: 'Lists must only contain list items',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'ul, ol',
+  evaluate(element) {
+    // A role attribute replaces the HTML list semantics — a <ul role="tablist">
+    // is judged by ARIA structure rules, not HTML list rules.
+    if (element.hasAttribute('role') && element.getAttribute('role') !== 'list') return { status: 'pass' };
+    // Flat-tree children: a <slot> renders as its assigned elements (or its
+    // fallback content), so a shadow <ul><slot></slot></ul> receiving <li>s
+    // is a perfectly valid list.
+    const effectiveChildren = (parent) => [...parent.children].flatMap((child) =>
+      child.tagName === 'SLOT'
+        ? (child.assignedElements?.().length ? child.assignedElements() : [...child.children])
+        : [child]);
+    // Role-less div/span wrappers are generic nodes the accessibility tree
+    // passes list ownership through — a <ul><div><li>…</li></div></ul>
+    // (framework grouping wrappers) still announces size and structure
+    // correctly, so it's judged by what the wrapper holds, recursively.
+    // Only PURE wrappers qualify: direct text of its own means the element
+    // is content, not plumbing — that text sits outside any list item and
+    // genuinely corrupts the list.
+    const isValidChild = (child) => {
+      if (NEVER_RENDERED.has(child.tagName)) return true;
+      // An explicit role REPLACES an <li>'s listitem semantics: a carousel
+      // built as <ul> with <li role="group"> slides no longer owns any
+      // listitems, so the list announces broken/empty. Only a role-less
+      // <li> (or an explicit listitem/presentation/none anywhere) keeps
+      // the structure intact.
+      const role = child.getAttribute('role') ?? '';
+      if (child.tagName === 'LI') return !role || ITEM_ROLES.includes(role);
+      if (ITEM_ROLES.includes(role)) return true;
+      const genericWrapper = !child.hasAttribute('role')
+        && (child.tagName === 'DIV' || child.tagName === 'SPAN');
+      if (!genericWrapper) return false;
+      const hasStrayText = [...child.childNodes].some(
+        (node) => node.nodeType === Node.TEXT_NODE && node.textContent.trim());
+      return !hasStrayText && effectiveChildren(child).every(isValidChild);
+    };
+    const invalid = effectiveChildren(element).filter((child) => !isValidChild(child));
+    if (!invalid.length) return { status: 'pass' };
+    const tags = [...new Set(invalid.map((child) => {
+      const role = child.getAttribute('role');
+      return `<${child.tagName.toLowerCase()}${role ? ` role="${role}"` : ''}>`;
+    }))].join(', ');
+    return {
+      status: 'fail',
+      message: `This list has ${invalid.length} direct child(ren) without listitem semantics (${tags}) — screen readers misreport the list's size and structure.`,
+      fix: 'Use plain <li> children (an explicit role like role="group" replaces the listitem role), or move non-item elements outside the list.',
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-listitem-parent.js

@@ -0,0 +1,33 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+export default {
+  id: 'listitem-parent',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: '<li> must be inside a list',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'li:not([role])', // a role attribute replaces the listitem semantics
+  evaluate(element) {
+    // Judge the FLAT-tree parent — what assistive technology actually sees:
+    // a slotted <li> belongs to the <ul> around its slot, and an <li> at the
+    // top of a shadow tree belongs to its host element.
+    let parent = element.assignedSlot?.parentElement ?? element.parentElement ?? element.getRootNode()?.host;
+    while (parent?.tagName === 'SLOT') parent = parent.assignedSlot?.parentElement ?? parent.parentElement;
+    // List ownership passes through presentation/none wrappers and
+    // role-less div/span grouping wrappers (generic nodes) — an <li> in a
+    // framework's wrapping div inside a <ul> is still that list's item.
+    while (parent && (
+      ['presentation', 'none'].includes(parent.getAttribute('role') ?? '')
+      || (!parent.hasAttribute('role') && (parent.tagName === 'DIV' || parent.tagName === 'SPAN'))
+    )) {
+      parent = parent.assignedSlot?.parentElement ?? parent.parentElement ?? parent.getRootNode()?.host;
+    }
+    if (parent && (parent.matches('ul, ol, menu') || parent.getAttribute('role') === 'list')) {
+      return { status: 'pass' };
+    }
+    return {
+      status: 'fail',
+      message: `This <li> sits inside <${parent?.tagName.toLowerCase() ?? 'nothing'}> — outside a list, screen readers lose the item's list context entirely.`,
+      fix: 'Wrap it in a <ul> or <ol>, or change it to a <div>/<p> if it isn’t really a list item.',
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-p-as-heading.js

@@ -0,0 +1,25 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+export default {
+  id: 'p-as-heading',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: 'Bold paragraphs should not stand in for headings',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'p',
+  evaluate(element) {
+    const text = element.textContent.trim();
+    const only = element.children.length === 1 && element.children[0];
+    const looksLikeHeading =
+      text && text.length < 60 &&
+      only && only.matches('b, strong') && only.textContent.trim() === text &&
+      element.nextElementSibling?.matches('p');
+    if (!looksLikeHeading) return { status: 'pass' };
+    // A heuristic, not proof — bold lead-ins are a legitimate style, so this
+    // asks for review instead of asserting a violation.
+    return {
+      status: 'incomplete',
+      message: `"${text}" is a short bold paragraph followed by text — if it's acting as a heading, it's invisible to heading navigation. Verify.`,
+      fix: 'If it is a heading, use a real heading element (<h2>…</h2>) at the appropriate level.',
+    };
+  },
+};

package/engine/rules/wcag/1.3.1-table-headers.js

@@ -0,0 +1,61 @@
+// WCAG SC 1.3.1 Info and Relationships (Level A)
+// WCAG 1.3.1: data tables must expose their header/data relationships in
+// markup. Two failure modes, reported per TABLE (one fix point), not per
+// cell:
+//   - a clear data table with no header cells at all (no th, scope, headers)
+//   - headers="" attributes referencing ids that aren't cells of this table
+// Layout tables are skipped via a conservative heuristic (role=presentation,
+// or too small/text-sparse to be a data grid) — a missed layout table is
+// better than false positives on real pages.
+export default {
+  id: 'table-headers',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag131'],
+  help: 'Data tables must have properly associated header cells',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
+  selector: 'table',
+  evaluate(element) {
+    const role = element.getAttribute('role');
+    if (role && !['table', 'grid'].includes(role)) return { status: 'pass' }; // presentation/none/other widget
+    const rows = [...element.rows];
+    const cells = rows.flatMap((row) => [...row.cells]);
+    // Data-grid heuristic: at least a 2×2 grid with mostly-text cells.
+    const isGrid = rows.length >= 2 && Math.max(0, ...rows.map((row) => row.cells.length)) >= 2;
+    const textCells = cells.filter((cell) => cell.textContent.trim()).length;
+    if (!isGrid || textCells < 4) return { status: 'pass' }; // likely layout or trivial
+    // Nested tables are the signature of legacy LAYOUT markup, not data —
+    // asserting "missing headers" there flags email-style scaffolding. A
+    // human can tell in a glance; the machine can't.
+    if (!element.querySelector('th') && element.querySelector('table')) {
+      return {
+        status: 'incomplete',
+        message: 'This table has no header cells but contains nested tables — a layout-table signature. If it really presents data, mark its header cells with <th>; if it is layout scaffolding, add role="presentation".',
+      };
+    }
+
+    const badRefs = cells.filter((cell) => {
+      const headers = cell.getAttribute('headers');
+      return headers && headers.trim().split(/\s+/).filter(Boolean).some((id) => {
+        const target = element.getRootNode().getElementById?.(id);
+        return !target || !element.contains(target) || !/^T[HD]$/.test(target.tagName);
+      });
+    });
+    if (badRefs.length) {
+      return {
+        status: 'fail',
+        message: `${badRefs.length} cell(s) have headers="…" referencing ids that are not header cells of this table — screen readers cannot relate the data to its headers.`,
+        fix: 'Make each headers attribute list the id(s) of <th> cells in the same table.',
+      };
+    }
+
+    const hasHeaders = element.querySelector('th, [scope], td[headers]');
+    if (!hasHeaders) {
+      return {
+        status: 'fail',
+        message: 'This looks like a data table but has no header cells — screen reader users get the data with no way to tell what each row/column means.',
+        fix: 'Mark header cells with <th> (add scope="col" or scope="row" when the table has both).',
+      };
+    }
+    return { status: 'pass' };
+  },
+};

package/engine/rules/wcag/1.3.5-autocomplete-valid.js

@@ -0,0 +1,38 @@
+// WCAG SC 1.3.5 Identify Input Purpose (Level AA)
+// WCAG 1.3.5: autocomplete tokens from the HTML spec's input-purposes list.
+const TOKENS = new Set([
+  'on', 'off', 'name', 'honorific-prefix', 'given-name', 'additional-name', 'family-name',
+  'honorific-suffix', 'nickname', 'organization-title', 'username', 'new-password',
+  'current-password', 'one-time-code', 'organization', 'street-address', 'address-line1',
+  'address-line2', 'address-line3', 'address-level1', 'address-level2', 'address-level3',
+  'address-level4', 'country', 'country-name', 'postal-code', 'cc-name', 'cc-given-name',
+  'cc-additional-name', 'cc-family-name', 'cc-number', 'cc-exp', 'cc-exp-month', 'cc-exp-year',
+  'cc-csc', 'cc-type', 'transaction-currency', 'transaction-amount', 'language', 'bday',
+  'bday-day', 'bday-month', 'bday-year', 'sex', 'url', 'photo', 'tel', 'tel-country-code',
+  'tel-national', 'tel-area-code', 'tel-local', 'tel-local-prefix', 'tel-local-suffix',
+  'tel-extension', 'email', 'impp', 'webauthn', 'shipping', 'billing', 'home', 'work',
+  'mobile', 'fax', 'pager',
+]);
+
+export default {
+  id: 'autocomplete-valid',
+  impact: 'serious',
+  tags: ['wcag21aa', 'wcag135'],
+  help: 'autocomplete attributes must use valid tokens',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html',
+  selector: 'input[autocomplete], select[autocomplete], textarea[autocomplete]',
+  evaluate(element) {
+    const invalid = element
+      .getAttribute('autocomplete')
+      .trim()
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((token) => token && !TOKENS.has(token) && !token.startsWith('section-'));
+    if (!invalid.length) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `autocomplete contains unknown token(s): ${invalid.join(', ')} — browsers and assistive tools can't identify this field's purpose.`,
+      fix: 'Use tokens from the HTML input-purposes list, e.g. autocomplete="email" or autocomplete="given-name".',
+    };
+  },
+};

package/engine/rules/wcag/1.4.1-link-in-text-block.js

@@ -0,0 +1,74 @@
+// WCAG SC 1.4.1 Use of Color (Level A)
+import { parseColor, contrastRatio } from '../../lib/contrast.js';
+
+export default {
+  id: 'link-in-text-block',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag141'],
+  help: 'Links inside text must be distinguishable by more than colour',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html',
+  // Only running prose counts as a "text block" — lists of links (navs,
+  // blogrolls) are identified by their structure, not by colour.
+  selector: 'p a[href], dd a[href], blockquote a[href], td a[href]',
+  visibility: 'visual', // colour distinction is a purely visual concern
+  evaluate(element, { ownText }) {
+    const parent = element.closest('p, dd, blockquote, td');
+    if (!element.textContent.trim() || !parent) return { status: 'pass' };
+    // Needs real surrounding text to blend into (1.4.1 is about links
+    // embedded in prose, not a link that IS the content).
+    if (ownText(parent).replace(/\s+/g, '').length < 10) return { status: 'pass' };
+
+    const style = getComputedStyle(element);
+    if ((style.textDecorationLine ?? style.textDecoration ?? '').includes('underline')) return { status: 'pass' };
+    // Underline substitutes count as non-colour cues too: border-bottom
+    // "underlines", box-shadow underlines, and background chips/pills all
+    // mark the link by shape, not colour alone.
+    if (parseFloat(style.borderBottomWidth) > 0 && style.borderBottomStyle !== 'none') return { status: 'pass' };
+    if (style.boxShadow && style.boxShadow !== 'none') return { status: 'pass' };
+    const ownBackground = parseColor(style.backgroundColor);
+    if (ownBackground && ownBackground.a > 0) return { status: 'pass' };
+    if (style.backgroundImage !== 'none') return { status: 'pass' }; // gradient/image underline technique
+
+    // A clear weight difference is a non-colour distinction too.
+    const parentStyle = getComputedStyle(parent);
+    const weight = (s) => parseInt(s.fontWeight, 10) || 400;
+    if (Math.abs(weight(style) - weight(parentStyle)) >= 300) return { status: 'pass' };
+
+    const linkColor = parseColor(style.color);
+    const textColor = parseColor(parentStyle.color);
+    if (!linkColor || !textColor) return { status: 'pass' };
+
+    const ratio = contrastRatio(linkColor, textColor);
+    // WCAG technique G183: 3:1 against the surrounding text is a sufficient
+    // colour difference for identifying a link.
+    if (ratio >= 3) return { status: 'pass' };
+
+    // LAST, because it's the expensive check (tree walk + line geometry)
+    // and only failing candidates should ever pay for it: a link occupying
+    // its own line (<br>-separated address blocks, one-link-per-line
+    // footers) has no surrounding words to blend into — nothing is
+    // conveyed by colour.
+    const rect = element.getBoundingClientRect();
+    if (rect.height) {
+      const mid = rect.top + rect.height / 2;
+      const walker = element.ownerDocument.createTreeWalker(parent, NodeFilter.SHOW_TEXT);
+      const range = element.ownerDocument.createRange();
+      let sharesLine = false;
+      for (let node = walker.nextNode(); node && !sharesLine; node = walker.nextNode()) {
+        if (!node.textContent.trim() || element.contains(node)) continue;
+        range.selectNodeContents(node);
+        for (const r of range.getClientRects()) {
+          if (r.top <= mid && r.bottom >= mid && r.width > 0) { sharesLine = true; break; }
+        }
+      }
+      if (!sharesLine) return { status: 'pass' };
+    }
+    return {
+      status: 'fail',
+      message: ratio < 1.01
+        ? 'This link has no underline and the same colour as the surrounding text — sighted users can’t tell it’s a link.'
+        : `This link has no underline and only ${ratio.toFixed(2)}:1 colour difference from the surrounding text — colour-blind users can’t spot it.`,
+      fix: 'Underline links inside text (text-decoration: underline), or add a non-colour indicator.',
+    };
+  },
+};

package/engine/rules/wcag/1.4.10-reflow.js

@@ -0,0 +1,25 @@
+// WCAG SC 1.4.10 Reflow (Level AA)
+// The full test renders at 320 CSS px; an audit runs at whatever viewport
+// the page is in. What IS knowable here: content that already forces
+// two-dimensional scrolling at the current width will only be worse at
+// 320px. Abstain-over-assert: this flags, it never fails — tables, maps,
+// and images are exempt content the geometry can't distinguish.
+export default {
+  id: 'reflow',
+  impact: 'moderate',
+  tags: ['wcag21aa', 'wcag1410'],
+  help: 'Content should reflow to one-dimensional scrolling',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/reflow.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    const doc = element.ownerDocument;
+    const scroller = doc.scrollingElement ?? doc.documentElement;
+    const overflow = scroller.scrollWidth - scroller.clientWidth;
+    if (overflow <= 1) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: `The page already scrolls horizontally by ${Math.round(overflow)}px at the current viewport — at the 320px reflow breakpoint it will be worse. Verify content reflows at 320 CSS px width (data tables, maps and images are exempt).`,
+    };
+  },
+};