ultra11y 2.22.0

package/src/rules/headings.ts

@@ -0,0 +1,227 @@
+// Theme 9 — Information structure (headings).
+import type { Doc, El, HNode } from "../parse/html.js";
+import { attr, elementsByTag } from "../parse/html.js";
+import { isIntrinsic } from "../parse/jsx-bridge.js";
+import { accessibleName, mayInjectContent } from "../name.js";
+import { type Rule, type RuleFinding, shellBodyInjected } from "./rule.js";
+import { ancestors } from "../parse/html.js";
+
+// JSX/SFC only: true when a required element/content may be injected at runtime in a
+// way static source analysis cannot see — a child component (non-intrinsic tag, which
+// can render anything), a <slot>, or a {…}/{@render} expression child. Rules that
+// assert "the page is missing X" must bail on these so a residual risk is never turned
+// into a false non-conformity (e.g. a Next.js layout supplies its <h1> via {children}).
+function contentMaybeInjected(doc: Doc): boolean {
+  if (doc.kind === "html") return false; // plain HTML has no slots/components/expressions
+  for (const el of doc.elements) {
+    if (el.tag === "slot") return true;
+    if (el.tag !== "#fragment" && !isIntrinsic(el.tag)) return true;
+  }
+  const stack: HNode[] = [...doc.roots];
+  while (stack.length) {
+    const n = stack.pop()!;
+    if (n.type === "text") {
+      if (n.data.includes("{")) return true; // {children}/{expr} — injected markup
+    } else stack.push(...n.children);
+  }
+  return false;
+}
+
+function headingLevel(el: El): number | null {
+  const m = /^h([1-6])$/.exec(el.tag);
+  if (m) return Number(m[1]);
+  if ((attr(el, "role") ?? "") === "heading") {
+    const lvl = Number(attr(el, "aria-level"));
+    if (Number.isInteger(lvl) && lvl >= 1) return lvl;
+  }
+  return null;
+}
+
+function headings(doc: Doc): { el: El; level: number }[] {
+  const out: { el: El; level: number }[] = [];
+  for (const el of doc.elements) {
+    const lvl = headingLevel(el);
+    if (lvl !== null) out.push({ el, level: lvl });
+  }
+  return out;
+}
+
+const headingOrderSkip: Rule = {
+  id: "heading-order-skip",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    let prev = 0;
+    let prevArm: string | undefined;
+    let prevHeading: El | null = null;
+    let componentBetween = false;
+    // Walk elements in source order so interleaved child components are visible: a
+    // component rendered BETWEEN two headings may itself render an intermediate heading
+    // (invisible to source) — so a "skip" across it is not a definite order violation.
+    for (const el of doc.elements) {
+      const level = headingLevel(el);
+      if (level === null) {
+        if (el.tag !== "#fragment" && !isIntrinsic(el.tag) && (!prevHeading || !ancestors(el).includes(prevHeading))) componentBetween = true;
+        continue;
+      }
+      // Compare only headings in the SAME branch context (different JSX conditional arms
+      // are mutually exclusive) with no component injected between them.
+      if (prev !== 0 && el.branchArm === prevArm && !componentBetween && level - prev > 1) {
+        out.push({
+          criteriaId: "1.3.1",
+          el,
+          msgId: "heading-order-skip",
+          params: { level, prev, expected: prev + 1 },
+        });
+      }
+      prev = level;
+      prevArm = el.branchArm;
+      prevHeading = el;
+      componentBetween = false;
+    }
+    return out;
+  },
+};
+
+// h1-missing / h1-multiple are ADVISORY (non-normative): neither "start at h1" nor "a
+// single h1 per page" is a requirement in HTML, accessibility, or SEO. A human RGAA
+// auditor rejected them as non-conformities — no normative test backs them. Heading
+// HIERARCHY stays covered by `heading-order-skip` (normative: RGAA 9.1.3 makes a level
+// skip testable). These fire as « Recommandation (non normative) », never an NC.
+const h1Missing: Rule = {
+  id: "h1-missing",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  scope: "page",
+  advisory: true,
+  run(doc: Doc): RuleFinding[] {
+    const hasH1 = headings(doc).some((h) => h.level === 1);
+    if (hasH1) return [];
+    // The h1 may be supplied by {children}/a child component (JSX/SFC) or injected into
+    // a framework shell template (SPA mount point / `%sveltekit.body%`) at build/runtime.
+    if (contentMaybeInjected(doc) || shellBodyInjected(doc)) return [];
+    const anchor = elementsByTag(doc, "body")[0] ?? elementsByTag(doc, "html")[0];
+    if (!anchor) return [];
+    return [
+      {
+        criteriaId: "1.3.1",
+        el: anchor,
+        msgId: "h1-missing",
+      },
+    ];
+  },
+};
+
+const h1Multiple: Rule = {
+  id: "h1-multiple",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  scope: "page",
+  advisory: true,
+  run(doc: Doc): RuleFinding[] {
+    const h1s = elementsByTag(doc, "h1");
+    if (h1s.length <= 1) return [];
+    return h1s.slice(1).map((el) => ({
+      criteriaId: "1.3.1",
+      el,
+      msgId: "h1-multiple",
+      params: { count: h1s.length },
+    }));
+  },
+};
+
+// <slot> is allowed: it projects slotted <li>s (web components / SFC templates).
+const ALLOWED_IN_LIST = new Set(["li", "script", "template", "slot"]);
+
+const listStructure: Rule = {
+  id: "list-structure",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag === "ul" || el.tag === "ol") {
+        // Only intrinsic (HTML) children are a definite violation; a PascalCase
+        // component child may itself render an <li>, so it is left to the cross-file
+        // graph / human, never asserted here.
+        const bad = el.children.find((c) => c.type === "element" && isIntrinsic(c.tag) && !ALLOWED_IN_LIST.has(c.tag));
+        if (bad && bad.type === "element") {
+          out.push({
+            criteriaId: "1.3.1",
+            el: bad,
+            msgId: "list-structure.invalid-child",
+            params: { childTag: bad.tag, parentTag: el.tag },
+          });
+        }
+      } else if (el.tag === "li") {
+        const parent = el.parent;
+        if (!parent || ["ul", "ol", "menu"].includes(parent.tag)) continue;
+        // A <li> inside a <template> (named-slot definition) or a component subtree is
+        // projected into a parent component's <ul> at render — its real parent is unknown
+        // to static analysis, so this is not a definite violation.
+        if (parent.tag === "template" || ancestors(el).some((a) => a.tag === "template" || (a.tag !== "#fragment" && !isIntrinsic(a.tag)))) continue;
+        out.push({
+          criteriaId: "1.3.1",
+          el,
+          msgId: "list-structure.li-outside-list",
+          params: { parentTag: parent.tag },
+        });
+      }
+    }
+    return out;
+  },
+};
+
+const emptyHeading: Rule = {
+  id: "empty-heading",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const { el, level } of headings(doc)) {
+      if (attr(el, "aria-hidden") === "true") continue;
+      if (accessibleName(el, doc)) continue;
+      if (mayInjectContent(el)) continue; // text supplied by a <slot>/child component
+      out.push({
+        criteriaId: "1.3.1",
+        el,
+        msgId: "empty-heading",
+        params: { tag: el.tag, level },
+      });
+    }
+    return out;
+  },
+};
+
+// A description list only conveys its term/description pairing when the markup is
+// well-formed: <dl> takes <dt>/<dd> (optionally wrapped in <div>), and <dt>/<dd> mean
+// nothing outside a <dl>. Broken either way, the relationship is purely visual.
+const DL_ALLOWED = new Set(["dt", "dd", "div", "script", "template", "slot", "#fragment"]);
+
+const dlStructure: Rule = {
+  id: "dl-structure",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag === "dl") {
+        if (mayInjectContent(el)) continue; // children projected by a slot/component
+        for (const child of el.children) {
+          if (child.type !== "element" || !isIntrinsic(child.tag)) continue;
+          if (DL_ALLOWED.has(child.tag)) continue;
+          out.push({ criteriaId: "1.3.1", el: child, msgId: "dl-structure.foreign-child", params: { tag: child.tag } });
+        }
+        continue;
+      }
+      if (el.tag !== "dt" && el.tag !== "dd") continue;
+      const chain = ancestors(el);
+      if (chain.some((a) => a.tag === "dl" || !isIntrinsic(a.tag))) continue; // inside a dl, or a component may supply one
+      out.push({ criteriaId: "1.3.1", el, msgId: "dl-structure.orphan", params: { tag: el.tag } });
+    }
+    return out;
+  },
+};
+
+export const headingsRules: Rule[] = [headingOrderSkip, h1Missing, h1Multiple, listStructure, emptyHeading, dlStructure];

