@gusnips/vite 0.8.43 → 0.8.45

package/src/contrast-tokens.test.ts

@@ -0,0 +1,256 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  checkTokenPairs,
+  formatContrastReport,
+  loadTokenThemes,
+  type ContrastProblem,
+  type TokenPairsBundle,
+} from "./contrast.ts";
+
+/**
+ * `checkTokenPairs` and `loadTokenThemes`, the plain-CSS half of `contrast.ts`. Nothing is
+ * compiled, so these read real stylesheets and run in milliseconds, unlike the Tailwind half.
+ *
+ * Two committed fixtures keep the whole contract (`ok.css`, and `ok-media.css` with both dark
+ * blocks wrapped in `@media`) and are the positive controls. Every failing case is one of them
+ * with ONE line changed, written to a temp folder: the change sits beside its assertion, and
+ * `change` throws when the text it was told to replace is not there, so a fixture edited later
+ * cannot turn a test into one that passes for nothing.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const fixtures = join(here, "fixtures/contrast/tokens");
+
+const bundle: TokenPairsBundle = {
+  name: "site",
+  css: "tokens.css",
+  dark: ':root[data-theme="dark"]',
+  system: ":root:not([data-theme])",
+  textPairs: [
+    ["--ground", "--ink"],
+    ["--ground", "--muted"],
+    ["--accent", "--accent-ink"],
+  ],
+  nonTextPairs: [
+    ["--ground", "--line"],
+    ["--ground", "--accent"],
+  ],
+};
+
+const folders: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    folders.splice(0).map((folder) => rm(folder, { recursive: true, force: true })),
+  );
+});
+
+async function fixture(name: string): Promise<string> {
+  return readFile(join(fixtures, name), "utf8");
+}
+
+/** Replace text that must be there, every occurrence: the fallback repeats the dark colours. */
+function change(css: string, from: string, to: string): string {
+  if (!css.includes(from))
+    throw new Error(`the fixture no longer contains ${JSON.stringify(from)}`);
+  return css.replaceAll(from, to);
+}
+
+async function check(css: string, overrides: Partial<TokenPairsBundle> = {}) {
+  const root = await mkdtemp(join(tmpdir(), "kit-contrast-tokens-"));
+  folders.push(root);
+  await writeFile(join(root, "tokens.css"), css);
+  return checkTokenPairs([{ ...bundle, ...overrides }], { root });
+}
+
+const lineOf = (css: string, text: string): number =>
+  css.split("\n").findIndex((line) => line.includes(text)) + 1;
+
+const only = (problems: ContrastProblem[]): ContrastProblem => {
+  expect(problems).toHaveLength(1);
+  return problems[0]!;
+};
+
+describe("checkTokenPairs", () => {
+  it("passes a palette whose pairs clear their floors in both themes", async () => {
+    const report = await check(await fixture("ok.css"));
+    expect(report.problems).toEqual([]);
+    expect(formatContrastReport(report)).toBe("✔ contrast: no errors");
+  });
+
+  it("reads blocks wrapped in @media, at any depth", async () => {
+    const report = await check(await fixture("ok-media.css"));
+    expect(report.problems).toEqual([]);
+  });
+
+  it("compares the fallback as colours and selectors as selectors, not as text", async () => {
+    let css = await fixture("ok.css");
+    css = change(css, "    --ink: #f2f2f2;", "    --ink: #F2F2F2;");
+    css = change(css, ':root[data-theme="dark"]', ":root[data-theme='dark']");
+    expect((await check(css)).problems).toEqual([]);
+  });
+
+  it("fails a pair under its floor in the theme where it fails, and points at the line", async () => {
+    const css = change(await fixture("ok.css"), "--muted: #b3b3b3", "--muted: #3a3a3a");
+    const report = await check(css);
+    const found = only(report.problems);
+    expect(found).toMatchObject({ rule: "floor", level: "error", bundle: "site" });
+    expect(found.message).toBe(
+      "dark: --muted (#3a3a3a) on --ground (#121212) is 1.65:1, under the 4.5:1 floor for text (WCAG 1.4.3)",
+    );
+    expect(found.at).toBe(`tokens.css:${String(lineOf(css, "--muted: #3a3a3a"))}`);
+    // The formatter is checkContrast's own, so a repo prints and exits the same way for both.
+    expect(formatContrastReport(report)).toContain("✖ contrast: 1 error(s)");
+  });
+
+  it("holds a pair that is not text to the lower floor", async () => {
+    const css = change(await fixture("ok.css"), "--line: #767676", "--line: #cccccc");
+    expect(only((await check(css)).problems).message).toBe(
+      "light: --line (#cccccc) on --ground (#ffffff) is 1.61:1, under the 3:1 floor for a control or icon (WCAG 1.4.11)",
+    );
+  });
+
+  it("takes the floors from the bundle", async () => {
+    const css = change(await fixture("ok.css"), "--muted: #555555", "--muted: #999999");
+    expect(only((await check(css)).problems).message).toContain("2.85:1, under the 4.5:1 floor");
+    expect((await check(css, { textFloor: 2.5 })).problems).toEqual([]);
+    // Raising the non-text floor fails the untouched palette: --line is 4.54:1 in the light theme.
+    const strict = await check(await fixture("ok.css"), { nonTextFloor: 5 });
+    expect(only(strict.problems).message).toContain(
+      "light: --line (#767676) on --ground (#ffffff) is 4.54:1",
+    );
+  });
+
+  it("reports a colour one theme declares and the other does not, once", async () => {
+    // The dark block loses --line (and the fallback with it, so only one rule fires).
+    const noDark = change(await fixture("ok.css"), "  --line: #8a8a8a;\n", "");
+    const dropped = only((await check(noDark)).problems);
+    expect(dropped.rule).toBe("missing");
+    expect(dropped.message).toContain("`--line` is in the light block but not in the dark block");
+    expect(dropped.at).toBe(`tokens.css:${String(lineOf(noDark, "--line: #767676"))}`);
+
+    const noLight = change(await fixture("ok.css"), "  --accent-ink: #fff;\n", "");
+    const unbound = only((await check(noLight)).problems);
+    expect(unbound.rule).toBe("missing");
+    expect(unbound.message).toContain("`--accent-ink` is in the dark block but not in the light");
+  });
+
+  it("reports a pair that names a token no block declares, once however many pairs use it", async () => {
+    const report = await check(await fixture("ok.css"), {
+      textPairs: [
+        ["--ground", "--inkk"],
+        ["--inkk", "--muted"],
+        ["ground", "--ink"],
+      ],
+    });
+    expect(report.problems.map((p) => p.rule)).toEqual(["missing", "missing"]);
+    expect(report.problems[0]?.message).toContain("`--inkk`, which neither the light nor");
+    expect(report.problems[1]?.message).toContain("`ground`");
+    expect(report.problems[1]?.message).toContain("start with --");
+  });
+
+  it("fails a fallback that holds a different colour, naming both", async () => {
+    const css = change(await fixture("ok.css"), "    --ink: #f2f2f2;", "    --ink: #eeeeee;");
+    const found = only((await check(css)).problems);
+    expect(found.rule).toBe("mirror");
+    expect(found.message).toBe(
+      "`--ink` is #f2f2f2 in the dark block but #eeeeee in the system block",
+    );
+    expect(found.at).toBe(`tokens.css:${String(lineOf(css, "--ink: #eeeeee"))}`);
+  });
+
+  it("fails a fallback that lacks a token, or holds one the dark block lacks", async () => {
+    const lacks = change(await fixture("ok.css"), "    --line: #8a8a8a;\n", "");
+    expect(only((await check(lacks)).problems).message).toBe(
+      "`--line` is in the dark block but not in the system block",
+    );
+    const extra = change(
+      await fixture("ok.css"),
+      "    --accent: #7ab7ff;",
+      "    --accent: #7ab7ff;\n    --extra: #000000;",
+    );
+    expect(only((await check(extra)).problems).message).toBe(
+      "`--extra` is in the system block but not in the dark block",
+    );
+  });
+
+  it("fails a fallback written outside @media (prefers-color-scheme: dark)", async () => {
+    const css = change(
+      await fixture("ok.css"),
+      "@media (prefers-color-scheme: dark)",
+      "@media print",
+    );
+    const found = only((await check(css)).problems);
+    expect(found.rule).toBe("mirror");
+    expect(found.message).toContain("is not inside @media (prefers-color-scheme: dark)");
+  });
+
+  it("fails a fallback that is not there, and reads none when the bundle names none", async () => {
+    const css = await fixture("ok.css");
+    const absent = only((await check(css, { system: ":root:not([data-mode])" })).problems);
+    expect(absent.rule).toBe("mirror");
+    expect(absent.message).toContain("no `:root:not([data-mode])` block");
+
+    const differs = change(css, "    --ink: #f2f2f2;", "    --ink: #eeeeee;");
+    expect((await check(differs, { system: undefined })).problems).toEqual([]);
+  });
+
+  it("fails a pair it cannot measure, and leaves tokens no pair uses alone", async () => {
+    // ok.css already carries `--radius: 8px` in the light block and passes: geometry is skipped.
+    const css = change(await fixture("ok.css"), "--muted: #555555", "--muted: rgb(85 85 85)");
+    const found = only((await check(css)).problems);
+    expect(found.rule).toBe("floor");
+    expect(found.message).toContain("cannot measure --muted (rgb(85 85 85))");
+  });
+
+  it("a stylesheet or block that is not there fails the gate instead of passing it", async () => {
+    const css = await fixture("ok.css");
+    const noFile = await checkTokenPairs([bundle], { root: fixtures });
+    expect(only(noFile.problems)).toMatchObject({
+      rule: "load",
+      message: "tokens.css could not be read",
+    });
+
+    const noDark = only((await check(css, { dark: '[data-theme="night"]' })).problems);
+    expect(noDark.rule).toBe("load");
+    expect(noDark.message).toContain('no `[data-theme="night"]` block for the dark colours');
+
+    const same = only((await check(css, { light: bundle.dark })).problems);
+    expect(same.rule).toBe("load");
+    expect(same.message).toContain("must differ");
+  });
+
+  it("does not read a block that holds another block", async () => {
+    const css = change(
+      await fixture("ok.css"),
+      "  --accent-ink: #0a1a2b;\n}\n\n@media",
+      "  --accent-ink: #0a1a2b;\n  & a {\n    color: red;\n  }\n}\n\n@media",
+    );
+    expect(only((await check(css)).problems).rule).toBe("load");
+  });
+});
+
+describe("loadTokenThemes", () => {
+  it("hands back both palettes as hex, so an adopter can add a check of its own", async () => {
+    const { light, dark } = await loadTokenThemes(
+      { css: "ok.css", dark: bundle.dark },
+      { root: fixtures },
+    );
+    expect(light.get("--ground")).toBe("#ffffff");
+    expect(dark.get("--ground")).toBe("#121212");
+    // `#fff` comes back as `#ffffff`, and `--radius: 8px` is geometry, not a colour.
+    expect(light.get("--accent-ink")).toBe("#ffffff");
+    expect(light.has("--radius")).toBe(false);
+  });
+
+  it("throws, saying what is missing, rather than returning two empty palettes", async () => {
+    await expect(
+      loadTokenThemes({ css: "ok.css", dark: '[data-theme="night"]' }, { root: fixtures }),
+    ).rejects.toThrow('no `[data-theme="night"]` block');
+    await expect(
+      loadTokenThemes({ css: "nope.css", dark: bundle.dark }, { root: fixtures }),
+    ).rejects.toThrow("nope.css could not be read");
+  });
+});

