@7365admin1/layer-common 3.2.2-staging.80 → 3.2.2-staging.82

package/utils/theme.ts

@@ -1,163 +1,294 @@
 /**
- * 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.
+ * THE PLATFORM PALETTE, AND THE BRIDGE BETWEEN TWO COLOUR SYSTEMS.
+ *
+ * The redesign is specified in raw CSS custom properties (`--bg`, `--card`,
+ * `--muted`, `--ok`...). This product is built in Vuetify, which paints from
+ * its own `--v-theme-*` RGB triples. Stacking the two would leave every
+ * `v-card`, `v-btn`, `v-chip` and `v-data-table` in eleven applications on its
+ * factory colours underneath a correct-looking token file.
+ *
+ * So there is ONE source of truth - `PALETTE` below - and it flows one way:
+ *
+ *     PALETTE  ->  Vuetify theme colours  ->  `--v-theme-*`  ->  `--bg` etc.
+ *                  (LIGHT_THEME/DARK_THEME)   (Vuetify emits)   (assets/css/tokens.css)
+ *
+ * `assets/css/tokens.css` does not restate a single colour; it aliases each
+ * design token to the Vuetify variable that already holds it. That matters for
+ * more than tidiness: Vuetify puts `.v-theme--light` / `.v-theme--dark` on
+ * every `v-theme-provider` subtree, so a token read inside the `plain-dark`
+ * layout or inside `FormDialog` resolves to that subtree's theme instead of the
+ * page's. A `body.dark` class - which is how the prototype does it - cannot do
+ * that, and would have gone wrong in exactly those two places.
+ *
+ * Every ratio quoted here is WCAG 2.1, alpha composited against the surface the
+ * value actually sits on, and `utils/theme.test.ts` re-measures all of them on
+ * every run. This file has already been got wrong once by moving a colour for
+ * one use and forgetting the other.
+ */
+
+/**
+ * WHAT MOVED FROM THE DESIGN, AND WHY - the owner's decision, 2026-08-13:
+ * "minimal darkening, keep the look".
+ *
+ * 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:
+ *
+ *     --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%)
+ *
+ * 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.
+ *
+ * `--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()`.
+ */
+
+/**
+ * WHITE ON THE ACCENT: A DARKER ACCENT FOR FILLS, NOT A BIGGER FONT.
+ *
+ * White on `--accent` (#5b8def) is 3.23:1 in BOTH themes - the fill is
+ * theme-independent, so the failure is too. It is the primary button's label
+ * and the active segment of the Today/Week/Month control. There were two ways
+ * out and only one of them keeps the design:
+ *
+ *   - The type route. 3.23:1 is legal for LARGE text, which starts at 18.66px
+ *     bold. The design's buttons are 13.5px/700-800 in a 40px pill. Reaching
+ *     18.66px would make the label taller than the button was drawn for and
+ *     change every button in the product. Rejected.
+ *   - `--accent-strong`, an 18%-darker accent used ONLY where a white label
+ *     sits on an accent fill. White reads 4.57:1 on it, and the fill still
+ *     holds its own edge (4.57:1 against a light card, 3.64:1 against a dark
+ *     one). Chosen.
+ *
+ * The point is what it does NOT touch. `--accent` itself is unchanged, so the
+ * links, the active sidebar item, the tab underline, the toggle in its on
+ * state, the chart lines, the focus rings, the logo tile and every
+ * `--accent-soft` background are the exact colour the design specifies. Only
+ * the two filled surfaces that carry white lettering are darker.
  */
 
 /**
  * `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.
+ * colour that fills a button 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, a foreground
+ * that is readable on a dark card wants to be light. There is no overlap.
+ *
+ * That is why the split established on 2026-08-12 survives this rewrite, just
+ * pointed at the new palette:
+ *
+ *     primary         = --accent-text   (a FOREGROUND: links, icons, text)
+ *     primary-button  = --accent-strong (a FILL that carries a white label)
+ *     brand-surface   = --sidebar       (the navigation drawer's own fill)
+ *
+ * Re-pointing rather than renaming is deliberate: `text-primary` and
+ * `primary-button` are written in roughly eighty places across this layer and
+ * the applications, and none of them has to change.
  */
 
 /**
- * `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.
+ * VUETIFY DERIVES THE LABEL ON A FILLED COLOUR, AND ITS GUESS IS WHITE.
+ *
+ * Measured in a browser, not assumed: given `warning`, `info`, `error`,
+ * `success` or `primary` as a fill, Vuetify picks a WHITE foreground. On this
+ * palette's dark theme that is 2.04:1 to 2.99:1 - every filled chip, alert,
+ * badge and button in dark mode. So each `on-*` is set explicitly below rather
+ * than left to the derivation. Light's fills are dark enough that white is in
+ * fact right, and it is still written down there, so that no component in
+ * eleven applications is left depending on Vuetify guessing correctly.
  */
