@bsuite/theme 0.10.4 → 0.10.6

package/dist/react/BrandingProvider.d.ts

@@ -1,5 +1,48 @@
-import type { ReactNode } from 'react';
+/**
+ * BrandingProvider — runtime enterprise white-labelling
+ * Version 0.4.1
+ *
+ * On mount:
+ *  1. Calls supabase.rpc('branding_json_for_tenant') using the user's authed session.
+ *  2. Validates each colour value is a well-formed oklch() string.
+ *  3. Applies each key as a CSS custom property on document.documentElement.
+ *  4. Caches the result in localStorage under BRANDING_STORAGE_KEY for FOUC prevention.
+ *  5. Subscribes to tenant row changes via Supabase Realtime so branding updates
+ *     propagate without a page reload (within ~1 second).
+ *
+ * Security / brand policies:
+ *  - Only oklch() values are accepted for colour fields — hex/rgb/hsl are rejected.
+ *  - --role-error and --role-destructive are NOT overridable by tenants.
+ *    Colourblind policy (purple error) is a system-level requirement, not a brand pref.
+ *  - brand="braden" short-circuits all Supabase calls — Braden corporate site uses
+ *    static CSS tokens, not runtime tenant overrides.
+ *  - SEC-002 / SEC-003 (added 0.4.1) — tenant-controlled URL fields
+ *    (`logo_url`, `logo_light_url`, `logo_dark_url`, `mark_url`,
+ *    `favicon_url`) and `font_stack` are routed through `branding-sanitize`
+ *    at the DOM-apply sink. Dangerous schemes (`javascript:`, `data:`,
+ *    `vbscript:`, `blob:`, `file:`) are rejected; the URL is parsed and
+ *    re-serialised so breakout chars are percent-encoded; the `url()`
+ *    token is emitted in the safe quoted form with `"` and `\` escaped;
+ *    font values carrying CSS-breakout tokens (`< > ( ) { } ; @ \ /* *\/`)
+ *    are rejected and the var is cleared so the default font applies.
+ *
+ * Environment flags:
+ *  - VITE_ENABLE_BRANDING_OVERRIDE (default: 'true') — set 'false' as kill switch.
+ *
+ * Usage:
+ *    <ThemeProvider>
+ *      <BrandingProvider supabaseClient={supabase}>
+ *        {children}
+ *      </BrandingProvider>
+ *    </ThemeProvider>
+ *
+ *   For Braden corporate (skips all RPC/Realtime):
+ *    <BrandingProvider brand="braden" supabaseClient={supabase}>
+ *      {children}
+ *    </BrandingProvider>
+ */
 import type { SupabaseClient } from '@supabase/supabase-js';
+import type { ReactNode } from 'react';
 export declare const BRANDING_STORAGE_KEY = "bsuite_tenant_branding";
 export declare const BRANDING_OVERRIDE_FLAG = "VITE_ENABLE_BRANDING_OVERRIDE";
 /** Shape returned by the branding_json_for_tenant RPC */

