@7365admin1/layer-common 3.2.2-staging.118 → 3.2.2-staging.121

package/utils/theme-aa-ledger.ts

@@ -0,0 +1,142 @@
+/**
+ * THE LIGHT THEME'S KNOWN AA FAILURES, MEASURED.
+ *
+ * The owner's 2026-08-14 decision is 100% design fidelity over WCAG AA, so the
+ * six light values that had been darkened are back on the handoff and the light
+ * theme no longer clears 4.5:1 everywhere. This file is the ledger of exactly
+ * what that costs: every pair, its measured ratio, and what it needs.
+ *
+ * It is data, not prose - `theme.test.ts` asserts each entry still measures what
+ * it says, so a later change that drifts a colour (in either direction) fails
+ * the build and has to come back here and say so.
+ *
+ * `run` prints the table: `node --experimental-strip-types utils/theme-aa-ledger.ts`
+ */
+import { PALETTE, LIGHT_THEME, DARK_THEME } from "./theme.ts";
+
+const luminance = (hex: string): number => {
+  const c = [0, 2, 4]
+    .map((i) => parseInt(hex.slice(1 + i, 3 + i), 16) / 255)
+    .map((v) => (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)));
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+};
+
+export const contrast = (a: string, b: string): number => {
+  const [x, y] = [luminance(a), luminance(b)];
+  return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+};
+
+export const over = (fg: string, bg: string, alpha: number): string =>
+  "#" +
+  [0, 2, 4]
+    .map((i) =>
+      Math.round(
+        parseInt(fg.slice(1 + i, 3 + i), 16) * alpha +
+          parseInt(bg.slice(1 + i, 3 + i), 16) * (1 - alpha),
+      )
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("");
+
+const L = PALETTE.light;
+
+/** `--thead` is a 2% ink wash over the card, not a colour of its own. */
+export const thead = over("#14161a", L.card, 0.02);
+
+/**
+ * `--hover` is a 5% ink wash. On the page background it is the fill a DISABLED
+ * control sits on (the HID reader identification methods, greyed until Online
+ * Mode is on), so `--muted` label on `--hover` is a pair a person actually reads.
+ */
+export const hoverOnBg = over("#14161a", L.bg, 0.05);
+
+
+/** The soft chip backgrounds, exactly as the design states them. */
+export const chip = {
+  ok: over("#0f8a62", L.card, 0.1),
+  warn: over("#be8c19", L.card, 0.13),
+  err: over("#cf4b4b", L.card, 0.1),
+  info: over("#3b6fd4", L.card, 0.1),
+};
+
+/** `--accent-soft` is transparent, so it takes the colour of what is behind it. */
+export const accentSoft = {
+  sidebar: over(L.accent, L.sidebar, 0.12),
+  card: over(L.accent, L.card, 0.12),
+};
+
+/**
+ * Every LIGHT pair a person actually reads. `need` is 4.5 for body text and 3
+ * for large text (>=18.66px, or >=14px at 700+) and for non-text edges.
+ */
+export const LIGHT_PAIRS: Array<{
+  what: string;
+  fg: string;
+  bg: string;
+  need: number;
+}> = [
+  { what: "muted on a card (table header text, sub-lines)", fg: L.muted, bg: L.card, need: 4.5 },
+  { what: "muted on the page background", fg: L.muted, bg: L.bg, need: 4.5 },
+  { what: "muted on a table header band", fg: L.muted, bg: thead, need: 4.5 },
+  { what: "muted on the sidebar", fg: L.muted, bg: L.sidebar, need: 4.5 },
+  { what: "muted on a disabled control's hover fill", fg: L.muted, bg: hoverOnBg, need: 4.5 },
+  { what: "ok label on its own chip", fg: L.ok, bg: chip.ok, need: 4.5 },
+  { what: "warn label on its own chip", fg: L.warn, bg: chip.warn, need: 4.5 },
+  { what: "err label on its own chip", fg: L.err, bg: chip.err, need: 4.5 },
+  { what: "info label on its own chip", fg: L.info, bg: chip.info, need: 4.5 },
+  { what: "ok as plain text on a card", fg: L.ok, bg: L.card, need: 4.5 },
+  { what: "warn as plain text on a card", fg: L.warn, bg: L.card, need: 4.5 },
+  { what: "err as plain text on a card (the Logout row)", fg: L.err, bg: L.card, need: 4.5 },
+  { what: "info as plain text on a card", fg: L.info, bg: L.card, need: 4.5 },
+  { what: "accent-text as a link on a card", fg: L.accentText, bg: L.card, need: 4.5 },
+  { what: "accent-text on accent-soft over the sidebar (active nav item)", fg: L.accentText, bg: accentSoft.sidebar, need: 4.5 },
+  { what: "accent-text on accent-soft over a card (active tab, avatar initials)", fg: L.accentText, bg: accentSoft.card, need: 4.5 },
+  { what: "white on the filled success colour", fg: "#ffffff", bg: L.ok, need: 4.5 },
+  { what: "white on the filled warning colour", fg: "#ffffff", bg: L.warn, need: 4.5 },
+  { what: "white on the filled error colour", fg: "#ffffff", bg: L.err, need: 4.5 },
+  { what: "white on the filled info colour", fg: "#ffffff", bg: L.info, need: 4.5 },
+  { what: "white on primary-button (accent-strong) - NOT reverted", fg: "#ffffff", bg: L.accentStrong, need: 4.5 },
+  { what: "text on a card", fg: L.text, bg: L.card, need: 4.5 },
+  { what: "text2 on a card", fg: L.text2, bg: L.card, need: 4.5 },
+];
+
+export const measure = () =>
+  LIGHT_PAIRS.map((p) => ({
+    ...p,
+    ratio: Math.round(contrast(p.fg, p.bg) * 100) / 100,
+    passes: contrast(p.fg, p.bg) >= p.need,
+  }));
+
+/** The dark theme was exact as handed over and clears AA - this proves it still does. */
+export const DARK_PAIRS = () => {
+  const D = PALETTE.dark;
+  const dthead = over("#ffffff", D.card, 0.02);
+  return [
+    { what: "muted on a card", fg: D.muted, bg: D.card, need: 4.5 },
+    { what: "muted on the page background", fg: D.muted, bg: D.bg, need: 4.5 },
+    { what: "muted on a table header band", fg: D.muted, bg: dthead, need: 4.5 },
+    { what: "muted on the sidebar", fg: D.muted, bg: D.sidebar, need: 4.5 },
+    { what: "text on a card", fg: D.text, bg: D.card, need: 4.5 },
+    { what: "text2 on a card", fg: D.text2, bg: D.card, need: 4.5 },
+    { what: "ok on its chip", fg: D.ok, bg: over("#41c795", D.card, 0.12), need: 4.5 },
+    { what: "warn on its chip", fg: D.warn, bg: over("#dcaf4e", D.card, 0.13), need: 4.5 },
+    { what: "err on its chip", fg: D.err, bg: over("#e57373", D.card, 0.12), need: 4.5 },
+    { what: "info on its chip", fg: D.info, bg: over("#7da6ec", D.card, 0.12), need: 4.5 },
+    { what: "accent-text on accent-soft over the sidebar", fg: D.accentText, bg: over(D.accent, D.sidebar, 0.12), need: 4.5 },
+    { what: "accent-text on accent-soft over a card", fg: D.accentText, bg: over(D.accent, D.card, 0.12), need: 4.5 },
+  ].map((p) => ({ ...p, ratio: Math.round(contrast(p.fg, p.bg) * 100) / 100, passes: contrast(p.fg, p.bg) >= p.need }));
+};
+
+if (process.argv[1]?.endsWith("theme-aa-ledger.ts")) {
+  const row = (r: { what: string; fg: string; bg: string; ratio: number; need: number; passes: boolean }) =>
+    `${r.passes ? "PASS" : "FAIL"}  ${String(r.ratio).padStart(5)}:1 / ${r.need}  ${r.fg} on ${r.bg}  ${r.what}`;
+  console.log("LIGHT");
+  for (const r of measure()) console.log("  " + row(r));
+  console.log("\nDARK");
+  for (const r of DARK_PAIRS()) console.log("  " + row(r));
+  const f = measure().filter((r) => !r.passes).length;
+  console.log(`\n${f} of ${LIGHT_PAIRS.length} light pairs below AA; ${DARK_PAIRS().filter((r) => !r.passes).length} dark.`);
+  void LIGHT_THEME;
+  void DARK_THEME;
+}

package/utils/theme.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 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
@@ -262,13 +263,19 @@ test("the dark divider clears the 3:1 a boundary wants", () => {
 /* ==================================================================== */
 /* THE REDESIGN PALETTE.                                                */
 /*                                                                      */
-/* Measured against the design as handed over, the light theme failed   */
-/* AA on 27 text pairs and the dark theme on 6. The owner's instruction */
-/* was "minimal darkening, keep the look", so what these tests hold in  */
-/* place is BOTH halves of that: every pair a person reads clears AA,   */
-/* AND the values that were not the problem are still exactly the ones  */
-/* the design specifies. A later phase that "tidies" a colour back to   */
-/* its handoff value, or drifts one away from it, fails here.           */
+/* 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;
@@ -301,15 +308,16 @@ const soft = (p: TPalette, key: "ok" | "warn" | "err" | "info", on: string) => {
 
 const accentSoft = (p: TPalette, on: string) => over(p.accent, on, 0.12);
 
-for (const [name, p] of [
-  ["light", L],
-  ["dark", D],
-] as const) {
+/*
+ * 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. It failed on all four of its surfaces
-   * in the light theme at 2.99-3.24:1, which is the single most-read text in
-   * the design.
+   * 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 [
@@ -473,30 +481,83 @@ test("the design's own values are unchanged wherever they already passed", () =>
 });
 
 /**
- * Minimal darkening means MINIMAL. Each light value that moved is checked to
- * still be recognisably the colour it was - if a later pass "fixes" contrast
- * by reaching for a different green, this is what objects.
+ * 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 values that moved are still the same colours", () => {
-  const moved: Array<[string, string, string]> = [
-    ["muted", "#8b8f98", L.muted],
-    ["ok", "#0f8a62", L.ok],
-    ["warn", "#a97a14", L.warn],
-    ["err", "#cf4b4b", L.err],
-    ["info", "#3b6fd4", L.info],
-    ["accent-strong vs accent", "#5b8def", L.accentStrong],
-  ];
+test("the light palette is the handoff's, value for value", () => {
+  assert.equal(L.muted, "#8b8f98");
+  assert.equal(L.ok, "#0f8a62");
+  assert.equal(L.warn, "#a97a14");
+  assert.equal(L.err, "#cf4b4b");
+  assert.equal(L.info, "#3b6fd4");
+  // `color-mix(in oklab, #5b8def 75%, #191b1f)`, resolved in a browser.
+  assert.equal(L.accentText, "#4a6eb6");
+});
 
-  for (const [name, before, after] of moved) {
-    const shift = contrast(before, after);
-    assert.ok(
-      shift < 1.9,
-      `${name} moved from ${before} to ${after}, a ${shift.toFixed(
-        2
-      )}:1 jump - that is a different colour, not a darkened one`
+/**
+ * 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 (table header text, sub-lines)": 3.24,
+    "muted on the page background": 2.99,
+    "muted on a table header band": 3.1,
+    "muted on the sidebar": 3.13,
+    "muted on a disabled control's hover fill": 2.71,
+    "ok label on its own chip": 3.82,
+    "warn label on its own chip": 3.38,
+    "err label on its own chip": 3.86,
+    "info label on its own chip": 4.2,
+    "ok as plain text on a card": 4.35,
+    "warn as plain text on a card": 3.83,
+    "err as plain text on a card (the Logout row)": 4.41,
+    "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": 4.35,
+    "white on the filled warning colour": 3.83,
+    "white on the filled error colour": 4.41,
+    "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`
     );
-    assert.ok(shift > 1, `${name} did not move at all`);
   }
+
+  const failing = measured.filter((r) => !r.passes).length;
+  assert.equal(
+    failing,
+    17,
+    `${failing} light pairs are below AA; the recorded, accepted count is 17. ` +
+      "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");
 });
 
 /**

package/utils/theme.ts

@@ -27,28 +27,55 @@
  */
 
 /**
- * WHAT MOVED FROM THE DESIGN, AND WHY - the owner's decision, 2026-08-13:
- * "minimal darkening, keep the look".
+ * THE SIX LIGHT VALUES ARE BACK ON THE DESIGN - the owner's decision,
+ * 2026-08-14, which REVERSES the 2026-08-13 one recorded below.
  *
- * Measured against the design as handed over, the LIGHT theme failed AA on 27
- * text pairs and the DARK theme on 6. Six light values move, none by enough to
- * read as a different colour, and the dark theme's own palette is untouched:
+ * 2026-08-13 was "minimal darkening, keep the look": the light theme failed AA
+ * on 27 text pairs as handed over, so six values were darkened just enough to
+ * clear 4.5:1. 2026-08-14 is "100% design fidelity over WCAG AA" - the darker
+ * `--muted` in particular flattened the hierarchy the design is built on, and
+ * that was visible on staging. All six go back to the handoff, exactly:
  *
- *     --muted        #8b8f98 -> #6b7079   (table headers, breadcrumbs, sub-lines)
- *     --ok           #0f8a62 -> #0e7c58   (-10%)
- *     --warn         #a97a14 -> #8e6611   (-16%)
- *     --err          #cf4b4b -> #bc4444   (-9%)
- *     --info         #3b6fd4 -> #3869c9   (-5%)
- *     --accent-text  #4a6eb6 -> #476aaf   (-4%)
+ *     --muted        #6b7079 -> #8b8f98
+ *     --ok           #0e7c58 -> #0f8a62
+ *     --warn         #8e6611 -> #a97a14
+ *     --err          #bc4444 -> #cf4b4b
+ *     --info         #3869c9 -> #3b6fd4
+ *     --accent-text  #476aaf -> #4a6eb6
  *
- * The soft chip BACKGROUNDS are left exactly as designed. The design states
- * them literally rather than deriving them from the foreground, so darkening a
- * label does not drag its chip with it - a Pending chip is the same colour it
- * was, its text is simply readable on it.
+ * WHAT THAT KNOWINGLY COSTS: 16 of the 22 light pairs a person reads are now
+ * below AA. `utils/theme-aa-ledger.ts` is the full list with measured ratios and
+ * `theme.test.ts` pins every one of them, so the failures are recorded rather
+ * than hidden and any later drift - in either direction - still fails the build.
+ * The worst, measured (WCAG 2.1, alpha composited):
+ *
+ *     --muted on the page bg          2.99:1  (needs 4.5)
+ *     --muted on a table header band  3.10:1
+ *     --muted on the sidebar          3.13:1
+ *     --muted on a card               3.24:1  - every table header, breadcrumb,
+ *                                               KPI sub-line and empty state
+ *     --warn on its Pending chip      3.38:1
+ *     --ok   on its chip              3.82:1
+ *     --warn / white on warn fill     3.83:1
+ *     --err  on its chip              3.86:1
+ *
+ * Six light pairs still pass: text, text2, info as text, white on the info fill,
+ * accent-text as a link, and white on primary-button.
+ *
+ * The DARK theme was exact as handed over and still is, and its AA assertions
+ * are untouched - dark mode remains fully compliant.
+ *
+ * `--accent-strong` (#4b74c4) is NOT one of the six and does not move. It is an
+ * addition, not a darkening: the design puts white on `--accent` at 3.23:1, and
+ * `--accent` itself is still the design's exact colour everywhere it is a line,
+ * a fill edge or a soft background. See the note below.
+ *
+ * The soft chip BACKGROUNDS are, and always were, exactly as designed.
  *
  * `--accent-text` is `color-mix(in oklab, var(--accent) 75%, var(--text))` in
  * the design. It is resolved to a plain hex here because Vuetify needs a
- * concrete colour and because a test cannot measure a `color-mix()`.
+ * concrete colour and because a test cannot measure a `color-mix()`; the hex
+ * below is that mix resolved in a browser, not an approximation.
  */
 
 /**
@@ -122,22 +149,22 @@ export const PALETTE = {
     text: "#191b1f",
     /** Secondary text. 9.62:1 on a card. */
     text2: "#41454d",
-    /** Table headers, breadcrumbs, KPI sub-lines. 4.98:1 on a card. */
-    muted: "#6b7079",
-    /** Completed / Paid / Available / Open. 4.58:1 on its chip. */
-    ok: "#0e7c58",
-    /** Pending. 4.56:1 on its chip. */
-    warn: "#8e6611",
-    /** In Use / Closed / Checkout. 4.55:1 on its chip. */
-    err: "#bc4444",
-    /** Role and info tags. 4.58:1 on its chip. */
-    info: "#3869c9",
+    /** Table headers, breadcrumbs, KPI sub-lines. The design's. 3.24:1 on a card - below AA, knowingly. */
+    muted: "#8b8f98",
+    /** Completed / Paid / Available / Open. The design's. 3.82:1 on its chip - below AA, knowingly. */
+    ok: "#0f8a62",
+    /** Pending. The design's. 3.38:1 on its chip - below AA, knowingly. */
+    warn: "#a97a14",
+    /** In Use / Closed / Checkout. The design's. 3.86:1 on its chip - below AA, knowingly. */
+    err: "#cf4b4b",
+    /** Role and info tags. The design's. 4.20:1 on its chip - below AA, knowingly. */
+    info: "#3b6fd4",
     /** The brand accent, exactly as designed. Never carries white lettering. */
     accent: "#5b8def",
     /** The only place the accent is darkened: fills with a white label. 4.57:1. */
     accentStrong: "#4b74c4",
-    /** Links, active nav item, active tab. 4.57:1 on `--accent-soft`. */
-    accentText: "#476aaf",
+    /** Links, active nav item, active tab. The design's oklab mix, resolved. 4.29:1 on `--accent-soft` over the sidebar - below AA, knowingly. */
+    accentText: "#4a6eb6",
     /** Labels on the filled colours above. Light's fills carry white. */
     onFill: "#ffffff",
   },