@7365admin1/layer-common 3.2.1 → 3.2.2-staging.101

package/utils/theme.test.ts

@@ -0,0 +1,534 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DARK_THEME, LIGHT_THEME, PALETTE, type TPalette } from "./theme.ts";
+
+/**
+ * The dark theme was shipped once with `primary` chosen for the one place it
+ * was a fill, which left the twenty-six places it is a sentence at 1.80:1.
+ * These are the measurements that would have caught it.
+ *
+ * WCAG 2.1 relative luminance and contrast ratio, nothing else.
+ */
+const luminance = (hex: string): number => {
+  const channels = [0, 2, 4]
+    .map((i) => parseInt(hex.slice(1 + i, 3 + i), 16) / 255)
+    .map((c) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)));
+
+  return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2];
+};
+
+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);
+};
+
+/** `fg` at `alpha` composited over `bg` - an overlay is not its raw value. */
+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 WHITE = "#FFFFFF";
+const dark = DARK_THEME.colors;
+const light = LIGHT_THEME.colors;
+
+/** Sanity check on the measuring tape before it is used to judge anything. */
+test("contrast is measured the way WCAG measures it", () => {
+  assert.equal(contrast(WHITE, "#000000").toFixed(2), "21.00");
+  assert.equal(contrast("#777777", WHITE).toFixed(2), "4.48");
+});
+
+test("dark primary is readable as text on the page, a card and a menu", () => {
+  assert.ok(
+    contrast(dark.primary, dark.background) >= 4.5,
+    `primary on the page: ${contrast(dark.primary, dark.background).toFixed(2)}`
+  );
+  assert.ok(
+    contrast(dark.primary, dark.surface) >= 4.5,
+    `primary on a card: ${contrast(dark.primary, dark.surface).toFixed(2)}`
+  );
+  assert.ok(
+    contrast(dark.primary, dark["surface-bright"]) >= 4.5,
+    `primary on surface-bright: ${contrast(
+      dark.primary,
+      dark["surface-bright"]
+    ).toFixed(2)}`
+  );
+});
+
+test("light primary is readable as text on white", () => {
+  assert.ok(contrast(light.primary, WHITE) >= 4.5);
+  assert.ok(contrast(light["text-primary"], WHITE) >= 4.5);
+});
+
+test("text-primary is readable on the surface each theme puts it on", () => {
+  assert.ok(contrast(dark["text-primary"], dark.background) >= 4.5);
+  assert.ok(contrast(dark["text-primary"], dark.surface) >= 4.5);
+});
+
+/**
+ * The drawer is the reason `primary` was moved in the first place. If someone
+ * points it back at `primary` this fails, because a foreground colour cannot
+ * carry the drawer's label.
+ */
+test("the nav drawer fill carries its own label in both themes", () => {
+  assert.ok(
+    contrast(dark["on-brand-surface"], dark["brand-surface"]) >= 4.5,
+    `dark drawer label: ${contrast(
+      dark["on-brand-surface"],
+      dark["brand-surface"]
+    ).toFixed(2)}`
+  );
+  assert.ok(
+    contrast(light["on-brand-surface"], light["brand-surface"]) >= 4.5,
+    `light drawer label: ${contrast(
+      light["on-brand-surface"],
+      light["brand-surface"]
+    ).toFixed(2)}`
+  );
+});
+
+/**
+ * The defect this replaced: `brand-surface` was the same deep navy in both
+ * themes, so the drawer was the one panel the theme switch did not reach. A
+ * light-theme surface has to be light, a dark-theme surface has to be dark,
+ * and if the two are ever within 3:1 of each other the switch is invisible on
+ * the drawer again.
+ */
+test("the drawer belongs to its theme, and the switch visibly changes it", () => {
+  assert.ok(
+    contrast(light["brand-surface"], WHITE) < 1.5,
+    "the light drawer must be a light surface, not a dark slab on a white page"
+  );
+  assert.ok(
+    contrast(dark["brand-surface"], dark.background) < 1.5,
+    "the dark drawer must sit with the dark page, not float above it"
+  );
+  assert.ok(
+    contrast(light["brand-surface"], dark["brand-surface"]) >= 3,
+    `light and dark drawers only ${contrast(
+      light["brand-surface"],
+      dark["brand-surface"]
+    ).toFixed(2)} apart - the switch would look like it does nothing`
+  );
+});
+
+/**
+ * The drawer's fill is deliberately close to the page, so the edge is the
+ * boundary and it is the thing that has to reach 3:1. 0.45 is the value
+ * `NavigationDrawer.vue` sets on itself; the theme-wide `border-opacity` is
+ * left alone.
+ */
+test("the drawer's own edge clears the 3:1 a boundary wants", () => {
+  const edge = (fg: string, bg: string) => over(fg, bg, 0.45);
+
+  assert.ok(
+    contrast(edge("#000000", light["brand-surface"]), WHITE) >= 3,
+    `light drawer edge vs page: ${contrast(
+      edge("#000000", light["brand-surface"]),
+      WHITE
+    ).toFixed(2)}`
+  );
+  assert.ok(
+    contrast(edge(WHITE, dark["brand-surface"]), dark.background) >= 3,
+    `dark drawer edge vs page: ${contrast(
+      edge(WHITE, dark["brand-surface"]),
+      dark.background
+    ).toFixed(2)}`
+  );
+});
+
+/** The active item is named by colour, so `primary` has to be readable on it. */
+test("the active nav item is readable on the drawer in both themes", () => {
+  assert.ok(
+    contrast(light.primary, light["brand-surface"]) >= 4.5,
+    `light: ${contrast(light.primary, light["brand-surface"]).toFixed(2)}`
+  );
+  assert.ok(
+    contrast(dark.primary, dark["brand-surface"]) >= 4.5,
+    `dark: ${contrast(dark.primary, dark["brand-surface"]).toFixed(2)}`
+  );
+});
+
+/**
+ * `v-list-subheader` is the one thing in the drawer that does NOT inherit the
+ * drawer's label colour - Vuetify paints it `on-surface` at medium emphasis.
+ * That is why apps used to hardcode `text-white` on it. It has to work
+ * unaided now, or those hardcodes come back.
+ */
+test("an unstyled subheader is readable on the drawer in both themes", () => {
+  assert.ok(
+    contrast(over("#000000", light["brand-surface"], 0.6), light["brand-surface"]) >= 4.5
+  );
+  assert.ok(
+    contrast(over(WHITE, dark["brand-surface"], 0.6), dark["brand-surface"]) >= 4.5
+  );
+});
+
+test("primary-button carries a white label in both themes", () => {
+  assert.ok(contrast(WHITE, dark["primary-button"]) >= 4.5);
+  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.
+ */
+/**
+ * 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(
+    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", () => {
+  // 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.                                                */
+/*                                                                      */
+/* 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.           */
+/* ==================================================================== */
+
+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);
+
+for (const [name, p] of [
+  ["light", L],
+  ["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.
+   */
+  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"]
+  );
+});
+
+/**
+ * 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.
+ */
+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],
+  ];
+
+  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`
+    );
+    assert.ok(shift > 1, `${name} did not move at all`);
+  }
+});
+
+/**
+ * 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"
+  );
+});