package/src/rules/images.ts

@@ -0,0 +1,200 @@
+// Theme 1 — Images.
+import type { Doc, El } from "../parse/html.js";
+import { attr, hasAttr, hasBoundAttr, boundAttr, hasDynamicSpread, visibleText, ancestors, descendants } from "../parse/html.js";
+import { accessibleName, isNameExempt } from "../name.js";
+import type { Rule, RuleFinding } from "./rule.js";
+
+// Not exposed to assistive tech (aria-hidden / [hidden] / an inline display:none or
+// visibility:hidden, on the element or an ancestor), or explicitly presentational —
+// either way there is no accessible name to demand. Shared with the other rule families
+// via src/name.ts so the whole engine agrees on what "not exposed" means.
+const isHidden = isNameExempt;
+// A dynamically-bound name (`:aria-label`, `v-bind:aria-labelledby`) names the element
+// even though we cannot resolve its value — treat it as present, not missing.
+const named = (el: El): boolean => !!(boundAttr(el, "aria-label") ?? "").trim() || hasBoundAttr(el, "aria-labelledby");
+
+const imgAltMissing: Rule = {
+  id: "img-alt-missing",
+  criteria: ["1.1.1"],
+  severity: "bloquant",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      const isImg = el.tag === "img" || el.tag === "area" || (attr(el, "role") ?? "") === "img";
+      if (!isImg) continue;
+      if (isHidden(el) && el.tag !== "area") continue;
+      // alt="" is the decorative opt-out (maps the image to presentation); a whitespace-only
+      // alt is NOT — it provides no accessible name yet keeps the image in the a11y tree.
+      const altLiteral = attr(el, "alt");
+      const whitespaceAlt = altLiteral !== undefined && altLiteral !== "" && altLiteral.trim() === "";
+      if ((hasBoundAttr(el, "alt") && !whitespaceAlt) || named(el)) continue; // alt="" / :alt="x" / aria-* → present
+      if (hasDynamicSpread(el)) continue; // {...props} / Svelte {alt} shorthand may carry alt
+      // role="img" on a non-<img> element (e.g. <svg role="img"><title>…) is named by its
+      // <title>/text content, not an alt attribute — accept that accessible name.
+      if (el.tag !== "img" && el.tag !== "area" && accessibleName(el, doc).trim() !== "") continue;
+      // `title` IS an accname fallback for an image, so 1.1.1 is technically satisfied and
+      // asserting a non-conformity would be inventing one. It is still the wrong tool —
+      // `title` is hover-only, absent on touch and unevenly announced — so this stays a
+      // recommendation to move the text into `alt`, never a normative failure.
+      if ((attr(el, "title") ?? "").trim() !== "") {
+        out.push({
+          criteriaId: "1.1.1",
+          el,
+          msgId: "img-alt-missing.title-only",
+          params: { tag: el.tag },
+          advisory: true,
+          severity: "mineur",
+        });
+        continue;
+      }
+      out.push({
+        criteriaId: "1.1.1",
+        el,
+        msgId: "img-alt-missing",
+        params: { tag: el.tag },
+      });
+    }
+    return out;
+  },
+};
+
+const decorativeAltMisuse: Rule = {
+  id: "decorative-alt-misuse",
+  criteria: ["1.1.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "img") continue;
+      const alt = attr(el, "alt");
+      const role = (attr(el, "role") ?? "").trim();
+      const ariaLabel = (attr(el, "aria-label") ?? "").trim();
+      const title = (attr(el, "title") ?? "").trim();
+      if (alt === "" && (ariaLabel || title)) {
+        out.push({
+          criteriaId: "1.1.1",
+          el,
+          msgId: "decorative-alt-misuse.empty-but-named",
+        });
+      } else if (["presentation", "none"].includes(role) && alt?.trim()) {
+        out.push({
+          criteriaId: "1.1.1",
+          el,
+          msgId: "decorative-alt-misuse.role-but-alt",
+          params: { role },
+        });
+      }
+    }
+    return out;
+  },
+};
+
+const canvasFallbackMissing: Rule = {
+  id: "canvas-fallback-missing",
+  criteria: ["1.1.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "canvas") continue;
+      if (attr(el, "aria-hidden") === "true") continue; // explicitly removed from the a11y tree (named on a role=img wrapper)
+      const hasFallback = el.children.some((c) => (c.type === "element" ? true : c.data.trim().length > 0));
+      if (hasFallback || named(el) || visibleText(el)) continue;
+      out.push({
+        criteriaId: "1.1.1",
+        el,
+        msgId: "canvas-fallback-missing",
+      });
+    }
+    return out;
+  },
+};
+
+const inputImageAltMissing: Rule = {
+  id: "input-image-alt-missing",
+  criteria: ["1.1.1"],
+  severity: "bloquant",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "input" || (attr(el, "type") ?? "").toLowerCase() !== "image") continue;
+      if (isHidden(el)) continue;
+      const alt = (boundAttr(el, "alt") ?? "").trim();
+      if (alt || named(el) || (attr(el, "title") ?? "").trim()) continue;
+      out.push({
+        criteriaId: "1.1.1",
+        el,
+        msgId: "input-image-alt-missing",
+      });
+    }
+    return out;
+  },
+};
+
+// <object>/<embed> embed non-text content (PDF, Flash-era media, SVG, video) and need an
+// accessible name or text fallback, like <img>. (Decorative ones should be aria-hidden.)
+const objectEmbedNoName: Rule = {
+  id: "object-embed-no-name",
+  criteria: ["1.1.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "object" && el.tag !== "embed") continue;
+      if (isHidden(el)) continue;
+      if (hasDynamicSpread(el)) continue; // a spread may inject aria-label/title
+      // named(el) catches a dynamically-bound aria-label / :aria-labelledby / aria-labelledby={x}
+      // (present name, value unknown) the same way chart-no-accessible-name does — without it,
+      // a bound aria-labelledby re-fired as a false "no name" finding on <object>/<embed>.
+      if (named(el) || accessibleName(el, doc).trim() !== "") continue; // aria-label/labelledby, title, or fallback content
+      out.push({
+        criteriaId: "1.1.1",
+        el,
+        msgId: "object-embed-no-name",
+        params: { tag: el.tag },
+      });
+    }
+    return out;
+  },
+};
+
+// A charting container (<svg>/<div> of a known charting library) with no accessible
+// name — the data visualization carries information with no text alternative
+// (WCAG 1.1.1). Distinct from canvas-fallback-missing (which owns <canvas>): charting
+// libs (recharts/echarts/chart.js/…) render into <svg>/<div>. Only the OUTERMOST chart
+// container is reported (inner chart nodes are skipped), and a class allowlist bounds FP.
+// Right boundary (`([-_ ]|$)`) so a generic token matches a WHOLE class token only — else
+// `graph` prefix-matches `graphics`/`typography-graphic` (decorative), a false positive.
+const CHART_CLASS = /(^|[-_ ])(charts?|graphs?|recharts|highcharts|chart-?js|plotly|nivo|apexcharts|echarts|d3)([-_ ]|$)/i;
+
+const chartNoAccessibleName: Rule = {
+  id: "chart-no-accessible-name",
+  criteria: ["1.1.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "svg" && el.tag !== "div") continue;
+      const cls = attr(el, "class") ?? "";
+      if (!CHART_CLASS.test(cls)) continue;
+      if (isHidden(el)) continue;
+      if (hasDynamicSpread(el)) continue;
+      // report only the outermost chart container (skip nested chart nodes)
+      if (ancestors(el).some((a) => CHART_CLASS.test(attr(a, "class") ?? ""))) continue;
+      if (named(el) || accessibleName(el, doc).trim() !== "") continue; // aria-label/labelledby, <svg><title>, text
+      // named by a wrapping <figure><figcaption> or a role=img wrapper
+      const fig = ancestors(el).find((a) => a.tag === "figure");
+      if (fig && descendants(fig).some((d) => d.tag === "figcaption" && visibleText(d))) continue;
+      if (ancestors(el).some((a) => (attr(a, "role") ?? "") === "img" && (named(a) || (attr(a, "aria-label") ?? "").trim()))) continue;
+      out.push({
+        criteriaId: "1.1.1",
+        el,
+        msgId: "chart-no-accessible-name",
+        params: { tag: el.tag, cls: cls.trim().split(/\s+/)[0] ?? "" },
+      });
+    }
+    return out;
+  },
+};
+
+export const imagesRules: Rule[] = [imgAltMissing, decorativeAltMisuse, canvasFallbackMissing, inputImageAltMissing, objectEmbedNoName, chartNoAccessibleName];

