@7365admin1/layer-common 3.2.7 → 3.2.8-staging.201

package/utils/theme.test.ts

@@ -1,7 +1,9 @@
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { test } from "node:test";
 
-import { DARK_THEME, LIGHT_THEME } from "./theme.ts";
+import { DARK_THEME, LIGHT_THEME, PALETTE, type TPalette } from "./theme.ts";
+import { DARK_PAIRS, measure } from "./theme-aa-ledger.ts";
 
 /**
  * The dark theme was shipped once with `primary` chosen for the one place it
@@ -180,22 +182,498 @@ test("primary-button carries a white label in both themes", () => {
   assert.ok(contrast(WHITE, light["primary-button"]) >= 4.5);
 });
 
+/**
+ * `primary` is still a fill in a v-btn, a v-chip, a v-alert and a tab bar. The
+ * comment above `primary` used to claim Vuetify derives black for `on-primary`;
+ * it derives WHITE, and white on this blue is 2.68:1. Nothing measured it, so
+ * it shipped. This is that measurement.
+ */
+test("a filled primary surface carries a readable label in both themes", () => {
+  assert.equal(DARK_THEME.colors["on-primary"], dark.background);
+  assert.ok(contrast(dark["on-primary"], dark.primary) >= 4.5);
+  assert.ok(contrast(WHITE, dark.primary) < 4.5, "white here is the defect");
+
+  // Light derives its own and it passes; measure it rather than assume.
+  assert.ok(contrast(WHITE, light.primary) >= 4.5);
+});
+
 /**
  * Both themes correct the same two Vuetify defaults, and a value that drifts
  * apart between them is a bug nobody sees until they flip the switch.
  */
