automatica11y 0.3.3 → 0.4.0

package/src/schema.js

@@ -2,20 +2,20 @@ import * as v from "valibot";
 
 export const WCAG_VERSIONS = ["2.0", "2.1", "2.2"];
 export const LEVELS = ["A", "AA", "AAA"];
-export const TIERS = ["rules", "interactions", "computed", "vsr"];
+export const TIERS = ["rules", "interactions", "computed", "conditions", "vsr"];
 export const ENGINES = ["axe", "ibm"];
 export const LIB_A11Y = ["on", "off"];
 export const IMPACTS = ["minor", "moderate", "serious", "critical"];
 export const TOOLKIT_LEVELS = [1, 2, 3];
 export const FAIL_MODES = ["any", "all"];
-export const ARCHETYPES = ["button", "link", "dialog", "menu", "tabs", "combobox", "form-field", "accordion", "tooltip", "chart"];
-export const FLAVORS = ["react", "wc"];
-export const MAPPING_STATUSES = ["template", "authored", "needs-fixture", "no-match"];
+export const ARCHETYPES = ["button", "link", "dialog", "menu", "tabs", "combobox", "form-field", "accordion", "tooltip", "live-region", "chart"];
+export const FLAVORS = ["react", "vue", "wc"];
+export const MAPPING_STATUSES = ["template", "authored", "generated", "needs-fixture", "no-match"];
 
 /** What a candidate mapping says about one archetype of one npm target. */
 export const MappingEntrySchema = v.object({
   flavor: v.optional(v.picklist(FLAVORS)),
-  /** Export name (React) the fixture or template uses. */
+  /** Export name (React or Vue) the fixture or template uses. */
   export: v.optional(v.string()),
   /** Custom element tag (web components) the fixture or template uses. */
   tag: v.optional(v.string()),
@@ -23,7 +23,14 @@ export const MappingEntrySchema = v.object({
   fixture: v.optional(v.nullable(v.string())),
   /** The library ships opt-in accessibility features. The fixture gets `libA11y` (true or false) and `--lib-a11y` runs it both ways. */
   libA11y: v.optional(v.boolean()),
+  /** Other packages to install beside the target, such as the token stylesheet or theme the library asks for. A fixture can then import them. */
+  install: v.optional(v.array(v.string())),
   status: v.optional(v.picklist(MAPPING_STATUSES)),
+  /** For a generated fixture: which recipe worked, what it was, which parts it used, and where its source was written. */
+  recipe: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  used: v.optional(v.array(v.string())),
+  generatedFile: v.optional(v.string()),
   candidates: v.optional(v.array(v.string())),
   parts: v.optional(v.array(v.string())),
   reason: v.optional(v.string()),
@@ -42,7 +49,7 @@ export function parseMappingFile(input) {
   return result.output;
 }
 
-export const TARGET_KINDS = ["npm", "npm-react", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
+export const TARGET_KINDS = ["npm", "npm-react", "npm-vue", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
 
 const nullableString = v.nullable(v.string());
 
@@ -77,6 +84,8 @@ export const PlanSchema = v.object({
     archetypes: v.nullable(v.array(v.picklist(ARCHETYPES))),
     mapping: nullableString,
     maxStories: v.pipe(v.number(), v.integer(), v.minValue(1)),
+    /** Build fixtures from a package's parts when none is authored. A plan saved before this existed generates. */
+    generate: v.optional(v.boolean(), true),
     out: v.string(),
     fail: v.nullable(FailConfigSchema),
   }),
@@ -200,6 +209,17 @@ export const TargetResultSchema = v.object({
     v.object({
       status: v.picklist(["ran", "gap"]),
       reason: v.optional(v.nullable(v.string())),
+      /** Where the fixture came from, and for a generated one what was tried. */
+      fixture: v.optional(
+        v.object({
+          source: v.picklist(["template", "authored", "generated", "none"]),
+          recipe: v.optional(v.string()),
+          summary: v.optional(v.string()),
+          used: v.optional(v.array(v.string())),
+          file: v.optional(v.nullable(v.string())),
+          attempts: v.optional(v.array(v.object({ recipe: v.string(), summary: v.string(), ok: v.boolean(), reason: v.nullable(v.string()) }))),
+        }),
+      ),
       configs: v.array(v.object({ libA11y: v.picklist(["on", "off", "n/a"]), state: v.optional(v.string()), tiers: v.record(v.string(), TierResultSchema) })),
     }),
   ),
@@ -207,11 +227,14 @@ export const TargetResultSchema = v.object({
   npm: v.optional(
     v.object({
       name: v.string(),
+      /** The sub-path of the package that was tested, such as `button/v2`, or null for the package itself. */
+      subpath: v.optional(nullableString),
       version: nullableString,
       flavor: v.picklist(FLAVORS),
       framework: nullableString,
       react: nullableString,
       reactDom: nullableString,
+      vue: v.optional(nullableString),
       tags: v.array(v.string()),
     }),
   ),
@@ -221,6 +244,7 @@ export const TargetResultSchema = v.object({
     notTestable: v.array(v.string()),
     interactions: v.optional(v.object({ pass: v.number(), fail: v.number(), notApplicable: v.number(), error: v.number() })),
     computed: v.optional(v.object({ pass: v.number(), fail: v.number(), undetermined: v.number(), notApplicable: v.number(), error: v.number() })),
+    conditions: v.optional(v.object({ pass: v.number(), fail: v.number(), undetermined: v.number(), notApplicable: v.number(), error: v.number() })),
     vsr: v.optional(v.object({ walks: v.number(), flagged: v.number() })),
   }),
   warnings: v.array(v.string()),

package/src/tiers/computed/checks.js

@@ -5,8 +5,9 @@
  * It's a gap and never a pass.
  * These are automatica11y's own measurements. They're reported on their own and never added to axe-core or IBM counts.
  */
+import { num } from "../../text.js";
 import { criterionRef } from "../../wcag/index.js";
-import { contrastOver, contrastRatio, formatRatio, textThreshold } from "./color.js";
+import { contrastOver, contrastRatio, formatRatio, ringIsEnough, textThreshold } from "./color.js";
 
 const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
 const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
@@ -67,7 +68,7 @@ const TEXT_CONTRAST = {
     const skipped = reached === null ? " The trigger couldn't be reached with Tab, so keyboard focus wasn't measured." : "";
     if (failed.length) {
       const f = failed[0];
-      const more = failed.length > 1 ? ` ${failed.length - 1} more measurement${failed.length > 2 ? "s are" : " is"} below its threshold.` : "";
+      const more = failed.length > 1 ? ` ${num(failed.length - 1)} more measurement${failed.length > 2 ? "s are" : " is"} below its threshold.` : "";
       return fail(`In ${f.state}, "${f.text}" has ${formatRatio(f.ratio)} against its background and needs ${f.required}:1.${more} ${list}${skipped}`, { measurements });
     }
     if (unknown.length || reached === null) {
@@ -150,9 +151,47 @@ const FOCUS_CONTRAST = {
     if (px.changed === 0) return na("Nothing visible changed on focus, so there's no indicator to measure. The interactions tier reports that as a failure.");
     const perimeter = 2 * (rest.box.width + rest.box.height);
     const measurements = [{ changedPixels: px.changed, pixelsAtLeast3to1: px.strong, strongestChange: floor2(px.max), perimeterPixels: Math.round(perimeter) }];
-    const detail = `${px.strong} of ${px.changed} changed pixels reach 3:1 against their unfocused color, and the strongest change is ${formatRatio(px.max)}. A ring around this control needs about ${Math.round(perimeter)}.`;
-    return px.strong >= perimeter ? pass(detail, { method: "pixels", measurements }) : fail(detail, { method: "pixels", measurements });
+    const detail = `${num(px.strong)} of ${num(px.changed)} changed pixels reach 3:1 against their unfocused color, and the strongest change is ${formatRatio(px.max)}. Enough to count is about half the control's perimeter, ${Math.round(perimeter / 2)}.`;
+    return ringIsEnough(px.strong, perimeter) ? pass(detail, { method: "pixels", measurements }) : fail(detail, { method: "pixels", measurements });
   },
 };
 
-export const COMPUTED_CHECKS = [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST];
+/**
+ * For a live region, the trigger is only a button that makes the message appear, so the message is what gets measured:
+ * the text that appears after the trigger is activated, in its resting state.
+ */
+const MESSAGE_TEXT_CONTRAST = {
+  name: "message-text-contrast",
+  criteria: ["1.4.3"],
+  async run(ctx) {
+    await parkPointer(ctx);
+    const before = (await ctx.page.evaluate(() => window.__a11yMeasure.text("page"))) ?? [];
+    await ctx.focus();
+    await ctx.press("Enter");
+    await ctx.settle(SETTLE_MS);
+    const after = (await ctx.page.evaluate(() => window.__a11yMeasure.text("page"))) ?? [];
+    const known = new Set(before.map((p) => p.key));
+    const fresh = after.filter((p) => !known.has(p.key));
+    if (fresh.length === 0) return na("No new visible text appeared when the trigger was activated, so there's no message text to measure.");
+    const rows = [];
+    const unknown = [];
+    for (const part of fresh) {
+      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 measurements = rows.map((r) => ({ text: r.text, ratio: floor2(r.ratio), required: r.required }));
+    const failed = rows.filter((r) => r.ratio < r.required).sort((a, b) => a.ratio / a.required - b.ratio / b.required);
+    if (failed.length) return fail(`The message text "${failed[0].text}" has ${formatRatio(failed[0].ratio)} against its background and needs ${failed[0].required}:1.`, { measurements });
+    if (unknown.length) return undetermined(`${rows.length ? `The lowest measured is ${formatRatio(Math.min(...rows.map((r) => r.ratio)))}. ` : ""}${unknown[0]}`, { measurements });
+    const lowest = rows.reduce((a, b) => (b.ratio / b.required < a.ratio / a.required ? b : a));
+    return pass(`The message text "${lowest.text}" has ${formatRatio(lowest.ratio)} against its background (needs ${lowest.required}:1).`, { measurements });
+  },
+};
+
+/** The checks that apply to an archetype. */
+export function computedChecksFor(archetype) {
+  return archetype === "live-region" ? [MESSAGE_TEXT_CONTRAST] : [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST];
+}
+
+/** Every computed check, for tests and docs. */
+export const COMPUTED_CHECKS = [TEXT_CONTRAST, BOUNDARY_CONTRAST, FOCUS_CONTRAST, MESSAGE_TEXT_CONTRAST];

package/src/tiers/computed/color.js

@@ -34,6 +34,14 @@ export function textThreshold(sizePx, weight) {
   return sizePx >= 24 || (sizePx >= 18.66 && Number(weight) >= 700) ? 3 : 4.5;
 }
 
+/**
+ * Is a focus change big enough to count as an indicator? Pixels that change by 3:1 or more have to cover at least half the
+ * control's perimeter: a ring or underline a person can't miss, even with anti-aliased edges and rounded corners.
+ */
+export function ringIsEnough(strongPixels, perimeter) {
+  return strongPixels >= perimeter / 2;
+}
+
 /** "4.52:1". The ratio is cut down, never rounded up, so 2.999 never reads as 3. */
 export function formatRatio(ratio) {
   return `${(Math.floor(ratio * 100) / 100).toFixed(2).replace(/\.?0+$/, "")}:1`;

package/src/tiers/computed/index.js

@@ -1,6 +1,6 @@
 import { installHelpers } from "../interactions/helpers.js";
 import { runCheck } from "../interactions/index.js";
-import { COMPUTED_CHECKS } from "./checks.js";
+import { computedChecksFor } from "./checks.js";
 import { installMeasure } from "./measure-kit.js";
 
 /**
@@ -14,7 +14,7 @@ import { installMeasure } from "./measure-kit.js";
 export async function runComputed(browser, url, archetype) {
   if (archetype === "chart") return { status: "not-applicable", reason: "The chart archetype has no trigger to measure." };
   const results = [];
-  for (const check of COMPUTED_CHECKS) results.push(await runCheck(browser, url, check, { kits: [installHelpers, installMeasure] }));
+  for (const check of computedChecksFor(archetype)) results.push(await runCheck(browser, url, check, { kits: [installHelpers, installMeasure] }));
   return { status: "ran", checks: results };
 }
 

package/src/tiers/computed/measure-kit.js

@@ -88,22 +88,36 @@ export function installMeasure() {
     return { inset: /\binset\b/.test(text), x: x ?? 0, y: y ?? 0, blur: blur ?? 0, spread: spread ?? 0, color: color ? rgba(color[0]) : null };
   };
 
+  const keys = new WeakMap();
+  let keyCounter = 0;
+
   window.__a11yMeasure = {
     rgba,
-    /** The text inside the trigger: each element that directly holds text, with its color, size, and backdrop. */
-    text() {
+    /**
+     * The text inside the trigger (or, with "page", anywhere on the page except the trigger): each piece of text with its
+     * color, size, and backdrop. Slotted text takes its style from the slot's parent in the flattened tree, and text that is
+     * visually hidden (a one-pixel screen reader copy) is left out. `key` lets a later call tell which text is new.
+     */
+    text(scope) {
+      const wholePage = scope === "page" || scope === "all";
       const el = trigger();
-      if (!el) return null;
+      if (!el && !wholePage) return null;
       const parts = [];
       const seen = new Set();
-      const consider = (node, label) => {
-        if (seen.has(node) || !visibleBox(node)) return;
-        seen.add(node);
+      const consider = (textNode, label, own) => {
+        const host = own ?? textNode.parentElement;
+        const node = own ?? textNode.assignedSlot ?? host;
+        if (!host || !node || seen.has(textNode) || !visibleBox(host)) return;
+        const box = host.getBoundingClientRect();
+        if (box.width <= 1 && box.height <= 1) return;
+        seen.add(textNode);
         const style = getComputedStyle(node);
         if (style.visibility === "hidden") return;
+        if (!keys.has(textNode)) keys.set(textNode, (keyCounter += 1));
         const behind = backdrop(node, true);
         const color = rgba(style.color);
         parts.push({
+          key: keys.get(textNode),
           text: label.replace(/\s+/g, " ").trim().slice(0, 40),
           color,
           size: parseFloat(style.fontSize),
@@ -112,11 +126,17 @@ export function installMeasure() {
           undetermined: behind.reason ?? (color ? null : "its color couldn't be read"),
         });
       };
-      const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
-      for (let node = walker.nextNode(); node && parts.length < 12; node = walker.nextNode()) {
-        if (node.nodeValue && node.nodeValue.trim() && node.parentElement) consider(node.parentElement, node.nodeValue);
+      const walk = (root) => {
+        const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, wholePage ? { acceptNode: (n) => (n.parentElement?.closest(scope === "all" ? "script, style, noscript" : "script, style, noscript, [data-a11y-trigger]") ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT) } : undefined);
+        for (let node = walker.nextNode(); node && parts.length < (scope === "all" ? 300 : 30); node = walker.nextNode()) {
+          if (node.nodeValue && node.nodeValue.trim() && node.parentElement) consider(node, node.nodeValue);
+        }
+        if (wholePage) for (const host of root.querySelectorAll("*")) if (host.shadowRoot) walk(host.shadowRoot);
+      };
+      walk(wholePage ? document.body : el);
+      if (!wholePage && el.matches("input, textarea, select") && "value" in el && String(el.value).trim()) {
+        consider(el, String(el.value), el);
       }
-      if (el.matches("input, textarea, select") && "value" in el && String(el.value).trim()) consider(el, String(el.value));
       return parts;
     },
     /** What the control looks like from outside: label, input, or icon, and the colors that mark its edge. */

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.",
+};