package/src/rules/links.ts

@@ -0,0 +1,193 @@
+// Theme 6 / 7 — Links & buttons: accessible-name presence (empty-name + icon-only).
+import type { Doc, El } from "../parse/html.js";
+import { attr, hasAttr, descendants, visibleText } from "../parse/html.js";
+import { isIntrinsic } from "../parse/jsx-bridge.js";
+import { accessibleName, mayInjectContent, isFormField, controlLabel, isNameExempt } from "../name.js";
+import type { Rule, RuleFinding } from "./rule.js";
+
+function hasIconChild(el: El): boolean {
+  return descendants(el).some((d) => {
+    if (d.tag === "img") {
+      const a = attr(d, "alt");
+      return a === undefined || a.trim() === "";
+    }
+    if (d.tag === "svg") {
+      const titled = descendants(d).some((x) => x.tag === "title" && visibleText(x));
+      return !titled && !(attr(d, "aria-label") ?? "").trim();
+    }
+    if (d.tag === "i") return /(^|\s|-)(icon|fa|glyphicon|material-icons)/.test((attr(d, "class") ?? "").toLowerCase());
+    return false;
+  });
+}
+
+const isButton = (el: El): boolean => {
+  if (el.tag === "button") return true;
+  if ((attr(el, "role") ?? "") === "button") return true;
+  if (el.tag === "input") return (attr(el, "type") ?? "").toLowerCase() === "button";
+  return false;
+};
+
+const linkEmptyName: Rule = {
+  id: "link-empty-name",
+  criteria: ["2.4.4"],
+  severity: "bloquant",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "a" || !hasAttr(el, "href")) continue;
+      if (isNameExempt(el)) continue; // not exposed, or explicitly presentational
+      if (accessibleName(el, doc) !== "") continue;
+      if (mayInjectContent(el)) continue; // name supplied by a <slot>/child component
+      if (hasIconChild(el)) continue; // handled by icon-only-control-unnamed
+      out.push({
+        criteriaId: "2.4.4",
+        el,
+        msgId: "link-empty-name",
+      });
+    }
+    return out;
+  },
+};
+
+const buttonEmptyName: Rule = {
+  id: "button-empty-name",
+  criteria: ["4.1.2"],
+  severity: "bloquant",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (!isButton(el)) continue;
+      if (isNameExempt(el)) continue; // not exposed, or explicitly presentational
+      if (accessibleName(el, doc) !== "") continue;
+      if (mayInjectContent(el)) continue; // name supplied by a <slot>/child component
+      if (hasIconChild(el)) continue; // handled by icon-only-control-unnamed
+      out.push({
+        criteriaId: "4.1.2",
+        el,
+        msgId: "button-empty-name",
+      });
+    }
+    return out;
+  },
+};
+
+const iconOnlyControlUnnamed: Rule = {
+  id: "icon-only-control-unnamed",
+  criteria: ["2.4.4", "4.1.2"],
+  severity: "bloquant",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      const link = el.tag === "a" && hasAttr(el, "href");
+      const button = isButton(el);
+      if (!link && !button) continue;
+      if (isNameExempt(el)) continue; // not exposed, or explicitly presentational
+      if (accessibleName(el, doc) !== "") continue;
+      if (mayInjectContent(el)) continue; // name supplied by a <slot>/child component
+      if (!hasIconChild(el)) continue;
+      out.push({
+        criteriaId: link ? "2.4.4" : "4.1.2",
+        el,
+        msgId: "icon-only-control-unnamed",
+        params: { kind: link ? "link" : "button" },
+      });
+    }
+    return out;
+  },
+};
+
+// A link/button whose ONLY accessible name comes from the title attribute. `title` is
+// restituted unreliably (hover only — not on touch, often not by keyboard/AT), so a control
+// named solely by it is effectively unlabeled in practice. (link-empty-name/button-empty-name
+// skip these because title technically yields a name, so this rule covers the gap.)
+const controlNameTitleOnly: Rule = {
+  id: "control-name-title-only",
+  criteria: ["4.1.2"],
+  severity: "mineur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      const link = el.tag === "a" && hasAttr(el, "href");
+      const field = !link && !isButton(el) && isFormField(el);
+      if (!link && !isButton(el) && !field) continue;
+      if (isNameExempt(el)) continue; // not exposed, or explicitly presentational
+      const title = (attr(el, "title") ?? "").trim();
+      if (!title || title.includes("{")) continue; // no title, or dynamic value
+      if (hasAttr(el, "aria-label") || hasAttr(el, "aria-labelledby")) continue; // named by ARIA, title is supplementary
+      if (mayInjectContent(el)) continue; // name may come from a <slot>/child component
+      if (el.tag === "input" && (attr(el, "value") ?? "").trim()) continue; // value names the button
+      // A form field is title-only precisely when its resolved label comes from title (a
+      // for=/wrapping/aria label wins over title in controlLabel, so via!=="title" means it
+      // is otherwise named or unlabeled — control-label-missing's job, not this rule's).
+      if (field && controlLabel(el, doc).via !== "title") continue;
+      const hasContentName =
+        visibleText(el).trim() !== "" ||
+        descendants(el).some(
+          (d) =>
+            (d.tag === "img" && (attr(d, "alt") ?? "").trim() !== "") ||
+            (d.tag === "svg" && descendants(d).some((x) => x.tag === "title" && visibleText(x).trim() !== "")),
+        );
+      if (!field && hasContentName) continue; // visible text / named image already provides the name (fields have no content name)
+      out.push({
+        criteriaId: "4.1.2",
+        el,
+        msgId: "control-name-title-only",
+        params: { kind: link ? "link" : field ? "field" : "button" },
+      });
+    }
+    return out;
+  },
+};
+
+/** Normalise for the label-in-name comparison: case, punctuation and whitespace are not
+ *  what voice control matches on. */
+const normalizeName = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[\u2018\u2019\u201c\u201d]/g, "'")
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim();
+
+// WCAG 2.5.3 Label in Name: when a control shows a visible text label, that text must be
+// CONTAINED in its accessible name. A voice-control user says what they see ("click Send");
+// if the accessible name is "Submit", the command silently does nothing. Only reported when
+// both halves are literal text — a dynamic name proves nothing either way.
+const labelInNameMismatch: Rule = {
+  id: "label-in-name-mismatch",
+  criteria: ["2.5.3"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (!isIntrinsic(el.tag)) continue;
+      const link = el.tag === "a" && hasAttr(el, "href");
+      const role = (attr(el, "role") ?? "").trim().toLowerCase();
+      if (!link && !isButton(el) && !["button", "link", "menuitem", "tab", "checkbox", "radio", "switch"].includes(role)) continue;
+      if (isNameExempt(el)) continue;
+      // The override must be a LITERAL aria-label: aria-labelledby points at text elsewhere
+      // in the page, which the visible label may legitimately extend rather than contradict.
+      const ariaLabel = (attr(el, "aria-label") ?? "").trim();
+      if (!ariaLabel || ariaLabel.includes("{")) continue;
+      if (hasAttr(el, "aria-labelledby")) continue; // labelledby wins over aria-label; different question
+      const visible = visibleText(el).trim();
+      if (!visible || visible.includes("{")) continue;
+      // A one- or two-character run ("X", "OK", "→") is a glyph, not a label a voice-control
+      // user would speak — 2.5.3 is about VISIBLE LABEL TEXT, and comparing glyphs to names
+      // manufactures noise.
+      if (visible.length < 3) continue;
+      if (mayInjectContent(el)) continue; // the visible text may come from a slot/component
+      const name = normalizeName(ariaLabel);
+      const label = normalizeName(visible);
+      if (!label || !name || name.includes(label)) continue;
+      out.push({
+        criteriaId: "2.5.3",
+        el,
+        msgId: "label-in-name-mismatch",
+        params: { visible, name: ariaLabel },
+      });
+    }
+    return out;
+  },
+};
+
+export const linksRules: Rule[] = [linkEmptyName, buttonEmptyName, iconOnlyControlUnnamed, controlNameTitleOnly, labelInNameMismatch];