-test("disabled text clears 4.5:1 on the surface each theme puts it on", () => {
-  assert.equal(LIGHT_THEME.variables["disabled-opacity"], 0.55);
-  assert.equal(DARK_THEME.variables["disabled-opacity"], 0.55);
-  assert.ok(contrast(over("#000000", WHITE, 0.55), WHITE) >= 4.5);
+/**
+ * Both opacities are applied to `on-surface`, which is now the design's ink
+ * rather than pure black - so an opacity that was right for black is not right
+ * for this. These hold the corrected values in place, measured against the ink
+ * they are actually applied to.
+ */
+test("disabled text is no paler than it was before the palette changed", () => {
+  assert.equal(LIGHT_THEME.variables["disabled-opacity"], 0.62);
+  assert.equal(DARK_THEME.variables["disabled-opacity"], 0.62);
+
+  // The bar is the previous rendering, not 4.5: Vuetify multiplies its own
+  // field alpha on top of this, which is Phase 3's problem to unpick.
+  const wasLight = contrast(over("#000000", WHITE, 0.55), WHITE);
+  const nowLight = contrast(over(PALETTE.light.text, WHITE, 0.62), WHITE);
   assert.ok(
-    contrast(over(WHITE, dark.background, 0.55), dark.background) >= 4.5
+    nowLight >= wasLight,
+    `disabled light went backwards: ${wasLight.toFixed(2)} -> ${nowLight.toFixed(2)}`
+  );
+
+  const nowDark = contrast(
+    over(PALETTE.dark.text, PALETTE.dark.card, 0.62),
+    PALETTE.dark.card
   );
+  assert.ok(nowDark >= 4.5, `disabled dark: ${nowDark.toFixed(2)}`);
+});
+
+/**
+ * THE REGRESSION THIS CAUGHT. `text-medium-emphasis` is `on-surface` at this
+ * opacity, and it is roughly two hundred lines of secondary text across eleven
+ * applications. At Vuetify's 0.6 the new ink lands at 4.41:1 on the page.
+ */
+test("medium-emphasis text clears AA on every surface, in both themes", () => {
+  for (const [name, p] of [
+    ["light", PALETTE.light],
+    ["dark", PALETTE.dark],
+  ] as const) {
+    const alpha = (name === "light" ? LIGHT_THEME : DARK_THEME).variables[
+      "medium-emphasis-opacity"
+    ];
+
+    for (const bg of [p.card, p.bg, p.sidebar]) {
+      const ratio = contrast(over(p.text, bg, alpha), bg);
+      assert.ok(
+        ratio >= 4.5,
+        `${name} medium emphasis on ${bg}: ${ratio.toFixed(2)} at alpha ${alpha}`
+      );
+    }
+  }
 });
 
 test("the dark divider clears the 3:1 a boundary wants", () => {
-  const border = "#62666a"; // white at 0.35 over the dark page
+  // Derived, not hardcoded: this used to be a literal "#62666a" with a comment
+  // saying it was white at 0.35 over the dark page, and it stopped being that
+  // the moment the page colour moved.
+  const border = over(WHITE, dark.background, 0.35);
 
   assert.equal(DARK_THEME.variables["border-opacity"], 0.35);
   assert.ok(contrast(border, dark.background) >= 3);
 });
+
+/* ==================================================================== */
+/* THE REDESIGN PALETTE.                                                */
+/*                                                                      */
+/* The owner's decision on 2026-08-14 is 100% DESIGN FIDELITY over WCAG */
+/* AA, reversing 2026-08-13's "minimal darkening". So the two themes    */
+/* are now held to two different standards, on purpose:                 */
+/*                                                                      */
+/*   DARK  - exact as handed over AND fully AA. Asserted below.         */
+/*   LIGHT - exact as handed over, 16 of 22 read pairs BELOW AA. Not    */
+/*           asserted as passing; every ratio is PINNED to its measured */
+/*           value in `utils/theme-aa-ledger.ts` instead, so the cost is */
+/*           recorded rather than hidden and any drift - lighter OR     */
+/*           darker - still fails the build and has to be declared.     */
+/*                                                                      */
+/* A later phase that "tidies" a light colour to make a contrast test   */
+/* green is exactly what the ledger test is here to catch.              */
+/* ==================================================================== */
+
+const L = PALETTE.light;
+const D = PALETTE.dark;
+
+/** The soft chip backgrounds, as the design states them - literally. */
+const SOFT = {
+  light: {
+    ok: ["#0f8a62", 0.1],
+    warn: ["#be8c19", 0.13],
+    err: ["#cf4b4b", 0.1],
+    info: ["#3b6fd4", 0.1],
+  },
+  dark: {
+    ok: ["#41c795", 0.12],
+    warn: ["#dcaf4e", 0.13],
+    err: ["#e57373", 0.12],
+    info: ["#7da6ec", 0.12],
+  },
+} as const;
+
+/** `--thead` is a 2% ink wash over the card, not a colour of its own. */
+const thead = (p: TPalette) =>
+  over(p === L ? "#14161a" : WHITE, p.card, 0.02);
+
+const soft = (p: TPalette, key: "ok" | "warn" | "err" | "info", on: string) => {
+  const [hex, alpha] = SOFT[p === L ? "light" : "dark"][key];
+  return over(hex, on, alpha);
+};
+
+const accentSoft = (p: TPalette, on: string) => over(p.accent, on, 0.12);
+
+/*
+ * DARK ONLY. The light theme is measured by the ledger test further down, not
+ * asserted here - see the section note above.
+ */
+for (const [name, p] of [["dark", D]] as const) {
+  /**
+   * `--muted` is the table header of every table in the product, the
+   * breadcrumb, and every KPI sub-line. The dark theme's `#868c98` clears AA
+   * on all four of its surfaces as designed; the light theme's `#8b8f98` does
+   * not, at 2.99-3.24:1, and that is the ledger's headline entry.
+   */
+  test(`${name}: muted text is readable on every surface it is used on`, () => {
+    for (const [where, bg] of [
+      ["a card", p.card],
+      ["the page", p.bg],
+      ["a table header", thead(p)],
+      ["the sidebar", p.sidebar],
+    ] as const) {
+      assert.ok(
+        contrast(p.muted, bg) >= 4.5,
+        `${name} muted on ${where}: ${contrast(p.muted, bg).toFixed(2)}`
+      );
+    }
+  });
+
+  test(`${name}: primary and secondary text clear AA on every surface`, () => {
+    for (const fg of [p.text, p.text2]) {
+      for (const bg of [p.card, p.bg, p.sidebar]) {
+        assert.ok(
+          contrast(fg, bg) >= 4.5,
+          `${name} ${fg} on ${bg}: ${contrast(fg, bg).toFixed(2)}`
+        );
+      }
+    }
+  });
+
+  /**
+   * A status chip is its own soft background, so the label is NOT read on the
+   * card - measuring it against white flatters it by about half a point.
+   */
+  test(`${name}: every status chip's label is readable on its own chip`, () => {
+    for (const [key, fg] of [
+      ["ok", p.ok],
+      ["warn", p.warn],
+      ["err", p.err],
+      ["info", p.info],
+    ] as const) {
+      const bg = soft(p, key, p.card);
+      assert.ok(
+        contrast(fg, bg) >= 4.5,
+        `${name} ${key} chip: ${contrast(fg, bg).toFixed(2)}`
+      );
+    }
+  });
+
+  /** The same four also appear as bare text: status dots, chart labels, the
+   *  red Logout row in the profile dropdown. */
+  test(`${name}: the status colours are readable as plain text on a card`, () => {
+    for (const fg of [p.ok, p.warn, p.err, p.info]) {
+      assert.ok(
+        contrast(fg, p.card) >= 4.5,
+        `${name} ${fg} on a card: ${contrast(fg, p.card).toFixed(2)}`
+      );
+    }
+  });
+
+  /**
+   * The active sidebar item is `--accent-text` on `--accent-soft`, and
+   * `--accent-soft` is transparent - so it takes the colour of whatever is
+   * behind it. Behind it is the SIDEBAR, which is not the card. Solving this
+   * against the card gives 4.50:1 and ships a 4.35:1 sidebar.
+   */
+  test(`${name}: accent text is readable on accent-soft over BOTH surfaces`, () => {
+    for (const [where, under] of [
+      ["the sidebar", p.sidebar],
+      ["a card", p.card],
+    ] as const) {
+      const bg = accentSoft(p, under);
+      assert.ok(
+        contrast(p.accentText, bg) >= 4.5,
+        `${name} accent-text on accent-soft over ${where}: ${contrast(
+          p.accentText,
+          bg
+        ).toFixed(2)}`
+      );
+    }
+
+    assert.ok(contrast(p.accentText, p.card) >= 4.5, "as a plain link");
+  });
+
+  /**
+   * THE REASON `--accent-strong` EXISTS. If someone deletes it and points the
+   * primary button back at `--accent`, the second assertion is what fails, and
+   * the message says why rather than just reporting a number.
+   */
+  test(`${name}: a white label sits on accent-strong, never on accent`, () => {
+    assert.ok(
+      contrast(WHITE, p.accentStrong) >= 4.5,
+      `white on accent-strong: ${contrast(WHITE, p.accentStrong).toFixed(2)}`
+    );
+    assert.ok(
+      contrast(WHITE, p.accent) < 4.5,
+      "white on --accent passes now? then --accent-strong is redundant - " +
+        "re-measure before deleting it"
+    );
+    // The fill still has to be findable against the card it sits on.
+    assert.ok(
+      contrast(p.accentStrong, p.card) >= 3,
+      `accent-strong against a card: ${contrast(p.accentStrong, p.card).toFixed(2)}`
+    );
+  });
+
+  /** Non-text uses of the accent only owe 3:1, and they keep the design value. */
+  test(`${name}: the accent clears 3:1 where it is a line rather than a word`, () => {
+    assert.ok(contrast(p.accent, p.card) >= 3, "chart line / tab underline");
+    assert.ok(contrast(WHITE, p.accent) >= 3, "the toggle knob on its on state");
+  });
+
+  /**
+   * Vuetify DERIVES the label on a filled colour and its derivation picks
+   * white, which on the dark palette is 2.04:1 to 2.99:1. Every one is set
+   * explicitly in `theme.ts`; this is what proves they were all set.
+   */
+  test(`${name}: every filled semantic colour carries a readable label`, () => {
+    const t = p === L ? LIGHT_THEME : DARK_THEME;
+
+    for (const key of ["primary", "success", "warning", "error", "info"]) {
+      const on = (t.colors as Record<string, string>)[`on-${key}`];
+      const fill = (t.colors as Record<string, string>)[key];
+
+      assert.ok(on, `on-${key} is not set - Vuetify would guess, and it guesses white`);
+      assert.ok(
+        contrast(on, fill) >= 4.5,
+        `${name} on-${key}: ${contrast(on, fill).toFixed(2)}`
+      );
+    }
+
+    assert.ok(
+      contrast(t.colors["on-primary-button"], t.colors["primary-button"]) >= 4.5
+    );
+  });
+}
+
+/**
+ * "KEEP THE LOOK" IS HALF THE INSTRUCTION, AND IT IS THE HALF A CONTRAST TEST
+ * CANNOT CATCH ON ITS OWN - darkening everything until it passes would satisfy
+ * every test above and would not be the design. These are the values that were
+ * NOT the problem, pinned to what the handoff says.
+ */
+test("the design's own values are unchanged wherever they already passed", () => {
+  assert.equal(L.accent, "#5b8def", "the brand accent is the design's, exactly");
+  assert.equal(D.accent, "#5b8def");
+
+  assert.equal(L.bg, "#f6f6f2");
+  assert.equal(L.sidebar, "#fbfbf8");
+  assert.equal(L.card, "#ffffff");
+  assert.equal(L.border, "#e8e8e1");
+  assert.equal(L.text, "#191b1f");
+  assert.equal(L.text2, "#41454d");
+
+  // The dark theme passed AA as designed and therefore moves nowhere at all.
+  assert.deepEqual(
+    [D.bg, D.sidebar, D.card, D.border, D.text, D.text2, D.muted],
+    ["#131418", "#17181d", "#1c1e24", "#2a2d35", "#eef0f3", "#c6cad2", "#868c98"],
+    "the dark palette needed no darkening - it should still be the handoff's"
+  );
+  assert.deepEqual(
+    [D.ok, D.warn, D.err, D.info, D.accentText],
+    ["#41c795", "#dcaf4e", "#e57373", "#7da6ec", "#78a2f4"]
+  );
+});
+
+/**
+ * THE SIX THAT WERE DARKENED ON 2026-08-13 ARE BACK ON THE HANDOFF, EXACTLY.
+ * Hex equality, not a tolerance: "design-exact" has no tolerance.
+ */
+test("the light palette is the handoff's, value for value", () => {
+  assert.equal(L.muted, "#8b8f98");
+  assert.equal(L.ok, "#0e7c58");
+  assert.equal(L.warn, "#8e6611");
+  assert.equal(L.err, "#bc4444");
+  assert.equal(L.info, "#3b6fd4");
+  // `color-mix(in oklab, #5b8def 75%, #191b1f)`, resolved in a browser.
+  assert.equal(L.accentText, "#4a6eb6");
+});
+
+/**
+ * THE LEDGER. The light theme's known sub-AA pairs, each pinned to the ratio it
+ * actually measures. This is the "recorded, not hidden" half of the owner's
+ * decision: nobody can quietly darken a value to make a test green, and nobody
+ * can lighten one further without this failing and making them write it down.
+ *
+ * The numbers come from `utils/theme-aa-ledger.ts`, which is also runnable:
+ *   node --experimental-strip-types utils/theme-aa-ledger.ts
+ */
+test("the light theme's sub-AA pairs measure exactly what the ledger says", () => {
+  const EXPECTED: Record<string, number> = {
+    "muted on a card (KPI sub-lines, field labels)": 3.24,
+    "muted on the page background": 2.99,
+    "muted on the sidebar": 3.13,
+    "muted on a disabled control's hover fill": 2.71,
+    "ok label on its own chip": 4.57,
+    "warn label on its own chip": 4.56,
+    "err label on its own chip": 4.55,
+    "info label on its own chip": 4.2,
+    "ok as plain text on a card": 5.19,
+    "warn as plain text on a card": 5.17,
+    "err as plain text on a card (the Logout row)": 5.19,
+    "info as plain text on a card": 4.76,
+    "accent-text as a link on a card": 5,
+    "accent-text on accent-soft over the sidebar (active nav item)": 4.29,
+    "accent-text on accent-soft over a card (active tab, avatar initials)": 4.42,
+    "white on the filled success colour": 5.19,
+    "white on the filled warning colour": 5.17,
+    "white on the filled error colour": 5.19,
+    "white on the filled info colour": 4.76,
+    "white on primary-button (accent-strong) - NOT reverted": 4.57,
+    "text on a card": 17.24,
+    "text2 on a card": 9.62,
+  };
+
+  const measured = measure();
+  assert.equal(
+    measured.length,
+    Object.keys(EXPECTED).length,
+    "a pair was added to or removed from the ledger without updating this test"
+  );
+
+  for (const row of measured) {
+    assert.equal(
+      row.ratio,
+      EXPECTED[row.what],
+      `${row.what}: ledger says ${EXPECTED[row.what]}:1, measured ${row.ratio}:1`
+    );
+  }
+
+  const failing = measured.filter((r) => !r.passes).length;
+  assert.equal(
+    failing,
+    7,
+    `${failing} light pairs are below AA; the recorded, accepted count is 7. ` +
+      "If this moved, the owner's design-fidelity decision needs re-stating."
+  );
+});
+
+/** The dark theme carries no such debt, and that is worth asserting out loud. */
+test("the dark theme has no sub-AA pairs at all", () => {
+  const bad = DARK_PAIRS().filter((r) => !r.passes);
+  assert.deepEqual(bad, [], "dark mode was exact AND compliant - keep it that way");
+});
+
+/* ------------------------------------------------------------------ */
+/* The two contrast fixes QA drove, asserted at the token level AND at  */
+/* the stylesheet that wires them.                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A native `<select>`'s option list is painted by the browser. With no
+ * background of its own the option keeps the theme's ink over whatever the
+ * browser paints - white on Windows/Chrome - which is 1.14:1 in dark mode.
+ * The rule gives it `--card`/`--text`, the same pair the themed popover uses.
+ */
+test("a native option's own fill carries the theme ink in both themes", () => {
+  for (const [name, p] of [["light", PALETTE.light], ["dark", PALETTE.dark]] as const) {
+    assert.ok(
+      contrast(p.text, p.card) >= 4.5,
+      `${name}: option ink on the card fill is ${contrast(p.text, p.card).toFixed(2)}:1`
+    );
+  }
+
+  // What the defect measured, so the number stays on the record.
+  assert.equal(Number(contrast(PALETTE.dark.text, "#ffffff").toFixed(2)), 1.14);
+});
+
+/**
+ * The table header. `--muted` measured 3.10:1 on the header band in light -
+ * below AA and reported by two apps' QA. `--text2` clears AA in both themes
+ * while staying clearly below the primary ink the data rows use, so the
+ * header still reads as secondary to the data.
+ */
+test("the table header clears AA and still reads below the data", () => {
+  for (const [name, p, wash] of [
+    ["light", PALETTE.light, "#14161a"],
+    ["dark", PALETTE.dark, "#ffffff"],
+  ] as const) {
+    const band = over(wash, p.card, 0.02);
+    const header = contrast(p.text2, band);
+    const data = contrast(p.text, band);
+
+    assert.ok(header >= 4.5, `${name}: header is ${header.toFixed(2)}:1, below AA`);
+    assert.ok(
+      header < data,
+      `${name}: the header (${header.toFixed(2)}:1) must stay below the data ` +
+        `(${data.toFixed(2)}:1) or it stops reading as secondary`
+    );
+    assert.ok(
+      contrast(p.muted, band) < header,
+      `${name}: --text2 must be an improvement on the --muted it replaced`
+    );
+  }
+});
+
+/**
+ * The ratios above are the tokens'. They say nothing about whether the CSS
+ * still ASKS for them - a deleted rule would leave every number here passing.
+ * These two assertions are the wiring. Neither can measure a real computed
+ * style: that needs a browser, and the measured evidence for it is in the PR.
+ */
+test("the stylesheets still ask for the tokens the two fixes chose", () => {
+  const css = (f: string) =>
+    readFileSync(new URL(`../assets/css/${f}`, import.meta.url), "utf8")
+      .replace(/\/\*[\s\S]*?\*\//g, "");
+
+  const primitives = css("primitives.css");
+  const optionRule = primitives.slice(primitives.indexOf("select option {"));
+  assert.ok(
+    primitives.includes("select option {"),
+    "the native <option> fill rule is gone - dark mode goes back to 1.14:1"
+  );
+  const optionBody = optionRule.slice(0, optionRule.indexOf("}"));
+  assert.ok(
+    optionBody.includes("background-color: var(--card)"),
+    "the option lost its own fill, which is the whole defect"
+  );
+  assert.ok(optionBody.includes("color: var(--text)"), "the option lost its ink");
+
+  const screens = css("screens.css");
+  const header = screens.slice(screens.indexOf(".table-card thead th {"));
+  const headerBody = header.slice(0, header.indexOf("}"));
+  assert.ok(
+    headerBody.includes("color: var(--text2) !important"),
+    "the table header is back on a token that does not clear AA in light"
+  );
+});
+
+/**
+ * THE BRIDGE. Every design token in `assets/css/tokens.css` is an alias onto a
+ * `--v-theme-*`, so a token whose Vuetify colour does not exist resolves to
+ * nothing and paints transparent - silently, in eleven applications. This is
+ * the list that CSS file reads.
+ */
+test("every design token has a Vuetify colour behind it, in both themes", () => {
+  const required = [
+    "background", "surface", "sidebar", "border",
+    "text-primary", "text2", "muted",
+    "success", "warning", "error", "info",
+    "accent", "accent-strong", "accent-text",
+    "primary", "primary-button", "brand-surface",
+  ];
+
+  for (const [name, t] of [["light", LIGHT_THEME], ["dark", DARK_THEME]] as const) {
+    for (const key of required) {
+      const value = (t.colors as Record<string, string>)[key];
+      assert.match(
+        value ?? "",
+        /^#[0-9a-f]{6}$/i,
+        `${name} is missing a usable colour for "${key}" - tokens.css aliases it`
+      );
+    }
+  }
+
+  assert.deepEqual(
+    Object.keys(LIGHT_THEME.colors),
+    Object.keys(DARK_THEME.colors),
+    "a colour wired into one theme and forgotten in the other is how this " +
+      "file broke before"
+  );
+});