-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",
+export const PALETTE = {
+  light: {
+    /** Page background. */
+    bg: "#f6f6f2",
+    /** The navigation rail. */
+    sidebar: "#fbfbf8",
+    /** Cards, tables, modals, menus. */
+    card: "#ffffff",
+    /** Card and table edges. As designed - see the note in the test. */
+    border: "#e8e8e1",
+    /** Primary text. 17.24:1 on a card. */
+    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",
+    /** 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",
+    /** Labels on the filled colours above. Light's fills carry white. */
+    onFill: "#ffffff",
+  },
+  dark: {
+    bg: "#131418",
+    sidebar: "#17181d",
+    card: "#1c1e24",
+    border: "#2a2d35",
+    text: "#eef0f3",
+    text2: "#c6cad2",
+    /** Passes as designed at 4.93:1 - the dark theme needed no darkening. */
+    muted: "#868c98",
+    ok: "#41c795",
+    warn: "#dcaf4e",
+    err: "#e57373",
+    info: "#7da6ec",
+    accent: "#5b8def",
+    /** Same value as light: the failure was theme-independent, so the fix is. */
+    accentStrong: "#4b74c4",
+    accentText: "#78a2f4",
     /**
-     * Vuetify leaves `warning` (#FB8C00) and `info` (#2196F3) at its stock
-     * values and DERIVES their foreground, and — as with `on-primary` — the
-     * derivation picks WHITE. Measured, that is 2.37:1 on warning and 3.12:1
-     * on info: every filled warning/info chip, alert, button and badge in the
-     * product, including the invitation status chips. Setting the label to the
-     * dark page colour takes them to 8.9:1 and 5.3:1. Same value in both
-     * themes because the two fills are the same in both themes.
+     * Dark's fills are LIGHT colours, so their label is the page ink, not
+     * white. White on them measures 2.04:1 to 2.99:1; this reads 6.16:1 to
+     * 9.01:1. Not a new colour - it is `bg` above, so a filled chip reads as a
+     * hole punched in the page.
      */
-    "on-warning": "#0E1319",
-    "on-info": "#0E1319",
-    "primary-button": "#1867C0",
-    "text-primary": "#052439",
-  },
-  variables: {
-    "disabled-opacity": 0.55,
-    "border-opacity": 0.26,
+    onFill: "#131418",
   },
-};
+} as const;
+
+/**
+ * The values are widened back to `string`. `PALETTE` is `as const` so a test
+ * can assert an exact hex, but the builder below takes EITHER theme - and with
+ * the literal types intact, "#131418" is not assignable to "#f6f6f2" and the
+ * dark theme will not compile.
+ */
+export type TPalette = { readonly [K in keyof (typeof PALETTE)["light"]]: string };
+
+type Palette = TPalette;
 
 /**
- * Only the keys that must differ; Vuetify merges the rest from its stock dark.
+ * One theme builder for both themes, so a colour can never be wired into light
+ * and forgotten in dark - which is the specific way this file broke before.
  */
