automatica11y 0.3.2 → 0.4.0

package/src/tiers/conditions/checks.js

@@ -0,0 +1,283 @@
+/**
+ * The conditions checks. Each opens the page under a setting a person might use (reduced motion, dark mode, forced colors),
+ * or in an environment (a 320 pixel window, wider text spacing), and says whether the page holds up.
+ * A check returns pass, fail, undetermined, or not-applicable, with a detail and the numbers behind it.
+ * These are automatica11y's own measurements. They're reported on their own and never added to axe-core or IBM counts.
+ */
+import { contrastOver, formatRatio, ringIsEnough, textThreshold } from "../computed/color.js";
+import { num, plural } from "../../text.js";
+import { criterionRef } from "../../wcag/index.js";
+
+const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
+const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
+const na = (detail) => ({ result: "not-applicable", detail });
+const undetermined = (detail, extra = {}) => ({ result: "undetermined", detail, ...extra });
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+const floor2 = (n) => Math.floor(n * 100) / 100;
+const list = (items, max = 3) => `${items.slice(0, max).join("; ")}${items.length > max ? `; and ${items.length - max} more` : ""}`;
+
+/** Archetypes whose trigger shouldn't be pressed to reach their resting state: a link would navigate, and a chart has nothing to press. */
+const NO_ACTIVATION = new Set(["link", "chart"]);
+
+/** Does this page have a trigger hook (a fixture), or is it a whole page? */
+const hasTrigger = async (ctx) => (await ctx.trigger.count()) > 0;
+
+/** Press Enter on the trigger of a fixture, so a dialog, menu, or message is showing. Whole pages are left as they are. */
+async function reachState(ctx, archetype) {
+  if (!(await hasTrigger(ctx)) || NO_ACTIVATION.has(archetype)) return false;
+  await ctx.focus();
+  await ctx.press("Enter");
+  await ctx.settle(300);
+  return true;
+}
+
+// ---- reduced motion ----
+
+/** Every animation seen at load and just after the trigger is pressed. Each is recorded once. */
+async function collectAnimations(ctx, archetype) {
+  const seen = new Map();
+  const take = async () => {
+    for (const a of await ctx.page.evaluate(() => window.__a11yConditions.animations())) seen.set(`${a.kind}|${a.name}|${a.target}|${a.props.join()}|${a.duration}|${a.iterations}`, a);
+  };
+  await ctx.settle(100);
+  await take();
+  await sleep(150);
+  await take();
+  if ((await hasTrigger(ctx)) && !NO_ACTIVATION.has(archetype)) {
+    await ctx.focus();
+    await ctx.page.keyboard.press("Enter");
+    for (const wait of [0, 40, 80, 160, 240]) {
+      await take();
+      await sleep(wait);
+    }
+  }
+  return [...seen.values()];
+}
+
+/** An animation worth reducing: anything that repeats forever, or moves for longer than a blink. */
+const concerning = (a) => a.iterations === "infinite" || (a.moving && (a.duration ?? 0) > 100);
+const describeAnimation = (a) => `${a.name || a.kind} on ${a.target} (${a.moving ? `moves ${a.props.filter((p) => /^(transform|translate|rotate|scale|top|left|right|bottom|inset|margin|height|width|offset|background|clip|max|min)/.test(p)).join(", ")}` : a.props.join(", ") || "no keyframes"}; ${a.duration ?? "?"}ms${a.iterations === "infinite" ? ", repeats forever" : ""})`;
+
+const reducedMotion = (archetype) => ({
+  name: "reduced-motion-respected",
+  criteria: ["2.3.3", "2.2.2"],
+  async run(ctx) {
+    const normal = await collectAnimations(ctx, archetype);
+    const reduced = await collectAnimations(await ctx.variant({ reducedMotion: true }), archetype);
+    const measurements = [{ setting: "no preference", animations: normal.length, moveOrRepeat: normal.filter(concerning).length }, { setting: "reduce", animations: reduced.length, moveOrRepeat: reduced.filter(concerning).length }];
+    if (normal.length === 0 && reduced.length === 0) return na("No animations or transitions were running at load or after the trigger was pressed, so there's nothing to reduce. Motion driven by JavaScript timers isn't visible to this check.");
+    const still = reduced.filter(concerning);
+    if (still.length) {
+      const before = normal.filter(concerning).length;
+      return fail(`With prefers-reduced-motion: reduce, ${plural(still.length, "animation")} still ${still.length === 1 ? "moves or repeats" : "move or repeat"}: ${list(still.map(describeAnimation))}. Without the preference, ${num(before)} did.`, { measurements });
+    }
+    const had = normal.filter(concerning);
+    return had.length
+      ? pass(`${plural(had.length, "animation")} that move or repeat (${list(had.map(describeAnimation), 2)}) don't run when motion is reduced.`, { measurements })
+      : pass(`The page animates (${plural(normal.length, "animation")}), but nothing moves or repeats, so there's no motion to reduce. Motion driven by JavaScript timers isn't visible to this check.`, { measurements });
+  },
+});
+
+// ---- color scheme ----
+
+const colorScheme = () => ({
+  name: "dark-mode-contrast",
+  criteria: ["1.4.3"],
+  async run(ctx) {
+    await ctx.settle(300);
+    // Animations are frozen in both shots, so a spinner or a fade can't make a page look as if it changed.
+    const light = await ctx.page.screenshot({ animations: "disabled" });
+    const dark = await ctx.variant({ colorScheme: "dark" });
+    await dark.settle(300);
+    const shot = await dark.page.screenshot({ animations: "disabled" });
+    if (light.equals(shot)) return na("The page looks the same under prefers-color-scheme: dark, so it doesn't adapt to it. A page isn't required to. Nothing was checked.");
+    const parts = (await dark.page.evaluate(() => window.__a11yMeasure.text("all"))) ?? [];
+    if (parts.length === 0) return undetermined("The page changes under prefers-color-scheme: dark, but no visible text was found to measure.");
+    const rows = [];
+    const unknown = [];
+    for (const part of parts) {
+      if (part.undetermined || !part.backdrop) unknown.push(`"${part.text}" can't be measured because ${part.undetermined ?? "its background couldn't be read"}.`);
+      else rows.push({ text: part.text, ratio: contrastOver(part.color, part.backdrop), required: textThreshold(part.size, part.weight) });
+    }
+    const failed = rows.filter((r) => r.ratio < r.required).sort((a, b) => a.ratio / a.required - b.ratio / b.required);
+    const measurements = [{ measured: rows.length, undetermined: unknown.length, below: failed.length, lowestRatio: rows.length ? floor2(Math.min(...rows.map((r) => r.ratio))) : null }];
+    if (failed.length) return fail(`In dark mode, ${plural(failed.length, "piece")} of text fall${failed.length === 1 ? "s" : ""} below the contrast it needs. The worst is "${failed[0].text}" at ${formatRatio(failed[0].ratio)} (needs ${failed[0].required}:1).`, { measurements });
+    if (unknown.length) return undetermined(`${rows.length ? `All ${plural(rows.length, "measured piece")} of text pass in dark mode. ` : ""}${plural(unknown.length, "other piece")} can't be reduced to one color. ${unknown[0]}`, { measurements });
+    return pass(`The page adapts to dark mode, and all ${plural(rows.length, "piece")} of text measured pass. The lowest is ${formatRatio(Math.min(...rows.map((r) => r.ratio)))}.`, { measurements });
+  },
+});
+
+// ---- prefers-contrast ----
+
+/** Measure the contrast of every piece of text on a page. */
+async function measureAllText(ctx) {
+  const parts = (await ctx.page.evaluate(() => window.__a11yMeasure.text("all"))) ?? [];
+  const rows = [];
+  const unknown = [];
+  for (const part of parts) {
+    if (part.undetermined || !part.backdrop) unknown.push(`"${part.text}" can't be measured because ${part.undetermined ?? "its background couldn't be read"}.`);
+    else rows.push({ text: part.text, ratio: contrastOver(part.color, part.backdrop), required: textThreshold(part.size, part.weight) });
+  }
+  return { rows, unknown };
+}
+
+/** The piece of text with the least room above its threshold, and how many fall below it. */
+function tightest(rows) {
+  const sorted = [...rows].sort((a, b) => a.ratio / a.required - b.ratio / b.required);
+  return { worst: sorted[0], below: sorted.filter((r) => r.ratio < r.required) };
+}
+
+/** Screenshots with animations frozen, so a running spinner can't make a page look different. */
+async function lookOf(ctx) {
+  await ctx.settle(300);
+  return ctx.page.screenshot({ animations: "disabled" });
+}
+
+const moreContrast = () => ({
+  name: "more-contrast-respected",
+  criteria: ["1.4.3", "1.4.6"],
+  async run(ctx) {
+    const normal = await lookOf(ctx);
+    const more = await ctx.variant({ contrast: "more" });
+    if (normal.equals(await lookOf(more))) return na("The page looks the same under prefers-contrast: more, so it doesn't respond to it. A page isn't required to. Nothing was checked.");
+    const base = await measureAllText(ctx);
+    const now = await measureAllText(more);
+    if (now.rows.length === 0) return undetermined("The page changes under prefers-contrast: more, but no visible text was measurable.");
+    const { worst, below } = tightest(now.rows);
+    const lowestNow = Math.min(...now.rows.map((r) => r.ratio));
+    const lowestBase = base.rows.length ? Math.min(...base.rows.map((r) => r.ratio)) : null;
+    const enhanced = now.rows.every((r) => r.ratio >= (r.required === 3 ? 4.5 : 7));
+    const measurements = [{ lowestWithoutPreference: lowestBase === null ? null : floor2(lowestBase), lowestWithMore: floor2(lowestNow), belowMinimum: below.length, reachesEnhanced: enhanced }];
+    if (below.length) return fail(`With prefers-contrast: more, ${plural(below.length, "piece")} of text fall${below.length === 1 ? "s" : ""} below the minimum contrast. The worst is "${worst.text}" at ${formatRatio(worst.ratio)} (needs ${worst.required}:1).`, { measurements });
+    if (lowestBase !== null && lowestNow < lowestBase - 0.01) return fail(`With prefers-contrast: more, the lowest text contrast dropped from ${formatRatio(lowestBase)} to ${formatRatio(lowestNow)}, so the page asked for more contrast and got less.`, { measurements });
+    if (now.unknown.length) return undetermined(`All ${plural(now.rows.length, "measured piece")} of text pass with more contrast. ${plural(now.unknown.length, "other piece")} can't be reduced to one color. ${now.unknown[0]}`, { measurements });
+    return pass(`The page responds to prefers-contrast: more. The lowest text contrast is ${formatRatio(lowestNow)}${lowestBase === null ? "" : `, from ${formatRatio(lowestBase)} without the preference`}. Enhanced contrast (${criterionRef("1.4.6")}, 7:1 for normal text) is ${enhanced ? "reached" : "not reached for every piece of text"}.`, { measurements });
+  },
+});
+
+const lessContrast = () => ({
+  name: "less-contrast-stays-readable",
+  criteria: ["1.4.3"],
+  async run(ctx) {
+    const normal = await lookOf(ctx);
+    const less = await ctx.variant({ contrast: "less" });
+    if (normal.equals(await lookOf(less))) return na("The page looks the same under prefers-contrast: less, so it doesn't respond to it. A page isn't required to. Nothing was checked.");
+    const now = await measureAllText(less);
+    if (now.rows.length === 0) return undetermined("The page changes under prefers-contrast: less, but no visible text was measurable.");
+    const { worst, below } = tightest(now.rows);
+    const measurements = [{ measured: now.rows.length, belowMinimum: below.length, lowest: floor2(Math.min(...now.rows.map((r) => r.ratio))) }];
+    if (below.length) return fail(`With prefers-contrast: less, ${plural(below.length, "piece")} of text fall${below.length === 1 ? "s" : ""} below the minimum contrast. The worst is "${worst.text}" at ${formatRatio(worst.ratio)} (needs ${worst.required}:1). Softer contrast is fine only while text stays readable.`, { measurements });
+    if (now.unknown.length) return undetermined(`All ${plural(now.rows.length, "measured piece")} of text stay above the minimum. ${plural(now.unknown.length, "other piece")} can't be reduced to one color. ${now.unknown[0]}`, { measurements });
+    return pass(`The page softens its contrast under prefers-contrast: less, and all ${plural(now.rows.length, "piece")} of text measured stay above the minimum. The lowest is ${formatRatio(Math.min(...now.rows.map((r) => r.ratio)))}.`, { measurements });
+  },
+});
+
+// ---- prefers-reduced-transparency ----
+
+const reducedTransparency = () => ({
+  name: "reduced-transparency-respected",
+  // The preference isn't a success criterion. See-through backgrounds make text contrast unpredictable, which 1.4.3 and 1.4.11 care about.
+  criteria: ["1.4.3", "1.4.11"],
+  async run(ctx) {
+    await ctx.settle(300);
+    const normal = await ctx.page.evaluate(() => window.__a11yConditions.translucentSurfaces());
+    const reduced = await ctx.variant({ reducedTransparency: true });
+    await reduced.settle(300);
+    const still = await reduced.page.evaluate(() => window.__a11yConditions.translucentSurfaces());
+    const measurements = [{ translucentWithoutPreference: normal.length, translucentWithReduce: still.length }];
+    if (normal.length === 0 && still.length === 0) return na("No surface that holds text is see-through (no translucent background and no backdrop filter), so there's nothing to reduce. Empty overlays aren't counted.");
+    const name = (s) => `${s.element} (${[s.background, s.backdropFilter && `backdrop-filter ${s.backdropFilter}`].filter(Boolean).join(", ")})`;
+    if (still.length) return fail(`With prefers-reduced-transparency: reduce, ${plural(still.length, "surface")} holding text stay${still.length === 1 ? "s" : ""} see-through: ${list(still.map(name))}. Without the preference there were ${num(normal.length)}. This preference isn't a WCAG requirement. It matters because see-through backgrounds make text contrast unpredictable.`, { measurements });
+    return pass(`${plural(normal.length, "see-through surface")} holding text (${list(normal.map(name), 2)}) become opaque when transparency is reduced.`, { measurements });
+  },
+});
+
+// ---- forced colors ----
+
+const forcedColors = (archetype) => ({
+  name: "forced-colors-focus-visible",
+  criteria: ["1.4.11", "2.4.7"],
+  async run(ctx) {
+    const forced = await ctx.variant({ forcedColors: true });
+    await forced.settle(300);
+    let focused;
+    if (await hasTrigger(forced)) {
+      if ((await forced.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so its focus indicator wasn't checked.");
+    } else {
+      await forced.page.keyboard.press("Tab");
+      await forced.settle(100);
+    }
+    focused = await forced.page.evaluate(() => window.__a11yMeasure.focusStyles(false));
+    if (!focused || (focused.box.width === 0 && focused.box.height === 0) || (await forced.page.evaluate(() => document.activeElement === document.body))) return na("Nothing on the page takes keyboard focus, so there's no focus indicator to check.");
+    await forced.settle(400);
+    const clip = forced.clipAround(focused.box, 12);
+    const shotFocused = await forced.page.screenshot({ clip, animations: "disabled" });
+    await forced.page.evaluate(() => /** @type {HTMLElement} */ (document.activeElement)?.blur?.());
+    await forced.page.mouse.move(0, 0);
+    await forced.settle(300);
+    const shotBlurred = await forced.page.screenshot({ clip, animations: "disabled" });
+    const url = (buffer) => `data:image/png;base64,${buffer.toString("base64")}`;
+    const px = await forced.page.evaluate(([a, b]) => window.__a11yMeasure.compareShots(a, b), [url(shotBlurred), url(shotFocused)]);
+    const optOuts = await forced.page.evaluate(() => window.__a11yConditions.forcedColorOptOuts());
+    const note = optOuts.length ? ` ${plural(optOuts.length, "element")} opt${optOuts.length === 1 ? "s" : ""} out of forced colors with forced-color-adjust: none (${list(optOuts, 3)}), so a person should check them.` : "";
+    const perimeter = 2 * (focused.box.width + focused.box.height);
+    const measurements = [{ changedPixels: px.changed, pixelsAtLeast3to1: px.strong, perimeterPixels: Math.round(perimeter), forcedColorOptOuts: optOuts.length }];
+    if (px.changed === 0) return fail(`With forced colors on, nothing visible changed when the control took focus. A focus ring drawn with box-shadow or a background color disappears in forced colors. Use an outline.${note}`, { measurements, method: "pixels" });
+    return ringIsEnough(px.strong, perimeter)
+      ? pass(`With forced colors on, the focus indicator is visible: ${num(px.strong)} of ${num(px.changed)} changed pixels reach 3:1 against their unfocused color.${note}`, { measurements, method: "pixels" })
+      : fail(`With forced colors on, the focus indicator is weak: only ${num(px.strong)} of ${num(px.changed)} changed pixels reach 3:1 against their unfocused color, and enough to count is about half the control's perimeter, ${Math.round(perimeter / 2)}.${note}`, { measurements, method: "pixels" });
+  },
+});
+
+// ---- reflow ----
+
+const reflow = (archetype) => ({
+  name: "reflow-at-320px",
+  criteria: ["1.4.10"],
+  async run(ctx) {
+    const narrow = await ctx.variant({ viewport: { width: 320, height: 256 } });
+    await narrow.settle(300);
+    await reachState(narrow, archetype);
+    const o = await narrow.page.evaluate(() => window.__a11yConditions.overflow("[data-a11y-root]"));
+    const measurements = [{ viewportWidth: o.viewportWidth, scrollWidth: o.scrollWidth, overflowingElements: o.offenderCount }];
+    const problems = [];
+    if (o.scrollWidth > o.viewportWidth + 1) problems.push(`the page scrolls sideways (it is ${o.scrollWidth}px wide in a ${o.viewportWidth}px window)`);
+    if (o.offenders.length) problems.push(`${plural(o.offenderCount, "element")} reach${o.offenderCount === 1 ? "es" : ""} past the right edge: ${list(o.offenders.map((e) => `${e.element} ends at ${e.right}px`))}`);
+    if (o.root && (o.root.right > o.viewportWidth + 1 || o.root.left < -1)) problems.push(`${o.root.element} spans ${o.root.left}px to ${o.root.right}px`);
+    if (problems.length) return fail(`In a 320px window, ${problems.join(", and ")}. ${criterionRef("1.4.10")} exempts two-dimensional content such as data tables and maps, so a person should judge whether that applies.`, { measurements });
+    return pass(`In a 320px window, nothing reaches past the right edge and the page doesn't scroll sideways${o.root ? `. The ${o.root.element} fits (${o.root.left}px to ${o.root.right}px)` : ""}.`, { measurements });
+  },
+});
+
+// ---- text spacing ----
+
+const textSpacing = (archetype) => ({
+  name: "text-spacing-no-clipping",
+  criteria: ["1.4.12"],
+  async run(ctx) {
+    await ctx.settle(200);
+    await reachState(ctx, archetype);
+    const before = await ctx.page.evaluate(() => window.__a11yConditions.clipping());
+    await ctx.page.evaluate(() => window.__a11yConditions.applySpacing());
+    await ctx.settle(200);
+    const after = await ctx.page.evaluate(() => window.__a11yConditions.clipping());
+    if (before.length !== after.length) return undetermined("The page's elements changed while the spacing was applied, so the before and after can't be compared.");
+    const clipped = (e) => (e.hidesX && e.overX > 1) || (e.hidesY && e.overY > 1);
+    const cut = [];
+    after.forEach((now, index) => {
+      const was = before[index];
+      if (clipped(now) && now.text && !now.visuallyHidden && (!clipped(was) || now.overX - was.overX > 1 || now.overY - was.overY > 1)) cut.push(`${now.element} ("${now.text}")`);
+    });
+    const measurements = [{ elementsChecked: after.length, clipped: cut.length }];
+    const settings = "line height 1.5, letter spacing 0.12em, word spacing 0.16em, and paragraph spacing 2em";
+    return cut.length
+      ? fail(`With ${settings}, text in ${plural(cut.length, "element")} gets cut off: ${list(cut)}. Overlapping text isn't checked.`, { measurements })
+      : pass(`With ${settings}, no element cut off its text (${num(after.length)} elements checked). Overlapping text isn't checked.`, { measurements });
+  },
+});
+
+/** The conditions checks for an archetype. Whole pages use the name "page". */
+export function conditionChecksFor(archetype) {
+  return [reducedMotion(archetype), colorScheme(), moreContrast(), lessContrast(), reducedTransparency(), forcedColors(archetype), reflow(archetype), textSpacing(archetype)];
+}

package/src/tiers/conditions/index.js

@@ -0,0 +1,30 @@
+import { installMeasure } from "../computed/measure-kit.js";
+import { installHelpers } from "../interactions/helpers.js";
+import { runCheck } from "../interactions/index.js";
+import { conditionChecksFor } from "./checks.js";
+import { installConditions } from "./kit.js";
+
+/** These checks open each page twice, and sometimes press keys, so they get longer than the others. */
+const TIMEOUT_MS = 60_000;
+
+/**
+ * Run the conditions checks against a fixture page or a whole page. Each check opens its own fresh pages.
+ * A check that can't finish reports `error`, and one that can't reduce the page to colors reports `undetermined`.
+ * Neither counts as a pass.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype An archetype name for a fixture, or "page" for a whole page.
+ */
+export async function runConditions(browser, url, archetype) {
+  const results = [];
+  for (const check of conditionChecksFor(archetype)) {
+    results.push(await runCheck(browser, url, check, { kits: [installHelpers, installMeasure, installConditions], needsTrigger: archetype !== "page", timeoutMs: TIMEOUT_MS, waitUntil: archetype === "page" ? "networkidle" : "load" }));
+  }
+  return { status: "ran", checks: results };
+}
+
+/** What a Storybook target says about this tier. */
+export const CONDITIONS_NOT_APPLICABLE_FOR_STORIES = {
+  status: "not-applicable",
+  reason: "Conditions checks open the whole page again with other settings. Storybook stories are audited inside their own frame, so this version doesn't run them.",
+};

package/src/tiers/conditions/kit.js

@@ -0,0 +1,133 @@
+/**
+ * Runs inside the page before any page script. It sets `window.__a11yConditions`, which reads what the page does under
+ * a user's settings and environment: running animations, content that spills past the window, and content a text spacing
+ * override clips. It reports plain facts. The checks in checks.js decide pass or fail.
+ * This function is serialized and sent to the browser, so it can't use anything from outside itself.
+ */
+export function installConditions() {
+  /** A short, readable name for an element: `button#save`, `div.alert`, or `span`. */
+  const describe = (el) => {
+    if (!el || el.nodeType !== 1) return "(document)";
+    const tag = el.localName;
+    if (el.id) return `${tag}#${el.id}`;
+    const first = typeof el.className === "string" ? el.className.trim().split(/\s+/).find(Boolean) : "";
+    return first ? `${tag}.${first}` : tag;
+  };
+
+  /** Keyframe properties that move or resize something. Opacity and color changes aren't motion. */
+  const MOVING = /^(transform|translate|rotate|scale|top|left|right|bottom|inset\w*|margin\w*|offset(Path|Distance|Rotate)|backgroundPosition\w*|height|maxHeight|minHeight|width|maxWidth|minWidth|clipPath|clip)$/;
+  const IGNORED_KEYS = new Set(["offset", "easing", "composite", "computedOffset"]);
+
+  const allElements = () => [...document.body.querySelectorAll("*")];
+
+  /** The scroll container an element sits in, if one hides its overflow sideways (so it doesn't push the page wider). */
+  const scrollsSideways = (el) => {
+    for (let node = el.parentElement; node && node !== document.documentElement; node = node.parentElement) {
+      const x = getComputedStyle(node).overflowX;
+      if (x === "auto" || x === "scroll" || x === "hidden" || x === "clip") return true;
+    }
+    return false;
+  };
+
+  window.__a11yConditions = {
+    describe,
+    /** Every animation and transition running right now. */
+    animations() {
+      return document.getAnimations().map((/** @type {any} */ animation) => {
+        const effect = /** @type {any} */ (animation.effect);
+        const timing = effect?.getComputedTiming?.() ?? {};
+        const keyframes = effect?.getKeyframes?.() ?? [];
+        const props = [...new Set(keyframes.flatMap((frame) => Object.keys(frame)).filter((key) => !IGNORED_KEYS.has(key)))];
+        const target = effect?.target ?? null;
+        const iterations = timing.iterations === Infinity ? "infinite" : timing.iterations;
+        return {
+          kind: animation.constructor.name,
+          name: animation.animationName ?? animation.transitionProperty ?? "",
+          target: describe(target),
+          duration: typeof timing.duration === "number" ? timing.duration : null,
+          iterations,
+          props,
+          moving: props.some((prop) => MOVING.test(prop)),
+        };
+      });
+    },
+    /** How far the page reaches past the window's right edge, and which elements do it. */
+    overflow(rootSelector) {
+      const width = document.documentElement.clientWidth;
+      const offenders = [];
+      for (const el of allElements()) {
+        const box = el.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0) continue;
+        const style = getComputedStyle(el);
+        if (style.visibility === "hidden" || style.display === "none") continue;
+        if (box.right > width + 1 && !scrollsSideways(el)) offenders.push({ element: describe(el), right: Math.round(box.right), width: Math.round(box.width), left: Math.round(box.left) });
+      }
+      const root = rootSelector ? document.querySelector(rootSelector) : null;
+      const rootBox = root && root.getClientRects().length ? root.getBoundingClientRect() : null;
+      return {
+        viewportWidth: width,
+        scrollWidth: document.documentElement.scrollWidth,
+        offenders: offenders.slice(0, 8),
+        offenderCount: offenders.length,
+        root: rootBox ? { element: describe(root), left: Math.round(rootBox.left), right: Math.round(rootBox.right) } : null,
+      };
+    },
+    /** For every element, whether its box cuts off its own content, so two snapshots can show what a change clips. */
+    clipping() {
+      return allElements().map((el) => {
+        const style = getComputedStyle(el);
+        const hidesX = ["hidden", "clip"].includes(style.overflowX);
+        const hidesY = ["hidden", "clip"].includes(style.overflowY);
+        const box = el.getBoundingClientRect();
+        return {
+          /** A one-pixel box that hides its overflow is a screen reader only copy. Nobody sees its text, so nothing is cut off. */
+          visuallyHidden: box.width <= 1 && box.height <= 1,
+          element: describe(el),
+          hidesX,
+          hidesY,
+          overX: el.scrollWidth - el.clientWidth,
+          overY: el.scrollHeight - el.clientHeight,
+          text: (el.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 30),
+        };
+      });
+    },
+    /** Apply the text spacing the success criterion names, with !important so authored styles can't hold it back. */
+    applySpacing() {
+      const style = document.createElement("style");
+      style.setAttribute("data-a11y-spacing", "");
+      style.textContent = "* { line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; } p { margin-bottom: 2em !important; }";
+      document.head.append(style);
+    },
+    /**
+     * Surfaces that carry text over a see-through background or a blur: a background color that isn't fully opaque,
+     * or a backdrop filter. Empty overlays are left out, because they hold no text for the effect to get in the way of.
+     */
+    translucentSurfaces() {
+      const toRgba = window.__a11yMeasure?.rgba;
+      const found = [];
+      for (const el of allElements()) {
+        const box = el.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0) continue;
+        const style = getComputedStyle(el);
+        if (style.visibility === "hidden" || style.display === "none") continue;
+        const own = [...el.childNodes].some((n) => n.nodeType === 3 && n.nodeValue.trim()) || el.matches("input, textarea, select, button");
+        const holdsText = own || (el.textContent ?? "").trim().length > 0;
+        if (!holdsText) continue;
+        const color = toRgba ? toRgba(style.backgroundColor) : null;
+        const seeThrough = Boolean(color) && color[3] > 0 && color[3] < 1;
+        const blur = style.backdropFilter && style.backdropFilter !== "none" ? style.backdropFilter : "";
+        if (seeThrough || blur) found.push({ element: describe(el), background: seeThrough ? `${Math.round(color[3] * 100)}% opaque` : "", backdropFilter: blur });
+      }
+      return found;
+    },
+    /** Elements that opt out of forced colors, and so keep their own colors. */
+    forcedColorOptOuts() {
+      return allElements().filter((el) => getComputedStyle(el).forcedColorAdjust === "none").slice(0, 20).map(describe);
+    },
+    /** A cheap fingerprint of how the page looks in the current color scheme. */
+    appearance() {
+      const html = getComputedStyle(document.documentElement);
+      return { colorScheme: html.colorScheme, background: getComputedStyle(document.body).backgroundColor, color: getComputedStyle(document.body).color };
+    },
+  };
+}