package/src/contrast.ts

@@ -30,9 +30,20 @@
  * - **dead**: a class that compiles to no rule at all — a token Tailwind does not have, or a
  *   name the scanner caught half of. A warning: dynamic construction reads the same way.
  *
+ * `checkContrast` is the Tailwind reading. `checkTokenPairs` (further down) is the other one, for
+ * an app whose colours are plain CSS custom properties: it reads a light block and a dark block as
+ * text, holds a list of pairs to a floor in both, and reports through the same problems and the
+ * same formatter. It adds two rules:
+ *
+ * - **missing**: a colour one theme declares and the other does not, or a pair that names a token
+ *   neither declares. A typo in a pair would otherwise read as a pair that passes.
+ * - **mirror**: the system fallback (the dark colours repeated under `prefers-color-scheme` for a
+ *   page that has chosen no theme) differs from the dark block, or sits outside that query.
+ *
  * Runs on node and bun: `fs.promises.glob`, never Bun's `Glob`, and no `import.meta.dir`.
- * Needs `@tailwindcss/cli` installed where it runs (an optional peer, reachable only from
- * `@gusnips/vite/contrast`), because the fixture is compiled, not guessed.
+ * `checkContrast` needs `@tailwindcss/cli` installed where it runs (an optional peer, reachable
+ * only from `@gusnips/vite/contrast`), because the fixture is compiled, not guessed.
+ * `checkTokenPairs` compiles nothing and needs no peer.
  */
 import { spawnSync } from "node:child_process";
 import { glob, mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -56,7 +67,8 @@ export interface CheckContrastOptions {
   root?: string;
 }
 
-export type ContrastRule = "load" | "floor" | "retune" | "rebind" | "untokened" | "hover" | "dead";
+export type ContrastRule =
+  "load" | "floor" | "retune" | "rebind" | "untokened" | "hover" | "dead" | "missing" | "mirror";
 
 export interface ContrastProblem {
   rule: ContrastRule;
@@ -149,6 +161,13 @@ const ATTR = /\bclass(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|`((?:[^`$]|\$(?!\{))
 const HELPER = /\b(?:cn|clsx|cva|twMerge|twJoin)\s*\(([^)]*)\)/g;
 const STR = /"([^"]*)"|'([^']*)'/g;
 