package/dist/react/BrandingProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BrandingProvider.d.ts","sourceRoot":"","sources":["../../src/react/BrandingProvider.tsx"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAO3D,eAAO,MAAM,oBAAoB,2BAA2B,CAAA;AAC5D,eAAO,MAAM,sBAAsB,kCAAkC,CAAA;AAErE,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED,eAAO,MAAM,eAAe,2DAA6D,CAAA;AAEzF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,CAAA;IACnB,2DAA2D;IAC3D,cAAc,EAAE,cAAc,CAAA;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AA+KD,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,cAAc,EACd,KAAgB,EAChB,qBAA4B,GAC7B,EAAE,qBAAqB,+BA4GvB"}
+{"version":3,"file":"BrandingProvider.d.ts","sourceRoot":"","sources":["../../src/react/BrandingProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAQtC,eAAO,MAAM,oBAAoB,2BAA2B,CAAA;AAC5D,eAAO,MAAM,sBAAsB,kCAAkC,CAAA;AAErE,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED,eAAO,MAAM,eAAe,2DAA6D,CAAA;AAEzF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,CAAA;IACnB,2DAA2D;IAC3D,cAAc,EAAE,cAAc,CAAA;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAyLD,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,cAAc,EACd,KAAgB,EAChB,qBAA4B,GAC7B,EAAE,qBAAqB,+BA4GvB"}

package/dist/react/BrandingProvider.js

@@ -1,47 +1,4 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * BrandingProvider — runtime enterprise white-labelling
- * Version 0.4.1
- *
- * On mount:
- *  1. Calls supabase.rpc('branding_json_for_tenant') using the user's authed session.
- *  2. Validates each colour value is a well-formed oklch() string.
- *  3. Applies each key as a CSS custom property on document.documentElement.
- *  4. Caches the result in localStorage under BRANDING_STORAGE_KEY for FOUC prevention.
- *  5. Subscribes to tenant row changes via Supabase Realtime so branding updates
- *     propagate without a page reload (within ~1 second).
- *
- * Security / brand policies:
- *  - Only oklch() values are accepted for colour fields — hex/rgb/hsl are rejected.
- *  - --role-error and --role-destructive are NOT overridable by tenants.
- *    Colourblind policy (purple error) is a system-level requirement, not a brand pref.
- *  - brand="braden" short-circuits all Supabase calls — Braden corporate site uses
- *    static CSS tokens, not runtime tenant overrides.
- *  - SEC-002 / SEC-003 (added 0.4.1) — tenant-controlled URL fields
- *    (`logo_url`, `logo_light_url`, `logo_dark_url`, `mark_url`,
- *    `favicon_url`) and `font_stack` are routed through `branding-sanitize`
- *    at the DOM-apply sink. Dangerous schemes (`javascript:`, `data:`,
- *    `vbscript:`, `blob:`, `file:`) are rejected; the URL is parsed and
- *    re-serialised so breakout chars are percent-encoded; the `url()`
- *    token is emitted in the safe quoted form with `"` and `\` escaped;
- *    font values carrying CSS-breakout tokens (`< > ( ) { } ; @ \ /* *\/`)
- *    are rejected and the var is cleared so the default font applies.
- *
- * Environment flags:
- *  - VITE_ENABLE_BRANDING_OVERRIDE (default: 'true') — set 'false' as kill switch.
- *
- * Usage:
- *    <ThemeProvider>
- *      <BrandingProvider supabaseClient={supabase}>
- *        {children}
- *      </BrandingProvider>
- *    </ThemeProvider>
- *
- *   For Braden corporate (skips all RPC/Realtime):
- *    <BrandingProvider brand="braden" supabaseClient={supabase}>
- *      {children}
- *    </BrandingProvider>
- */
 import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { sanitizeBrandingUrl, sanitizeFontFamily, toCssUrl, } from './branding-sanitize.js';
 export const BRANDING_STORAGE_KEY = 'bsuite_tenant_branding';
@@ -169,8 +126,17 @@ function warnIfProtectedKeyAttempted(branding) {
     }
 }
 function isDevEnvironment() {
-    const env = import.meta.env;
-    return env?.DEV === true || env?.MODE === 'development' || env?.NODE_ENV === 'development';
+    // SECURITY: direct static key access only — assigning `import.meta.env` to a
+    // variable makes consumer bundlers (Vite) inline the ENTIRE env object into
+    // every client bundle, leaking every VITE_* secret. try/catch keeps this
+    // safe in non-Vite runtimes where import.meta.env does not exist.
+    try {
+        return (import.meta.env.DEV === true ||
+            import.meta.env.MODE === 'development');
+    }
+    catch {
+        return false;
+    }
 }
 function persistBranding(branding) {
     try {
@@ -197,10 +163,10 @@ function loadPersistedBranding() {
     }
 }
 function isBrandingEnabled() {
+    // SECURITY: direct static key access only (see isDevEnvironment) — reading
+    // `import.meta.env` wholesale leaks every VITE_* secret into client bundles.
     try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const flag = import.meta.env;
-        const value = flag?.VITE_ENABLE_BRANDING_OVERRIDE ?? flag?.['VITE_ENABLE_BRANDING_OVERRIDE'];
+        const value = import.meta.env.VITE_ENABLE_BRANDING_OVERRIDE;
         if (value === 'false' || value === '0')
             return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/theme",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "type": "module",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -11,7 +11,7 @@
     "url": "https://github.com/GaryOcean428/bsuite.git",
     "directory": "packages/theme"
   },
-  "description": "BSuite Universal theme \u2014 D2C Neon Electric + Braden Corporate baselines. Tailwind v4 preset, CSS vars (5-layer), role aliases, colourblind-safe tokens, eye-strain-safe text scale, BrandingProvider (runtime white-label). Used by BSU, CRM7, conduit, R80.3, throughput (D2C) and braden.com.au (Corporate).",
+  "description": "BSuite Universal theme — D2C Neon Electric + Braden Corporate baselines. Tailwind v4 preset, CSS vars (5-layer), role aliases, colourblind-safe tokens, eye-strain-safe text scale, BrandingProvider (runtime white-label). Used by BSU, CRM7, conduit, R80.3, throughput (D2C) and braden.com.au (Corporate).",
   "files": [
     "dist",
     "src/css",

package/src/css/braden.css

@@ -24,10 +24,32 @@
  * already false twice over: the 0.7.0 separation-first contract retired purple
  * for semantics, and the Corporate contract binds error to --braden-indigo.
  *
- * ERROR IS INDIGO HERE, NOT RED — deliberately, and for the opposite reason to
- * D2C. D2C's primary is blue, so error must be red to separate from it.
- * Corporate's primary IS red, so a red error would collide with the brand's
- * own primary action colour. Same rule, inverted inputs.
+ * ERROR IS RED HERE — OPERATOR RULING 2026-08-10, superseding the indigo rule.
+ * Braden: "use standard error red not braden corporate red."
+ *
+ * What this overturns. 0.4.0 bound error to --braden-indigo on a
+ * separation-first argument: D2C's primary is blue so error must be red;
+ * Corporate's primary IS red so error must not be. That reasoning was sound
+ * and it is no longer the rule. Error now uses --error-red, the SAME standard
+ * error red the D2C brand uses (oklch(0.580 0.230 25)) — one error colour
+ * across the estate. Recognition beats palette separation: a person reads red
+ * as "danger" before they read it as "Braden".
+ *
+ * --error-red is NOT a Braden brand colour and must never be used as one. It
+ * is permitted here for the error/destructive roles only. It stays inside the
+ * palette whitelist because it is a value the D2C source-of-truth document
+ * already ships; the whitelist pools both contracts.
+ *
+ * THE COST, MEASURED, SO NOBODY REDISCOVERS IT AS A BUG:
+ *   ΔE_oklch(error red, --braden-red) = 0.113   ← now the palette's tightest pair
+ *   ΔE_oklch(old indigo, --braden-red) = 0.312
+ * The Corporate contract's previously-worst pair was 0.143. A destructive
+ * button and a primary button are now both red, separated by lightness (0.092)
+ * and chroma rather than hue, and under deuteranopia lightness is nearly all
+ * that survives. THEREFORE: destructive actions on Corporate must carry an
+ * icon or an explicit verb ("Delete"), never colour alone. The contract
+ * already said shape and label do more work on this brand than on D2C; after
+ * this ruling that is load-bearing rather than advisory.
  */
 
 
@@ -52,6 +74,12 @@
   --braden-teal-deep:  oklch(0.500 0.140 220);
   --braden-aqua:       oklch(0.800 0.130 198);
 
+  /* NOT A BRAND COLOUR. The estate's single standard error red, identical to
+     D2C's, bound to error/destructive only — operator ruling 2026-08-10.
+     Never bind this to primary, accent, a gradient stop or any decorative
+     surface: doing so puts a non-Braden red on a Braden page. */
+  --error-red:         oklch(0.580 0.230  25);
+
 /* ============================================================
    LAYER 2 — SURFACES AND BORDERS
    ============================================================ */
@@ -78,7 +106,14 @@
    ============================================================ */
   --role-text-heading:   var(--role-h1);
   --role-text-body:      oklch(0.22 0.020 250);
-  --role-text-secondary: oklch(0.38 0.018 250);
+  /* -base is what a LIGHT panel nested inside a dark section resets to. A
+     dark brand fill re-scopes the surface tokens for everything inside it,
+     which is right until the section contains a white card — then the card
+     inherits on-dark type and renders light-on-white. The reset cannot
+     hardcode a value because the correct one differs per theme, so it reads
+     this alias instead. */
+  --role-text-secondary-base: oklch(0.38 0.018 250);
+  --role-text-secondary: var(--role-text-secondary-base);
   --role-text-muted:     oklch(0.52 0.018 250);
   --role-text-subtle:    oklch(0.60 0.012 250);
   --role-text-disabled:  oklch(0.72 0.010 250);
@@ -102,13 +137,16 @@
 
 /* ============================================================
    LAYER 3 — SEMANTIC ROLES
-   error = --braden-indigo: Corporate primary is RED, so error cannot be.
+   error = --error-red, the estate's standard error red — operator ruling
+   2026-08-10. It is deliberately NOT --braden-red: the brand primary and the
+   destructive colour must still be two different values, even now that both
+   are red. See the header for the measured separation and what it obliges.
    ============================================================ */
   --role-primary:     var(--braden-red);
   --role-secondary:   var(--braden-navy);
   --role-accent:      var(--braden-gold);
-  --role-error:       var(--braden-indigo);
-  --role-destructive: var(--braden-indigo);
+  --role-error:       var(--error-red);
+  --role-destructive: var(--error-red);
   --role-warning:     var(--braden-gold);
   --role-success:     var(--braden-aqua);
   --role-info:        var(--braden-teal-deep);
@@ -176,8 +214,12 @@
    A saturated fill colour is not a legible text colour.
    ============================================================ */
   --role-primary-text: oklch(0.566 0.170 17.6);
-  --role-accent-text:  oklch(0.544 0.092 89.9);
-  --role-error-text:   oklch(0.562 0.200 270);
+  --role-accent-text-base: oklch(0.544 0.092 89.9);
+  --role-accent-text:  var(--role-accent-text-base);
+  /* Red, per the 2026-08-10 ruling. Measured on Corporate's own light
+     surfaces, not inherited from D2C's: 6.18:1 on --role-bg-body,
+     6.44:1 on --role-bg-panel. Both ✓ AA. */
+  --role-error-text:   oklch(0.482 0.230  25);
   --role-warning-text: oklch(0.544 0.092 89.9);
   --role-success-text: oklch(0.515 0.130 198);
   --role-info-text:    oklch(0.519 0.140 220);
@@ -188,6 +230,10 @@
   --text-on-light-fill: oklch(0.980 0.006 50);
   --text-on-dark-fill:  oklch(0.190 0.020 250);
   --text-on-primary:    var(--text-on-light-fill);
+  /* On the new error red (L 0.58) this measures 4.54:1 — ✓ AA, but with no
+     headroom. It was 9.35:1 on the old indigo fill (L 0.40). If the error
+     fill is ever lightened, re-measure before shipping: a tenth of a point of
+     lightness drops it below AA. */
   --text-on-error:      var(--text-on-light-fill);
   --text-on-accent:     var(--text-on-dark-fill);
   --text-on-warning:    var(--text-on-dark-fill);
@@ -260,7 +306,8 @@
   --role-h5:             oklch(0.80 0.040 228);
   --role-h6:             oklch(0.75 0.048 220);
   --role-text-body:      oklch(0.93 0.014 250);
-  --role-text-secondary: oklch(0.80 0.016 250);
+  --role-text-secondary-base: oklch(0.80 0.016 250);
+  --role-text-secondary: var(--role-text-secondary-base);
   --role-text-muted:     oklch(0.66 0.018 250);
   --role-text-subtle:    oklch(0.55 0.015 250);
   --role-text-disabled:  oklch(0.43 0.010 250);
@@ -278,8 +325,11 @@
   --role-kbd-bg:         oklch(0.250 0.020 250);
   --role-kbd-border:     oklch(0.400 0.022 250);
   --role-primary-text:   oklch(0.704 0.170 17.6);
-  --role-accent-text:    oklch(0.683 0.092 89.9);
-  --role-error-text:     oklch(0.711 0.200 270);
+  --role-accent-text-base: oklch(0.683 0.092 89.9);
+  --role-accent-text:    var(--role-accent-text-base);
+  /* Red, per the 2026-08-10 ruling. 7.24:1 on --role-bg-body,
+     6.51:1 on --role-bg-panel. Both ✓ AA. */
+  --role-error-text:     oklch(0.786 0.230  25);
   --role-warning-text:   oklch(0.683 0.092 89.9);
   --role-success-text:   oklch(0.662 0.130 198);
   --role-info-text:      oklch(0.667 0.140 220);

package/src/css/vars.css

@@ -200,15 +200,30 @@
 
   /* AA-safe text renderings of the saturated roles on light surfaces.
      A saturated fill colour is not a legible text colour; these are the
-     text variants and are the ONLY correct token for coloured type. */
-  --role-primary-text: oklch(0.541 0.215 262.9);  /* 4.71:1 ✓ AA */
-  --role-accent-text:  oklch(0.499 0.132 191.7);  /* 4.70:1 ✓ AA */
-  --role-error-text:   oklch(0.556 0.230  25);    /* 4.69:1 ✓ AA */
-  --role-warning-text: oklch(0.535 0.150  75);    /* 4.70:1 ✓ AA */
-  --role-success-text: oklch(0.501 0.130 195);    /* 4.70:1 ✓ AA */
+     text variants and are the ONLY correct token for coloured type.
+
+     VERIFIED AGAINST THE TINTED PILL, NOT JUST THE PAGE BACKGROUND. These
+     previously sat at ~4.70:1 measured against --role-bg-body, which is the
+     right floor for a bare coloured word on the page and the wrong one for
+     where they are actually used most: `bg-success/10 text-success-text`, a
+     status pill captioned on a 10% wash of its own hue. That wash pulls the
+     backdrop toward the text, and every one of these measured BELOW 4.5:1 in
+     that setting — error worst at 3.64:1 live. A token can be AA in the
+     context it was measured in and fail in the context it ships in.
+
+     Each is now dropped in lightness until it clears 4.5:1 on its own /10
+     tint with margin. Darkening only ever RAISES contrast against a light
+     backdrop, so the original page-background figures improve rather than
+     regress; both are quoted below. Dark mode is untouched — its variants sit
+     at L 0.67-0.79 and already measure clean on tint (7:1+ AAA). */
+  --role-primary-text: oklch(0.499 0.215 262.9);  /* 4.96:1 tint · 5.66:1 body ✓ AA */
+  --role-accent-text:  oklch(0.468 0.132 191.7);  /* 4.96:1 tint · 5.32:1 body ✓ AA */
+  --role-error-text:   oklch(0.482 0.230  25);    /* 4.96:1 tint · 5.83:1 body ✓ AA */
+  --role-warning-text: oklch(0.509 0.150  75);    /* 4.96:1 tint · 5.24:1 body ✓ AA */
+  --role-success-text: oklch(0.463 0.130 195);    /* 4.97:1 tint · 5.46:1 body ✓ AA */
   /* Pair for --role-info. Every other semantic role had a -text token; info
      was the only gap, which forced apps to invent a local copy (R80.4). */
-  --role-info-text:    oklch(0.480 0.120 192);    /* 4.70:1 ✓ AA on panel */
+  --role-info-text:    oklch(0.468 0.120 192);    /* 4.96:1 tint · 5.44:1 body ✓ AA */
 
   /* Text roles — six-tier scale (W3 §3.1 contract). Every tier below is
      measured against --role-bg-body (the conservative floor); all tiers

package/src/preset-v4.css

@@ -169,6 +169,31 @@
   --color-text-on-success: var(--text-on-success);
   --color-text-on-warning: var(--text-on-warning);
 
+  /* The two BASE inverse tones, exposed because the semantic roles above do
+     not cover every coloured fill in the system. The stage ramp is the case
+     that forced this: --stage-1..6 is a FIXED light-to-dark scale that does
+     NOT flip with the theme, so a chip painted `bg-stage-1` (L 0.86) needs
+     dark type in BOTH modes. Captioning it `text-foreground` — which DOES
+     flip — measured 1.34:1 in dark mode on conduit's candidate list, the
+     worst reading anywhere in the estate.
+
+     Read the name as describing the TEXT, not the fill: --text-on-dark-fill
+     is the DARK tone, and it is what goes on a LIGHT fill (see
+     --text-on-accent, cyan at L 0.77, which uses it).
+
+     For the stage ramp specifically, the crossover is between 4 and 5:
+
+       stage-1 L 0.86   light 1.52:1   dark 11.49:1
+       stage-2 L 0.78   light 1.93:1   dark  9.01:1
+       stage-3 L 0.70   light 2.55:1   dark  6.84:1
+       stage-4 L 0.62   light 3.48:1   dark  5.01:1   <- still takes DARK
+       stage-5 L 0.54   light 4.85:1   dark  3.59:1   <- flips to LIGHT
+       stage-6 L 0.46   light 6.86:1   dark  2.54:1
+
+     stage-4 is the trap: it reads as "mid, so white type is fine" and is not. */
+  --color-text-on-light-fill: var(--text-on-light-fill);
+  --color-text-on-dark-fill:  var(--text-on-dark-fill);
+
   /* ============================================================
      TYPE — the contract's stack, bridged to Tailwind's font-* utilities.
      `font-sans` and `font-mono` are what components actually write, so