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

package/utils/theme.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 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.
+ */
+
+/**
+ * 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 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",
+    /**
+     * 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.
+     */
+    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;
+
+/**
+ * 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.
+ */
+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: {
+    /**
+     * AN OPACITY IS ONLY AS DARK AS THE INK IT IS APPLIED TO.
+     *
+     * 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.
+     */
+    /**
+     * `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.
+     */
+    "high-emphasis-opacity": 1,
+    "medium-emphasis-opacity": 0.64,
+    "disabled-opacity": 0.62,
+    /**
+     * 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`.
+     */
+    "border-opacity": dark ? 0.35 : 0.26,
+  },
+});
+
+export const LIGHT_THEME = theme(false, PALETTE.light);
+
+export const DARK_THEME = theme(true, PALETTE.dark);