package/src/tiers/interactions/archetypes.js

@@ -5,6 +5,8 @@
  * Checks only use the two hooks (`data-a11y-trigger`, `data-a11y-root`) and ARIA roles.
  */
 
+import { focusIndicatorChanges } from "./focus-indicator.js";
+
 const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
 const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
 const na = (detail) => ({ result: "not-applicable", detail });
@@ -28,15 +30,15 @@ const COMMON = [
     criteria: ["2.4.7"],
     async run(ctx) {
       if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so its focus indicator wasn't checked.");
-      const focused = await ctx.page.evaluate(() => window.__a11y.focusStyle());
+      const focused = await ctx.page.evaluate(() => window.__a11y.focusSnapshot());
       await ctx.page.evaluate(() => window.__a11y.remember());
       const clip = ctx.clipAround(focused.box);
       const shotFocused = await ctx.page.screenshot({ clip });
       await ctx.page.evaluate(() => /** @type {any} */ (window).__a11yLast?.blur());
       await ctx.settle();
-      const unfocused = await ctx.page.evaluate(() => window.__a11y.lastStyle());
-      const changed = Object.keys(focused.style).filter((key) => focused.style[key] !== unfocused?.[key]);
-      if (changed.length) return pass(`Computed style changed on focus: ${changed.join(", ")}.`, { method: "computed-style" });
+      const unfocused = await ctx.page.evaluate(() => window.__a11y.lastSnapshot());
+      const changed = focusIndicatorChanges(focused.parts, unfocused?.parts);
+      if (changed.length) return pass(`Computed style changed on focus: ${changed.join("; ")}.`, { method: "computed-style" });
       const shotBlurred = await ctx.page.screenshot({ clip });
       if (!shotFocused.equals(shotBlurred)) return pass("The pixels around the trigger changed on focus, though no style property did.", { method: "screenshot" });
       return fail("Nothing visible changed when the trigger got keyboard focus. Checked computed styles first, then a screenshot comparison.", { method: "screenshot" });
@@ -85,9 +87,120 @@ async function openMenu(ctx) {
   return null;
 }
 
+// ---- live-region: a message that appears or changes without moving focus ----
+
+/** Press Enter on the trigger and wait for the message. Returns what the page looked like before, and after. */
+async function showMessage(ctx) {
+  await ctx.focus();
+  const before = await ctx.page.evaluate(() => window.__a11y.live());
+  await ctx.press("Enter");
+  const deadline = Date.now() + 2500;
+  let after = await ctx.page.evaluate(() => window.__a11y.live());
+  while (Date.now() < deadline && !(after.present && after.visible && (after.text || after.named))) {
+    await ctx.settle(80);
+    after = await ctx.page.evaluate(() => window.__a11y.live());
+  }
+  return { before, after, appeared: after.present && after.visible };
+}
+
+const NO_MESSAGE = "The message didn't appear when Enter was pressed on the trigger.";
+
+const LIVE_REGION_CHECKS = [
+  {
+    name: "message-in-live-region",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return fail(NO_MESSAGE);
+      if (!after.region) return fail("The message isn't inside an element with role alert, status, or log, or with an aria-live attribute, so a screen reader isn't told when it appears.");
+      if (after.region.politeness === "off") return fail(`The message sits in a region that doesn't announce (${after.region.role ? `role ${after.region.role}` : "aria-live"}${after.region.ariaLive ? `, aria-live="${after.region.ariaLive}"` : ""}), so a screen reader isn't told when it appears.`);
+      return pass(`The message is in a live region (${after.region.role ? `role ${after.region.role}, ` : ""}${after.region.politeness}).`);
+    },
+  },
+  {
+    name: "message-has-text",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its text wasn't checked.`);
+      return after.text || after.named ? pass(`The message says "${after.text || "(named by aria-label)"}".`) : fail("The message has no text and no accessible name, so there's nothing to announce.");
+    },
+  },
+  {
+    name: "region-exists-before-message",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { before, after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its region wasn't checked.`);
+      if (!after.region || after.region.politeness === "off") return na("The message isn't in a live region, so the region's timing doesn't apply.");
+      if (before.regionUids.includes(after.region.uid)) return pass("The live region was already in the page before the message, so assistive technology was watching it.");
+      if (after.region.role === "alert") return pass("The live region was added together with its message. role=\"alert\" is announced when it's inserted, so this works.");
+      return before.ancestorUids.includes(after.region.uid)
+        ? fail("The element was in the page before the message, but it only became a live region when the message arrived. Screen readers often miss that. Put role or aria-live in the page's HTML, and change only what's inside the region.")
+        : fail("The live region was added to the page together with its message. Screen readers often miss that. Keep the region in the page and change what's inside it.");
+    },
+  },
+  {
+    name: "live-politeness-fits-role",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { after, appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its politeness wasn't checked.`);
+      const r = after.region;
+      if (!r) return na("The message isn't in a live region, so there's no politeness to check.");
+      if (r.role === "alert" && r.ariaLive && r.ariaLive.toLowerCase() !== "assertive") return fail(`role="alert" is assertive, but aria-live="${r.ariaLive}" on the same element overrides it.`);
+      if (r.role === "status" && (r.ariaLive ?? "").toLowerCase() === "off") return fail('role="status" is polite, but aria-live="off" on the same element turns announcing off.');
+      return pass(`The region announces ${r.politeness}${r.role ? `, as role ${r.role} implies` : ""}.`);
+    },
+  },
+  {
+    name: "focus-stays-on-trigger",
+    criteria: ["4.1.3"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Focus wasn't checked.`);
+      await ctx.settle(200);
+      const s = await ctx.snap();
+      return s.activeIsTrigger ? pass("Focus stayed on the trigger when the message appeared.") : fail(`Focus moved to ${where(s)} when the message appeared. A status message is announced without taking focus.`);
+    },
+  },
+  {
+    name: "dismiss-works-by-keyboard",
+    criteria: ["2.1.1"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Its controls weren't checked.`);
+      const found = await ctx.page.evaluate(() => window.__a11y.focusDismiss());
+      if (!found.found) return na("The message has no control inside it, so there's nothing to dismiss.");
+      await ctx.settle();
+      await ctx.press("Enter");
+      const gone = await ctx.waitFor((s) => !s.rootExists || !s.rootVisible, 1500);
+      return gone ? pass(`Enter on the ${found.tag}${found.label ? ` "${found.label}"` : ""} removed the message.`) : fail(`Enter on the ${found.tag}${found.label ? ` "${found.label}"` : ""} didn't remove the message.`);
+    },
+  },
+  {
+    name: "focus-kept-after-removal",
+    criteria: ["2.4.3"],
+    async run(ctx) {
+      const { appeared } = await showMessage(ctx);
+      if (!appeared) return na(`${NO_MESSAGE} Focus after removal wasn't checked.`);
+      const found = await ctx.page.evaluate(() => window.__a11y.focusDismiss());
+      if (!found.found) return na("The message has no control inside it, so nothing removes it from the keyboard.");
+      await ctx.settle();
+      await ctx.press("Enter");
+      if (!(await ctx.waitFor((s) => !s.rootExists || !s.rootVisible, 1500))) return na("Enter didn't remove the message, so where focus goes wasn't checked.");
+      await ctx.settle(200);
+      const s = await ctx.snap();
+      return s.bodyActive ? fail("Focus fell back to the page when the message was removed. Move it to the trigger or another control.") : pass(`Focus moved to ${where(s)} when the message was removed.`);
+    },
+  },
+];
+
 // ---- The tables ----
 
 export const ARCHETYPE_CHECKS = {
+  "live-region": LIVE_REGION_CHECKS,
+
   button: [
     { name: "enter-activates", criteria: ["2.1.1"], run: activates("Enter", "Enter") },
     { name: "space-activates", criteria: ["2.1.1"], run: activates("Space", "Space") },

package/src/tiers/interactions/focus-indicator.js

@@ -0,0 +1,39 @@
+/**
+ * Compare the resolved styles of a control with and without keyboard focus, and say which changes can show a focus indicator.
+ * A change counts only if a person could see it: an outline with a width and a color, a box shadow, a border, a color change,
+ * a text decoration, or an element that appeared inside. An outline offset alone doesn't count, because it moves nothing visible.
+ * @param {Record<string, Record<string, any>>} focused Parts of the focused control, keyed by where they are.
+ * @param {Record<string, Record<string, any>> | undefined} unfocused The same parts without focus.
+ * @returns {string[]} Each change, such as `the element: outline`.
+ */
+export function focusIndicatorChanges(focused, unfocused) {
+  const changes = [];
+  for (const [where, now] of Object.entries(focused)) {
+    const before = unfocused?.[where];
+    if (!before) {
+      if (now.rendered) changes.push(`${where}: appeared on focus`);
+      continue;
+    }
+    // A ring that stays in the page but only shows on focus, such as a ripple, goes from not rendered to rendered.
+    if (now.rendered && !before.rendered) {
+      changes.push(`${where}: appeared on focus`);
+      continue;
+    }
+    const found = [];
+    const drawnOutline = (s) => s.outlineStyle !== "none" && parseFloat(s.outlineWidth) > 0 && !transparent(s.outlineColor);
+    if (drawnOutline(now) && (!drawnOutline(before) || now.outlineWidth !== before.outlineWidth || now.outlineColor !== before.outlineColor || now.outlineStyle !== before.outlineStyle)) found.push("outline");
+    if (now.boxShadow !== before.boxShadow) found.push("box-shadow");
+    const drawnBorder = (s) => s.borderTopStyle !== "none" && parseFloat(s.borderTopWidth) > 0;
+    if (drawnBorder(now) && (now.borderTopColor !== before.borderTopColor || now.borderTopWidth !== before.borderTopWidth || !drawnBorder(before))) found.push("border");
+    if (now.backgroundColor !== before.backgroundColor) found.push("background color");
+    if (now.color !== before.color) found.push("text color");
+    if (now.textDecorationLine !== before.textDecorationLine) found.push("text decoration");
+    if (!now.rendered && !before.rendered) continue;
+    for (const what of found) changes.push(`${where}: ${what}`);
+  }
+  return changes;
+}
+
+function transparent(color) {
+  return color === "transparent" || /^rgba\(.*,\s*0\)$/.test(color) || /\/\s*0\)$/.test(color);
+}