+/** The 1-based line a character offset falls on. */
+function lineAt(source: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (source.charCodeAt(i) === 10) line++;
+  return line;
+}
+
 const skipped = (file: string): boolean =>
   /(?:^|\/)__tests__\//.test(file) || /\.(test|spec)\.[tj]sx?$/.test(file);
 
@@ -164,11 +183,6 @@ async function scanSources(
       if (!skipped(file)) files.add(file);
     }
   }
-  const lineAt = (source: string, index: number): number => {
-    let line = 1;
-    for (let i = 0; i < index; i++) if (source.charCodeAt(i) === 10) line++;
-    return line;
-  };
   const keep = (raw: string, file: string, index: number, source: string): void => {
     for (const cls of raw.split(/\s+/).filter(Boolean)) {
       // A token that would break the fixture's quoting is skipped rather than escaped:
@@ -506,3 +520,356 @@ export function formatContrastReport(report: ContrastReport): string {
   );
   return lines.join("\n");
 }
+
+// ── Plain CSS tokens ──────────────────────────────────────────────────────────
+// The same gate for an app with no Tailwind `@theme`: its colours are custom properties in a
+// light block and a dark block, and a list of pairs that must stay readable in both. The file is
+// read as text and nothing is compiled, so this reading installs no optional peer.
+//
+// The limits are stated rather than hidden: hex colours only (a pair that names anything else
+// fails as unmeasurable, never passes), blocks found by their selector text, and a block that
+// holds another block (nested CSS) is not read. There is no CSS parser here. If themes outgrow
+// flat blocks, replace `leafRules` with one.
+
+/** Two custom properties, `[background, foreground]`, written as the CSS names them:
+ *  `["--ground", "--ink"]`. The ratio is the same either way round; the order only decides how a
+ *  problem reads. */
+export type TokenPair = readonly [background: string, foreground: string];
+
+export interface TokenPairsBundle {
+  /** Shown beside every problem: `"apps/site"`. */
+  name: string;
+  /** The stylesheet holding the colour blocks, relative to `root`. */
+  css: string;
+  /** The selector of the light block. Default `":root"`. It must differ from `dark`. */
+  light?: string;
+  /** The selector of the dark block: `':root[data-theme="dark"]'`. */
+  dark: string;
+  /**
+   * The selector of the system fallback: the dark colours again, for a page that has chosen no
+   * theme, inside `@media (prefers-color-scheme: dark)`: `":root:not([data-theme])"`. It must
+   * hold exactly the dark block's tokens and values. Leave it off when there is none.
+   */
+  system?: string;
+  /** Pairs read as text. Held to `textFloor`. */
+  textPairs?: readonly TokenPair[];
+  /** Pairs that are not text: borders, focus rings, icons. Held to `nonTextFloor`. */
+  nonTextPairs?: readonly TokenPair[];
+  /** Default 4.5 (WCAG 1.4.3). */
+  textFloor?: number;
+  /** Default 3 (WCAG 1.4.11). */
+  nonTextFloor?: number;
+}
+
+/** The hex colours of each theme, `--ground` → `#ffffff`, for a check of your own. */
+export interface TokenThemes {
+  light: Map<string, string>;
+  dark: Map<string, string>;
+}
+
+interface TokenDecl {
+  value: string;
+  line: number;
+}
+
+interface CssRule {
+  selectors: string[];
+  /** The at-rules around it, outermost first: `@media screen @media (prefers-color-scheme: dark)`. */
+  within: string;
+  tokens: Map<string, TokenDecl>;
+}
+
+interface TokenBlock {
+  tokens: Map<string, TokenDecl>;
+  /** `within` of every block that matched, since one selector may be written twice. */
+  within: string[];
+}
+
+interface TokenBlocks {
+  light: TokenBlock;
+  dark: TokenBlock;
+  /** `null` when the bundle names no system block, or names one that is not in the file. */
+  system: TokenBlock | null;
+}
+
+const PREFERS_DARK = /\(\s*prefers-color-scheme\s*:\s*dark\s*\)/;
+
+/** `:root[data-theme='dark']` and `:root[data-theme="dark"]` are the same selector. */
+const selectorOf = (text: string): string => text.replace(/\s+/g, " ").replace(/'/g, '"').trim();
+
+/** The comparable form of a value: `#FFF` and `#ffffff` are one colour. */
+const canonical = (value: string): string =>
+  normalizeHex(value) ?? value.replace(/\s+/g, " ").toLowerCase();
+
+/**
+ * Every innermost `selector { … }` block with the at-rules around it, and the custom properties
+ * it declares. Text, not syntax: a brace or semicolon inside a string or `url()` is not understood.
+ */
+function leafRules(css: string): CssRule[] {
+  // Comments become spaces, so a `{` in one is not a block and every offset still names its line.
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "));
+  const rules: CssRule[] = [];
+  const open: Array<{ prelude: string; bodyAt: number; nested: boolean }> = [];
+  let preludeFrom = 0;
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i];
+    if (char === "{") {
+      const parent = open.at(-1);
+      if (parent !== undefined) parent.nested = true;
+      open.push({ prelude: source.slice(preludeFrom, i).trim(), bodyAt: i + 1, nested: false });
+      preludeFrom = i + 1;
+    } else if (char === "}") {
+      const block = open.pop();
+      preludeFrom = i + 1;
+      if (block === undefined || block.nested || block.prelude.startsWith("@")) continue;
+      const tokens = new Map<string, TokenDecl>();
+      for (const match of source.slice(block.bodyAt, i).matchAll(/(--[\w-]+)\s*:\s*([^;]*)/g)) {
+        tokens.set(match[1] ?? "", {
+          value: (match[2] ?? "").trim(),
+          line: lineAt(source, block.bodyAt + match.index),
+        });
+      }
+      rules.push({
+        selectors: block.prelude.split(",").map(selectorOf),
+        within: open
+          .map((parent) => parent.prelude)
+          .filter((prelude) => prelude.startsWith("@"))
+          .join(" "),
+        tokens,
+      });
+    } else if (char === ";") {
+      preludeFrom = i + 1;
+    }
+  }
+  return rules;
+}
+
+/** Every block written with this selector, merged: a later token wins, as it does in CSS. */
+function blockOf(rules: readonly CssRule[], selector: string): TokenBlock | null {
+  const wanted = selectorOf(selector);
+  const found = rules.filter((rule) => rule.selectors.includes(wanted));
+  if (found.length === 0) return null;
+  const tokens = new Map<string, TokenDecl>();
+  for (const rule of found) for (const [name, decl] of rule.tokens) tokens.set(name, decl);
+  return { tokens, within: found.map((rule) => rule.within) };
+}
+
+/** Throws when the file or a block the bundle names is not there. The system block may be absent:
+ *  whether that is a problem is the check's question, not the loader's. */
+async function readTokenBlocks(
+  bundle: Pick<TokenPairsBundle, "css" | "light" | "dark" | "system">,
+  root: string,
+): Promise<TokenBlocks> {
+  const css = await readFile(resolve(root, bundle.css), "utf8").catch(() => null);
+  // A stylesheet that does not load reads as one with no tokens, which would pass every rule
+  // below. It fails instead, the same reason `checkContrast` has a load rule.
+  if (css === null) throw new Error(`${bundle.css} could not be read`);
+  const rules = leafRules(css);
+  const required = (label: string, selector: string): TokenBlock => {
+    const block = blockOf(rules, selector);
+    if (block === null) {
+      throw new Error(
+        `${bundle.css} has no \`${selector}\` block for the ${label} colours. A block is found by ` +
+          `its selector text, inside any @media, and holds declarations only`,
+      );
+    }
+    return block;
+  };
+  const lightSelector = bundle.light ?? ":root";
+  if (selectorOf(lightSelector) === selectorOf(bundle.dark)) {
+    throw new Error(`the light and dark selectors are both \`${lightSelector}\`; they must differ`);
+  }
+  return {
+    light: required("light", lightSelector),
+    dark: required("dark", bundle.dark),
+    system: bundle.system === undefined ? null : blockOf(rules, bundle.system),
+  };
+}
+
+/** The tokens whose value is a hex colour, as `#rrggbb`. Type and geometry are left out. */
+function hexTokens(tokens: ReadonlyMap<string, TokenDecl>): Map<string, string> {
+  const hex = new Map<string, string>();
+  for (const [name, { value }] of tokens) {
+    const colour = normalizeHex(value);
+    if (colour !== null) hex.set(name, colour);
+  }
+  return hex;
+}
+
+/**
+ * The two palettes of a bundle as hex maps, for a check of your own that needs the colours
+ * (the browser's toolbar colour should be the page's ground, in each theme):
+ *
+ * ```ts
+ * const { light, dark } = await loadTokenThemes({ css: "src/tokens.css", dark: '[data-theme="dark"]' });
+ * light.get("--ground"); // "#ffffff"
+ * ```
+ *
+ * Throws, saying what is missing, when the file or one of the two blocks is not there.
+ */
+export async function loadTokenThemes(
+  bundle: Pick<TokenPairsBundle, "css" | "light" | "dark">,
+  options: CheckContrastOptions = {},
+): Promise<TokenThemes> {
+  const { light, dark } = await readTokenBlocks(bundle, options.root ?? process.cwd());
+  return { light: hexTokens(light.tokens), dark: hexTokens(dark.tokens) };
+}
+
+async function checkTokenBundle(
+  bundle: TokenPairsBundle,
+  options: CheckContrastOptions,
+  report: ContrastReport,
+): Promise<void> {
+  const problem = (p: Omit<ContrastProblem, "bundle" | "level">): void => {
+    report.problems.push({ bundle: bundle.name, level: "error", ...p });
+  };
+  const at = (decl: TokenDecl | undefined): string =>
+    decl === undefined ? bundle.css : `${bundle.css}:${String(decl.line)}`;
+
+  let blocks: TokenBlocks;
+  try {
+    blocks = await readTokenBlocks(bundle, options.root ?? process.cwd());
+  } catch (error) {
+    problem({ rule: "load", message: error instanceof Error ? error.message : String(error) });
+    return;
+  }
+  const { light, dark, system } = blocks;
+  const themes: Array<[mode: string, tokens: Map<string, TokenDecl>]> = [
+    ["light", light.tokens],
+    ["dark", dark.tokens],
+  ];
+  const textPairs = bundle.textPairs ?? [];
+  const nonTextPairs = bundle.nonTextPairs ?? [];
+
+  // ── Every colour has both themes, and every pair names a real token ──
+  const wanted = new Set([
+    ...hexTokens(light.tokens).keys(),
+    ...hexTokens(dark.tokens).keys(),
+    ...[...textPairs, ...nonTextPairs].flat(),
+  ]);
+  for (const token of wanted) {
+    const inLight = light.tokens.get(token);
+    const inDark = dark.tokens.get(token);
+    if (inLight !== undefined && inDark !== undefined) continue;
+    if (inLight === undefined && inDark === undefined) {
+      problem({
+        rule: "missing",
+        at: bundle.css,
+        message:
+          `a pair names \`${token}\`, which neither the light nor the dark block declares` +
+          (token.startsWith("--") ? "" : ". Custom property names start with --"),
+      });
+      continue;
+    }
+    const [have, lack] = inLight === undefined ? ["dark", "light"] : ["light", "dark"];
+    problem({
+      rule: "missing",
+      at: at(inLight ?? inDark),
+      message:
+        `\`${token}\` is in the ${have} block but not in the ${lack} block. Declare it in both, ` +
+        `even when the colour is the same, so each theme says what it means`,
+    });
+  }
+
+  // ── The pairs, on the values that ship in each theme ──
+  // A token missing from a theme was reported above, so its pairs are skipped here, not repeated.
+  const unmeasurable = new Set<string>();
+  const cannotMeasure = (mode: string, token: string, decl: TokenDecl): void => {
+    if (unmeasurable.has(`${mode}:${token}`)) return;
+    unmeasurable.add(`${mode}:${token}`);
+    problem({
+      rule: "floor",
+      at: at(decl),
+      message:
+        `${mode}: cannot measure ${token} (${decl.value}), because it is not a hex colour. ` +
+        `Keep the values hex, or teach this check the new notation; ` +
+        `do not let a pair go unmeasured.`,
+    });
+  };
+  const measure = (pairs: readonly TokenPair[], floor: number, why: string): void => {
+    for (const [background, foreground] of pairs) {
+      for (const [mode, tokens] of themes) {
+        const bg = tokens.get(background);
+        const fg = tokens.get(foreground);
+        if (bg === undefined || fg === undefined) continue;
+        const bgHex = normalizeHex(bg.value);
+        const fgHex = normalizeHex(fg.value);
+        if (bgHex === null || fgHex === null) {
+          if (bgHex === null) cannotMeasure(mode, background, bg);
+          if (fgHex === null) cannotMeasure(mode, foreground, fg);
+          continue;
+        }
+        const ratio = contrast(fgHex, bgHex);
+        if (ratio < floor) {
+          problem({
+            rule: "floor",
+            at: at(fg),
+            message:
+              `${mode}: ${foreground} (${fgHex}) on ${background} (${bgHex}) is ` +
+              `${ratio.toFixed(2)}:1, under the ${floor}:1 floor for ${why}`,
+          });
+        }
+      }
+    }
+  };
+  measure(textPairs, bundle.textFloor ?? 4.5, "text (WCAG 1.4.3)");
+  measure(nonTextPairs, bundle.nonTextFloor ?? 3, "a control or icon (WCAG 1.4.11)");
+
+  // ── The system fallback says what the dark block says ──
+  if (bundle.system === undefined) return;
+  const mirror = (decl: TokenDecl | undefined, message: string): void =>
+    problem({ rule: "mirror", at: at(decl), message });
+  if (system === null) {
+    mirror(
+      undefined,
+      `no \`${bundle.system}\` block for the system fallback. Without it a page that has ` +
+        `chosen no theme stays light on a dark system`,
+    );
+    return;
+  }
+  if (!system.within.every((within) => PREFERS_DARK.test(within))) {
+    mirror(
+      [...system.tokens.values()][0],
+      `\`${bundle.system}\` is not inside @media (prefers-color-scheme: dark), so it paints ` +
+        `the dark colours for everyone who has chosen no theme`,
+    );
+  }
+  for (const token of new Set([...dark.tokens.keys(), ...system.tokens.keys()])) {
+    const chosen = dark.tokens.get(token);
+    const followed = system.tokens.get(token);
+    if (chosen !== undefined && followed !== undefined) {
+      if (canonical(chosen.value) !== canonical(followed.value)) {
+        mirror(
+          followed,
+          `\`${token}\` is ${chosen.value} in the dark block but ${followed.value} in the system block`,
+        );
+      }
+    } else if (chosen !== undefined) {
+      mirror(chosen, `\`${token}\` is in the dark block but not in the system block`);
+    } else {
+      mirror(followed, `\`${token}\` is in the system block but not in the dark block`);
+    }
+  }
+}
+
+/**
+ * The plain-CSS gate: for each stylesheet, the contrast of every pair in both themes, a token
+ * both themes have, and a system fallback that matches the dark block. Returns what it found,
+ * the same report `checkContrast` returns, so `formatContrastReport` prints either and a repo
+ * can join the two (`report.problems.push(...other.problems)`) and fail CI once.
+ *
+ * ```ts
+ * const report = await checkTokenPairs([
+ *   { name: "site", css: "src/tokens.css", dark: ':root[data-theme="dark"]', textPairs: [["--ground", "--ink"]] },
+ * ]);
+ * console.log(formatContrastReport(report));
+ * ```
+ */
+export async function checkTokenPairs(
+  bundles: readonly TokenPairsBundle[],
+  options: CheckContrastOptions = {},
+): Promise<ContrastReport> {
+  const report: ContrastReport = { problems: [] };
+  for (const bundle of bundles) await checkTokenBundle(bundle, options, report);
+  return report;
+}