@7365admin1/layer-common 3.2.1-staging.69 → 3.2.1-staging.71

package/.changeset/dark-primary-contrast.md

@@ -0,0 +1,39 @@
+---
+"@7365admin1/layer-common": patch
+---
+
+Split the dark theme's `primary` into a foreground colour and a fill, so text
+using it is readable again.
+
+Dark `primary` was set to the brand navy `#17506F` so the navigation drawer
+would read as a surface. That is the right value for a fill — a white label on
+it measures 8.70:1 — but Vuetify emits `.text-primary` from the same token, so
+every `class="text-primary"` sentence and every `color="primary"` icon, spinner
+and text button rendered navy on a dark background:
+
+|                        | before | now |
+|---|---|---|
+| `primary` as text on the dark page `#0E1319`   | 2.14:1 | **6.40:1** |
+| `primary` as text on a dark card `#1B242F`     | 1.80:1 | **5.38:1** |
+| `primary` as text on `surface-bright` `#26313E`| 1.52:1 | **4.53:1** |
+
+Dark `primary` is now `#5B9BE0`. That is not a new colour: it is the blue the
+camera wall already draws its accents in (`--vms-accent`), so the two dark
+surfaces in this product agree on one blue.
+
+The navigation drawer no longer depends on `primary`. Both themes gain a
+`brand-surface` colour — `#042134` light (identical to light `primary`, so
+light mode renders exactly as before) and `#17506F` dark — and
+`Layout/NavigationDrawer.vue` is painted with it. Its white label still reads
+16.51:1 light and 8.70:1 dark. `floating` was dropped from the drawer so it
+draws its own edge: the fill is 2.14:1 against the dark page, under the 3:1 a
+boundary wants, and the border at `border-opacity` 0.35 is 3.22:1.
+
+Where `primary` is still used as a fill, Vuetify derives `on-primary` from it
+and picks black, which reads at 7.21:1. What a light `primary` cannot carry is
+a hardcoded white label, and a handful of app-side sites still set one — see
+the pull request for the list.
+
+The light theme is unchanged. The colours moved to `utils/theme.ts` and
+`utils/theme.test.ts` now measures them, so a token cannot be moved for one use
+and quietly broken for the other again.

package/components/Layout/NavigationDrawer.vue

@@ -1,9 +1,41 @@
 <!-- LayoutNavigationDrawer.vue -->
 <template>