-export const DARK_THEME = {
-  dark: true,
+const theme = (dark: boolean, p: Palette) => ({
+  dark,
   colors: {
+    // --- the design's surfaces -------------------------------------------
+    background: p.bg,
+    surface: p.card,
+    "on-background": p.text,
+    "on-surface": p.text,
+    /** Menus and raised sheets sit on the card colour, not Vuetify's grey. */
+    "surface-bright": p.card,
+    "surface-light": p.card,
+    "surface-variant": p.sidebar,
+    "on-surface-variant": p.text2,
+
+    // --- the split accent -------------------------------------------------
+    /** A FOREGROUND. See the note above before making this a fill colour. */
+    primary: p.accentText,
+    "on-primary": p.onFill,
+    /** The FILL that carries a white label. White on it: 4.57:1, both themes. */
+    "primary-button": p.accentStrong,
+    "on-primary-button": "#ffffff",
+    /** The navigation drawer's fill = the design's sidebar colour. */
+    "brand-surface": p.sidebar,
+    "on-brand-surface": p.text,
+    /** ~80 call sites across the layer and the apps. Now the design's ink. */
+    "text-primary": p.text,
+
+    // --- semantic status, mapped as the design specifies ------------------
+    /** Completed / Paid / Available / Open. */
+    success: p.ok,
+    "on-success": p.onFill,
+    /** Pending. */
+    warning: p.warn,
+    "on-warning": p.onFill,
+    /** In Use / Closed / Checkout. */
+    error: p.err,
+    "on-error": p.onFill,
+    /** Role and info tags. */
+    info: p.info,
+    "on-info": p.onFill,
+
+    // --- design tokens with no Vuetify equivalent -------------------------
+    // These exist so `assets/css/tokens.css` can alias `--text2`, `--muted`,
+    // `--border`, `--accent` and friends to a `--v-theme-*` that Vuetify keeps
+    // in step with the active theme, rather than restating hexes in CSS.
+    accent: p.accent,
+    "accent-strong": p.accentStrong,
+    "accent-text": p.accentText,
+    text2: p.text2,
+    muted: p.muted,
+    border: p.border,
+    sidebar: p.sidebar,
+  },
+  variables: {
     /**
-     * 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.
+     * AN OPACITY IS ONLY AS DARK AS THE INK IT IS APPLIED TO.
      *
-     * Where it is still used as a fill it needs a foreground, and the claim
-     * that used to sit here - that Vuetify derives black - is wrong. Measured
-     * in a browser, Vuetify picks WHITE, which reads at 2.68:1 on this fill:
-     * every filled primary button, chip, alert and tab bar in dark mode. So
-     * `on-primary` is set explicitly below rather than derived.
-     */
-    primary: "#5B9BE0",
-    /**
-     * The label on a filled `primary` surface. Measured 6.40:1 against
-     * `primary`, against the 2.68:1 Vuetify's own derivation gives. Not a new
-     * colour - it is the dark page `background` above, so a filled button
-     * reads as a hole punched in the page rather than a fifth shade of navy.
+     * Both values below were tuned when `on-surface` was Vuetify's pure black.
+     * The design's ink is `#191b1f`, which is lighter, so the SAME opacity now
+     * composites to a paler grey - and it showed up the moment the two screens
+     * that shipped today were re-rendered: every `text-medium-emphasis` line
+     * fell from 5.74:1 to 4.53:1 on a card and 4.41:1 on the page, taking the
+     * dashboard's site name and the preference screen's summary below AA.
+     *
+     * That is one cause with about two hundred call sites across eleven
+     * applications, so it is fixed once, here, rather than in the two places
+     * the measurement happened to catch.
+     *
+     * `medium-emphasis-opacity` 0.64: 5.11:1 on a card, 4.94:1 on the page,
+     * 5.04:1 on the sidebar. The minimum that clears AA is 0.61 and this keeps
+     * a margin, while staying clearly lighter than `--text2`'s 9.62:1 - it is
+     * still medium emphasis, not body text.
+     *
+     * `disabled-opacity` 0.62: the value that composites `#191b1f` to the same
+     * grey `#000000` reached at 0.55, so a disabled field is exactly as dark as
+     * it was before this palette. It is NOT 4.5:1 as rendered - Vuetify
+     * multiplies its own field alpha on top and the result measures 1.9:1 -
+     * but that compounding predates this work and un-compounding it means
+     * changing how an input draws, which is Phase 3's job, not a token's.
+     *
+     * The same number in both themes on purpose: a value that drifts apart
+     * between light and dark is a bug nobody sees until they flip the switch.
      */
-    "on-primary": "#0E1319",
     /**
-     * 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.
+     * `high-emphasis-opacity` 1, and this one REMOVES a dimming layer rather
+     * than retuning it. Vuetify's 0.87 exists to soften pure black into body
+     * ink; the design already ships body ink, so applying 0.87 on top of
+     * `#191b1f` dims text that was never black to begin with.
+     *
+     * It also compounds. A field label is high emphasis AND medium emphasis -
+     * 0.87 x 0.64 - which is how "Search work orders" was rendering at 3.95:1
+     * while every token it is built from passed on its own. Taking this to 1
+     * leaves one opacity on that label instead of two, and it measures 5.02:1.
      */
-    "brand-surface": "#1B242F",
-    /** The drawer's label colour. On the rail: 13.21:1. */
-    "on-brand-surface": "#E8ECF1",
-    /** See LIGHT_THEME: Vuetify derives white on these fills, at 2.37:1. */
-    "on-warning": "#0E1319",
-    "on-info": "#0E1319",
+    "high-emphasis-opacity": 1,
+    "medium-emphasis-opacity": 0.64,
+    "disabled-opacity": 0.62,
     /**
-     * Dark's stock `error` is the pale #CF6679, and white on it is 3.60:1 —
-     * the light theme's darker #B00020 carries white fine, this one does not.
+     * Vuetify draws borders as `on-surface` at this opacity. The design's
+     * `--border` is a much softer edge than Material's default; these are the
+     * opacities that land closest to it while staying visible. Components that
+     * need a real boundary raise it on themselves - see `NavigationDrawer.vue`.
      */
-    "on-error": "#0E1319",
-    /** 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,
+    "border-opacity": dark ? 0.35 : 0.26,
   },
-};
+});
+
+export const LIGHT_THEME = theme(false, PALETTE.light);
+
+export const DARK_THEME = theme(true, PALETTE.dark);