-  <v-navigation-drawer v-model="drawer" permanent floating class="bg-primary">
+  <!--
+    `bg-brand-surface`, not `bg-primary`: `primary` is a foreground colour on a
+    dark page (it has to carry `class="text-primary"` sentences at 4.5:1), and a
+    fill that carries a label cannot also be that. `brand-surface` is a real
+    surface in each theme - see `utils/theme.ts` - so the drawer belongs to the
+    application it is in rather than being the one panel the theme switch never
+    reached. Its label reads 15.43:1 light, 13.21:1 dark.
+
+    NO HARDCODED LABEL COLOUR ANYWHERE IN HERE. Vuetify paints the drawer with
+    `on-brand-surface` and the list inside it inherits that through
+    `bg-transparent`, which the drawer supplies to every `v-list` it contains.
+    A `text-white` in here (or in an app's `#action` / `#services` slot) is
+    white on a light rail at 1.13:1.
+
+    `floating` dropped so the drawer draws its own edge, and the three
+    opacities below are raised on this element only:
+
+    - `border-opacity` 0.45. A surface is a low-contrast panel by design
+      (1.13:1 light, 1.19:1 dark against the page), so the edge is what carries
+      the boundary: 3.27:1 light, 4.33:1 dark. The theme-wide value stays where
+      it is; raising that would redraw every table and card edge in eleven
+      applications.
+    - `hover-opacity` 0.08. Material's 0.04 is 1.11:1 on this rail, which is
+      not feedback. 0.08 is 1.17:1 light, 1.24:1 dark.
+    - `activated-opacity` 0.18. The active item is `primary` text on a
+      primary-tinted fill (see `NavigationItem.vue`); 0.12 left the fill at
+      1.15:1, 0.18 is 1.44:1 light, 1.33:1 dark.
+  -->
+  <v-navigation-drawer
+    v-model="drawer"
+    permanent
+    class="bg-brand-surface brand-drawer"
+  >
     <v-list>
       <v-list-item>
-        <v-list-item-title class="text-h6 text-white">
+        <v-list-item-title class="text-h6">
           {{ props.title || APP_NAME }}
         </v-list-item-title>
       </v-list-item>
@@ -91,3 +123,12 @@ const handleClick = (item: any) => {
   emit("navigate", item);
 };
 </script>
+
+<style scoped>
+/* Scoped to the drawer: none of these reach the rest of the application. */
+.brand-drawer {
+  --v-border-opacity: 0.45;
+  --v-hover-opacity: 0.08;
+  --v-activated-opacity: 0.18;
+}
+</style>

package/components/NavigationItem.vue

@@ -1,9 +1,16 @@
+<!--
+  `color="primary"` is applied by Vuetify only while the item is active, so the
+  page you are on is named by colour and not just by a 1.15:1 tint you cannot
+  see. `primary` reads 14.56:1 on the light rail and 5.38:1 on the dark one,
+  and it is the one brand colour that is a foreground in both themes.
+-->
 <template>
   <v-list-group v-if="children && children.length">
     <template #activator="{ props: groupProps }">
       <v-list-item
         v-bind="groupProps"
         :prepend-icon="icon"
+        color="primary"
         class="text-subtitle-2"
         @click.stop="onParentClick"
       >
@@ -25,6 +32,7 @@
     v-else-if="routeTo"
     :prepend-icon="icon"
     :to="routeTo"
+    color="primary"
     class="text-subtitle-2"
   >
     {{ title }}
@@ -34,6 +42,7 @@
     v-else-if="props.link"
     :prepend-icon="icon"
     :href="props.link"
+    color="primary"
     class="text-subtitle-2"
   >
     {{ title }}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.1-staging.69",
+  "version": "3.2.1-staging.71",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "publishConfig": {

package/plugins/vuetify.ts

@@ -42,66 +42,7 @@ import {
 } from "vuetify-pro-tiptap";
 import "vuetify-pro-tiptap/style.css";
 
-/**
- * Contrast decisions live here rather than inline, because both themes need the
- * same two opacity corrections and a value that differs by accident between
- * light and dark is a bug nobody sees until somebody flips the switch.
- *
- * `disabled-opacity`: Material's 0.38 measures 2.68:1 on white, below the 4.5:1
- * a sentence needs, and disabled fields in this product carry sentences people
- * are expected to read. 0.55 is 4.74:1 on white and 6.21:1 on the dark page -
- * the same value the camera wall settled on, for the same reason.
- *
- * `border-opacity`: 0.12 measures 1.32:1, which is a divider you cannot see.
- * Dark goes to 0.35 (3.22:1) and carries the boundary properly. Light goes to
- * 0.26 (1.88:1) - visible, but short of the 3:1 a component boundary wants.
- * Reaching it on white needs 0.42, which turns every table and card edge into a
- * mid-grey grid across eleven applications; that is a change somebody should
- * look at before it ships, not one to slip in behind a contrast fix.
- */
-const LIGHT_THEME = {
-  dark: false,
-  colors: {
-    primary: "#042134",
-    "primary-button": "#1867C0",
-    "text-primary": "#052439",
-  },
-  variables: {
-    "disabled-opacity": 0.55,
-    "border-opacity": 0.26,
-  },
-};
-
-/**
- * Only the keys that must differ; Vuetify merges the rest from its stock dark.
- */
-const DARK_THEME = {
-  dark: true,
-  colors: {
-    /**
-     * Stock dark's #121212 page and #212121 surface measure 1.16:1 apart, so a
-     * card, a dialog and the page behind them were one flat sheet. These are
-     * 1.19:1 - elevation on a dark screen is a genuinely small delta - but they
-     * are tinted towards the brand navy rather than neutral grey, and the
-     * divider opacity above is what actually draws the edges.
-     */
-    background: "#0E1319",
-    surface: "#1B242F",
-    /** Stock dark ships a lavender #ccbfd6 here, which is not our product. */
-    "surface-bright": "#26313E",
-    "surface-light": "#26313E",
-    /** The brand navy lifted until the nav drawer is a surface, not a hole. */
-    primary: "#17506F",
-    /** Unchanged on purpose: it already passes in both themes. */
-    "primary-button": "#1867C0",
-    /** #052439 on a dark page measures 1.18:1. This is 15.72:1. */
-    "text-primary": "#E8ECF1",
-  },
-  variables: {
-    "disabled-opacity": 0.55,
-    "border-opacity": 0.35,
-  },
-};
+import { LIGHT_THEME, DARK_THEME } from "../utils/theme";
 
 export default defineNuxtPlugin((app) => {
   const vuetify = createVuetify({
@@ -152,18 +93,8 @@ export default defineNuxtPlugin((app) => {
      * means the toggle, `v-theme-provider theme="light"`, the `plain-dark`
      * layout and all of those comparisons keep working, and start being right.
      *
-     * Measured, not eyeballed - WCAG 2.1, alpha composited against the surface
-     * each value actually sits on:
-     *
-     *   text-primary on the page       dark   1.18:1 -> 15.72:1
-     *   nav drawer fill vs the page    dark   1.13:1 ->  2.14:1 (+ a real border)
-     *   white label in the nav drawer  dark   3.12:1 ->  8.70:1
-     *   primary-button vs the page     dark   3.34:1 ->  3.32:1 (unchanged)
-     *   white label on that button     both   5.61:1 ->  5.61:1 (unchanged)
-     *   disabled text                  light  2.68:1 ->  4.74:1
-     *   disabled text                  dark   3.57:1 ->  6.21:1
-     *   divider / outline              dark   1.38:1 ->  3.22:1
-     *   divider / outline              light  1.32:1 ->  1.88:1
+     * The colours themselves, and every ratio they were chosen for, are in
+     * `utils/theme.ts`, which `utils/theme.test.ts` measures on every run.
      */
     theme: {
       defaultTheme: "light",

package/utils/theme.test.ts

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DARK_THEME, LIGHT_THEME } 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);
+});
+
+/**
+ * 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);
+  assert.ok(
+    contrast(over(WHITE, dark.background, 0.55), dark.background) >= 4.5
+  );
+});
+
+test("the dark divider clears the 3:1 a boundary wants", () => {
+  const border = "#62666a"; // white at 0.35 over the dark page
+
+  assert.equal(DARK_THEME.variables["border-opacity"], 0.35);
+  assert.ok(contrast(border, dark.background) >= 3);
+});

package/utils/theme.ts

@@ -0,0 +1,136 @@
+/**
+ * THE TWO THEMES THIS PRODUCT SHIPS.
+ *
+ * They live here rather than inline in `plugins/vuetify.ts` so that
+ * `utils/theme.test.ts` can measure them. Every ratio quoted below is WCAG 2.1,
+ * alpha composited against the surface the value actually sits on, and the test
+ * re-measures the ones that matter on every run - this file has already been
+ * got wrong once by moving a colour for one use and forgetting the other.
+ *
+ * `disabled-opacity`: Material's 0.38 measures 2.68:1 on white, below the 4.5:1
+ * a sentence needs, and disabled fields in this product carry sentences people
+ * are expected to read. 0.55 is 4.74:1 on white and 6.21:1 on the dark page -
+ * the same value the camera wall settled on, for the same reason.
+ *
+ * `border-opacity`: 0.12 measures 1.32:1, which is a divider you cannot see.
+ * Dark goes to 0.35 (3.22:1) and carries the boundary properly. Light goes to
+ * 0.26 (1.88:1) - visible, but short of the 3:1 a component boundary wants.
+ * Reaching it on white needs 0.42, which turns every table and card edge into a
+ * mid-grey grid across eleven applications; that is a change somebody should
+ * look at before it ships, not one to slip in behind a contrast fix.
+ */
+
+/**
+ * `primary` IS BOTH A FILL AND A FOREGROUND, AND ONE VALUE CANNOT SERVE BOTH.
+ *
+ * Vuetify emits `.bg-primary` and `.text-primary` from the same token, so the
+ * colour that fills the navigation drawer is also the colour of every
+ * `class="text-primary"` sentence, every `color="primary"` icon, spinner and
+ * text button, and the focused outline on every input. On a dark page those
+ * pull in opposite directions: a fill that carries a white label wants to be
+ * dark, and a foreground that is readable on a dark card wants to be light.
+ * There is no overlap - a value light enough for 4.5:1 text on `surface`
+ * (#1B242F) can carry white at 3.48:1 at the very best.
+ *
+ * So the fill is not `primary` any more. `brand-surface` below is what the
+ * navigation drawer is painted with, and `primary` is free to be a foreground
+ * colour. The foreground uses outnumber the fill uses by roughly an order of
+ * magnitude, which is why the split falls this way round.
+ */
+
+/**
+ * `brand-surface` IS A SURFACE, AND A SURFACE BELONGS TO ITS THEME.
+ *
+ * It was first set to the deep brand navy in BOTH themes, which made the
+ * navigation drawer the one part of the product the theme switch did not
+ * reach: a near-black slab bolted onto a white application in light mode, and
+ * a lighter blue block sitting 1.80:1 off the cards beside it in dark mode. It
+ * belonged to neither.
+ *
+ * It is now a real surface in each theme - a light navy-tinted rail on the
+ * light page, the same `surface` the app bar and the cards use on the dark
+ * page - so the drawer reads as part of the application it is in and the
+ * switch visibly changes it. The brand is carried by the title and by the
+ * active item, which is `primary` in both themes, rather than by painting the
+ * whole rail.
+ *
+ * The drawer is a low-contrast panel against the page by design (1.13:1 light,
+ * 1.19:1 dark, exactly like every other surface in Material), so its edge is
+ * what carries the boundary. `NavigationDrawer.vue` raises `border-opacity` on
+ * itself alone to reach 3:1 there without redrawing every table and card edge
+ * in eleven applications.
+ *
+ * `on-brand-surface` is set explicitly rather than left to Vuetify's black or
+ * white, so the label is the same near-black / near-white the rest of the
+ * theme reads in.
+ */
+export const LIGHT_THEME = {
+  dark: false,
+  colors: {
+    primary: "#042134",
+    /**
+     * The navigation drawer's own fill: a navy-tinted light rail, 1.13:1
+     * against the white page and carried by its own 3.27:1 edge.
+     */
+    "brand-surface": "#EDF1F7",
+    /** The drawer's label colour. On the rail: 15.43:1. */
+    "on-brand-surface": "#0B1B27",
+    "primary-button": "#1867C0",
+    "text-primary": "#052439",
+  },
+  variables: {
+    "disabled-opacity": 0.55,
+    "border-opacity": 0.26,
+  },
+};
+
+/**
+ * Only the keys that must differ; Vuetify merges the rest from its stock dark.
+ */
+export const DARK_THEME = {
+  dark: true,
+  colors: {
+    /**
+     * Stock dark's #121212 page and #212121 surface measure 1.16:1 apart, so a
+     * card, a dialog and the page behind them were one flat sheet. These are
+     * 1.19:1 - elevation on a dark screen is a genuinely small delta - but they
+     * are tinted towards the brand navy rather than neutral grey, and the
+     * divider opacity above is what actually draws the edges.
+     */
+    background: "#0E1319",
+    surface: "#1B242F",
+    /** Stock dark ships a lavender #ccbfd6 here, which is not our product. */
+    "surface-bright": "#26313E",
+    "surface-light": "#26313E",
+    /**
+     * A FOREGROUND colour, chosen to be read: 6.40:1 on the page, 5.38:1 on a
+     * card, 4.53:1 on the bright surface. Not a new colour - it is the blue the
+     * camera wall already draws its accents in (`--vms-accent`), so the two
+     * dark surfaces in this product now agree on one blue.
+     *
+     * Where it is still used as a fill, Vuetify derives `on-primary` from it
+     * and picks black, which reads at 7.21:1. What it cannot carry is a
+     * hardcoded white label - see the note in the PR for the app-side sites
+     * that still do that.
+     */
+    primary: "#5B9BE0",
+    /**
+     * The navigation drawer's own fill. Deliberately the same value as
+     * `surface`: on a dark page the drawer, the app bar and the cards are the
+     * same material, which is what makes the rail read as part of the
+     * application instead of a blue block laid on top of it. The token stays
+     * separate from `surface` so the drawer can be moved on its own later.
+     */
+    "brand-surface": "#1B242F",
+    /** The drawer's label colour. On the rail: 13.21:1. */
+    "on-brand-surface": "#E8ECF1",
+    /** Unchanged on purpose: it already passes in both themes. */
+    "primary-button": "#1867C0",
+    /** #052439 on a dark page measures 1.18:1. This is 15.72:1. */
+    "text-primary": "#E8ECF1",
+  },
+  variables: {
+    "disabled-opacity": 0.55,
+    "border-opacity": 0.35,
+  },
+};