@tangle-network/brand 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.5.0
+
+### Minor Changes
+
+- 532a6d8: Add `--shadow-overlay`, the elevation step above `--shadow-dropdown` for a surface that covers the page rather than sitting beside it — a drawer, a modal, a floating dock.
+
+  It is derived from `--hsl-foreground` rather than a fixed `rgba`, so it inverts with the theme: dark ink in light, a soft halo in dark. That is what makes it work on a dark canvas, where a black shadow renders as nothing. One declaration serves both themes, and the token is declared in the `@theme` block as well so Tailwind emits a `shadow-overlay` utility.
+
+## 1.4.0
+
+### Minor Changes
+
+- e67a809: Raise the dark surface ladder to AA and add the page-level primitives.
+
+  In the dark spine, `--md3-surface-container-high` and `--md3-surface-container-highest` sat close enough to the ink ramp that `--text-dim` fell under 4.5:1 on them. The ladder is re-spaced and the ink ramp moves with it, so every ink tier clears AA on all five planes.
+
+  Dark status chips keep their hue, drop 14% chroma, and lift the fill to 1.50:1 from the card. A new `--run-mix-*` ramp carries proportional bars, spaced in relative luminance so adjacent segments clear the 3:1 floor for non-text contrast.
+
+  One light token moves: `--surface-warning-text` goes `#b45309` to `#ab4f09`. It is a contrast fix, not a hue change. The old value measured 4.16:1 on the light page canvas, under the 4.5:1 body floor, whenever the colour was used as text away from its own pill background; the new value measures 4.51:1 there and 5.25:1 on the pill. Every other light value is unchanged.
+
+  `@tangle-network/ui` gains four primitives: `PageHeader`, `StatusPill`, `MetricStrip`, and `Toolbar`/`FilterField`. All additive; no existing export changes.
+
 ## 1.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",

package/src/styles/named-themes.css

@@ -52,7 +52,7 @@
 [data-theme="arena-light"],
 [data-theme="tangle-light"] {
   --surface-success-bg: #ecfdf5; --surface-success-border: #a7f3d0; --surface-success-text: #047857;
-  --surface-warning-bg: #fffbeb; --surface-warning-border: #fde68a; --surface-warning-text: #b45309;
+  --surface-warning-bg: #fffbeb; --surface-warning-border: #fde68a; --surface-warning-text: #ab4f09;
   --surface-danger-bg: #fff1f2; --surface-danger-border: #fecdd3; --surface-danger-text: #b91c1c;
   --surface-info-bg: #f0f9ff; --surface-info-border: #bae6fd; --surface-info-text: #0369a1;
   /* Light-tuned interactive tokens — without these the named light scopes
@@ -184,23 +184,23 @@
 [data-theme="tangle-dark"] {
   --hsl-background: 240 24% 11%;  --hsl-foreground: 225 22% 91%;
   --hsl-card: 238 20% 22%;        --hsl-card-foreground: 225 22% 91%;
-  --hsl-popover: 240 22% 27%;     --hsl-popover-foreground: 225 22% 91%;
+  --hsl-popover: 239 22% 25%;     --hsl-popover-foreground: 225 22% 91%;
   --hsl-primary: 246 54% 51%;     --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 240 22% 27%;   --hsl-secondary-foreground: 225 22% 91%;
-  --hsl-muted: 240 22% 27%;       --hsl-muted-foreground: 223 14% 69%;
-  --hsl-accent: 240 22% 27%;      --hsl-accent-foreground: 225 22% 91%;
+  --hsl-secondary: 239 22% 25%;   --hsl-secondary-foreground: 225 22% 91%;
+  --hsl-muted: 239 22% 25%;       --hsl-muted-foreground: 234 16% 74%;
+  --hsl-accent: 239 22% 25%;      --hsl-accent-foreground: 225 22% 91%;
   --hsl-destructive: 348 74% 48%; --hsl-destructive-foreground: 0 0% 100%;
   --hsl-border: 236 20% 35%;      --hsl-input: 240 24% 15%;
   --hsl-ring: 233 100% 87%;
-  --depth-1: #151523; --depth-2: #2d2e43; --depth-3: #363654; --depth-4: #434365;
+  --depth-1: #151523; --depth-2: #2d2e43; --depth-3: #32324e; --depth-4: #393957;
   --bg-root: #151523; --bg-card: var(--depth-2); --bg-input: hsl(var(--hsl-input));
   --md3-surface-container-lowest: #0f0f1a; --md3-surface-container-low: #222235;
-  --md3-surface-container: #2d2e43; --md3-surface-container-high: #363654;
-  --md3-surface-container-highest: #434365; --md3-outline-variant: #474a6b;
+  --md3-surface-container: #2d2e43; --md3-surface-container-high: #32324e;
+  --md3-surface-container-highest: #393957; --md3-outline-variant: #474a6b;
   --border-subtle: rgba(165, 180, 252, 0.10); --border-default: rgba(165, 180, 252, 0.16);
   --border-hover: rgba(165, 180, 252, 0.28); --accent-text: #A5B4FC;
   --brand-primary: #7C6CF6; --brand-glow: #A5AAFC;
-  --text-primary: #e3e6ed; --text-secondary: #bec3d0; --text-muted: #a5abbb; --text-dim: #9299ab;
+  --text-primary: #e3e6ed; --text-secondary: #c2c7d4; --text-muted: #b2b4c7; --text-dim: #9ea5b9;
 }
 /* Its light mode. */
 [data-theme="tangle-light"] {

package/src/styles/theme-parity.test.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { blockIn } from "./css-test-utils";
+
+/**
+ * A token declared in both files has to carry the same value in both.
+ *
+ * `tokens.css` is what a consumer reads at runtime through `var(--x)`.
+ * `theme.css` is the Tailwind v4 `@theme` block, and it exists because Tailwind
+ * only emits a utility for a token it can see declared there — so the shared
+ * ones are necessarily written twice.
+ *
+ * That duplication is structural and cannot be factored out: `@theme` needs a
+ * literal, and a self-reference would be circular. What it can be is GATED. An
+ * edit to one file that misses the other would leave `shadow-overlay` (the
+ * utility, from theme.css) rendering a different shadow from
+ * `shadow-[var(--shadow-overlay)]` (the variable, from tokens.css), and the
+ * mismatch would show up as an inconsistency no one could reproduce from
+ * either file alone.
+ */
+const read = (name: string) =>
+  readFileSync(path.resolve(import.meta.dirname, name), "utf8");
+
+/** `--token: value;` pairs in one CSS block, whitespace collapsed. */
+function declarationsIn(css: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+    out.set(m[1] as string, (m[2] as string).split(/\s+/).join(" ").trim());
+  }
+  return out;
+}
+
+// The default spine, which is the one `@theme` mirrors. Anchor on the last
+// selector of the multi-selector header, as the other suites here do.
+const tokensCss = read("tokens.css");
+const runtime = declarationsIn(blockIn(tokensCss, ".dark"));
+const light = declarationsIn(blockIn(tokensCss, ".light"));
+const theme = declarationsIn(blockIn(read("theme.css"), "@theme"));
+
+const shared = [...theme.keys()].filter((t) => runtime.has(t)).sort();
+
+describe("tokens.css and theme.css agree on every token they both declare", () => {
+  it("finds the shared tokens to check", () => {
+    // Guards the parse itself: a selector rename that silently emptied one
+    // block would otherwise make every assertion below vacuously pass.
+    expect(shared.length).toBeGreaterThan(5);
+  });
+
+  for (const token of shared) {
+    it(`${token} carries one value`, () => {
+      expect(theme.get(token)).toBe(runtime.get(token));
+    });
+  }
+});
+
+/**
+ * A token written in terms of `--hsl-foreground` already inverts, because that
+ * ramp is what each spine redefines. Restating it on the light spine would pin
+ * it to one theme's ink and defeat the derivation — the failure would be silent,
+ * since both declarations are individually valid CSS.
+ *
+ * So the omission is the contract, and this asserts it rather than trusting the
+ * comment that states it.
+ */
+const selfInverting = [...runtime.entries()]
+  .filter(([, value]) => value.includes("var(--hsl-foreground)"))
+  .map(([token]) => token)
+  .sort();
+
+describe("a self-inverting token is declared once, not per spine", () => {
+  it("finds the self-inverting tokens to check", () => {
+    expect(selfInverting.length).toBeGreaterThan(0);
+    // The assertions below are absence checks, so they hold trivially against
+    // an empty map. A selector rename that stopped matching the light spine
+    // would otherwise read as "nothing is restated" — the strongest possible
+    // pass from the weakest possible parse.
+    expect(light.size).toBeGreaterThan(5);
+  });
+
+  for (const token of selfInverting) {
+    it(`${token} is not restated on the light spine`, () => {
+      expect(light.has(token)).toBe(false);
+    });
+  }
+});

package/src/styles/theme.css

@@ -104,4 +104,10 @@
   --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
   --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
   --shadow-glow: none;
+  /* Theme-derived, so it inverts — see tokens.css. Declared here as well so
+     Tailwind emits the `shadow-overlay` utility, which is how a consumer
+     reaches it without writing `shadow-[var(--shadow-overlay)]`. */
+  --shadow-overlay:
+    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
+    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
 }

package/src/styles/tokens.css

@@ -37,7 +37,7 @@
 .dark {
   --md3-surface: #151523;                   /* L0 page canvas */
   --md3-surface-dim: #0f0f1a;               /* recessed page */
-  --md3-surface-bright: #434365;
+  --md3-surface-bright: #393957;
   /* Same value as --md3-surface-dim by design, not by drift: both name the floor
    * of the ladder, and dark has no plane below it to give them. They stay two
    * tokens because the roles diverge in light, where the well is paper (#ffffff)
@@ -46,11 +46,11 @@
   --md3-surface-container-lowest: #0f0f1a;  /* L-1 terminal/code well */
   --md3-surface-container-low: #222235;     /* L1 chrome, field wells */
   --md3-surface-container: #2d2e43;         /* L2 resting card */
-  --md3-surface-container-high: #363654;    /* L3 nested / hover */
-  --md3-surface-container-highest: #434365; /* L4 overlay */
-  --md3-surface-variant: #363654;
+  --md3-surface-container-high: #32324e;    /* L3 nested / hover */
+  --md3-surface-container-highest: #393957; /* L4 overlay */
+  --md3-surface-variant: #32324e;
   --md3-on-surface: #e3e6ed;
-  --md3-on-surface-variant: #a5abbb;
+  --md3-on-surface-variant: #b2b4c7;
 
   --md3-primary: #A5B4FC;
   --md3-primary-dim: #7C6CF6;
@@ -89,20 +89,23 @@
   --hsl-foreground: 225 22% 91%;     /* #e3e6ed */
   --hsl-card: 238 20% 22%;           /* L2 card #2d2e43 */
   --hsl-card-foreground: 225 22% 91%;
-  --hsl-popover: 240 22% 27%;        /* L4 overlay */
+  --hsl-popover: 239 22% 25%;        /* L3 #32324e — the NESTED plane despite
+     the name; the overlay plane is --md3-surface-container-highest. A popover
+     carries body text, and the ladder above L3 is reserved for planes that lift
+     by shadow, so it sits on L3 and the ink ramp reaches it. */
   --hsl-popover-foreground: 225 22% 91%;
   /* The fill indigo, NOT the bright one: `.btn-primary` puts white on this, and
    * #6366F1 carries white at only 4.47:1. This clears the floor at 7.4:1. The
    * bright indigo stays available for accent TEXT via --accent-text. */
   --hsl-primary: 246 54% 51%;       /* #4c3fc6 */
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 240 22% 27%;      /* L3 #363654 */
+  --hsl-secondary: 239 22% 25%;      /* L3 #32324e */
   --hsl-secondary-foreground: 225 22% 91%;
-  --hsl-muted: 240 22% 27%;          /* L3 hover well */
-  --hsl-muted-foreground: 223 14% 69%;  /* #a5abbb — high enough that the
+  --hsl-muted: 239 22% 25%;          /* L3 hover well */
+  --hsl-muted-foreground: 234 16% 74%;  /* #b2b4c7 — high enough that the
      reduced-opacity caption derivatives (/70, /60) still clear the large-text
      contrast floor against the L2 card. */
-  --hsl-accent: 240 22% 27%;         /* neutral hover (indigo lives in accent-surface-strong) */
+  --hsl-accent: 239 22% 25%;         /* neutral hover (indigo lives in accent-surface-strong) */
   --hsl-accent-foreground: 225 22% 91%;
   --hsl-destructive: 348 74% 48%;
   --hsl-destructive-foreground: 0 0% 100%;
@@ -154,7 +157,7 @@
   --sidebar-foreground: 225 22% 91%;
   --sidebar-primary: 246 54% 51%;
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 240 22% 27%;      /* L3 hover well */
+  --sidebar-accent: 239 22% 25%;      /* L3 hover well */
   --sidebar-accent-foreground: 225 22% 91%;
   --sidebar-border: 236 20% 35%;
   --sidebar-ring: 233 100% 87%;
@@ -162,8 +165,8 @@
   /* Depth scale — tracks the MD3 ladder (canvas / card / nested / overlay) */
   --depth-1: #151523;
   --depth-2: #2d2e43;
-  --depth-3: #363654;
-  --depth-4: #434365;
+  --depth-3: #32324e;
+  --depth-4: #393957;
 
   /* Status colors */
   --status-running: #10B981;
@@ -175,18 +178,18 @@
   --status-deleted: #6B7094;
 
   /* Status surface tokens — bg / border / text for each semantic color */
-  --surface-success-bg: #022c22;
-  --surface-success-border: #14532d;
-  --surface-success-text: #34D399;
-  --surface-warning-bg: #451a03;
-  --surface-warning-border: #78350f;
-  --surface-warning-text: #fbbf24;
-  --surface-danger-bg: #450a0a;
-  --surface-danger-border: #7f1d1d;
-  --surface-danger-text: #f87171;
-  --surface-info-bg: #082f49;
-  --surface-info-border: #0c4a6e;
-  --surface-info-text: #38bdf8;
+  --surface-success-bg: #2f5146;
+  --surface-success-border: #3c7760;
+  --surface-success-text: #5ed7a4;
+  --surface-warning-bg: #6a402c;
+  --surface-warning-border: #916436;
+  --surface-warning-text: #f4c14f;
+  --surface-danger-bg: #733b36;
+  --surface-danger-border: #9a5b56;
+  --surface-danger-text: #ffada9;
+  --surface-info-bg: #2d4e67;
+  --surface-info-border: #3d7292;
+  --surface-info-text: #67cdff;
   --surface-teal-bg: #042f2e;
   --surface-teal-border: #134e4a;
   --surface-teal-text: #2dd4bf;
@@ -196,6 +199,31 @@
   --surface-orange-bg: #431407;
   --surface-orange-border: #7c2d12;
   --surface-orange-text: #fb923c;
+
+  /* Run-mix ramp — the fills of a proportional status bar.
+   *
+   * Separate from the `--surface-*-text` tones because a 6px bar is read
+   * differently from a chip: it is told by hue alone, at a size too small to
+   * carry a glyph or a label, so its slices must ALSO separate from each other
+   * in greyscale. These five are spaced at least 1.18:1 apart in relative
+   * luminance — 1.30 in dark, 1.20 in light, where the ramp has less room
+   * before it runs into the paper — and each clears 3:1 against the track, so
+   * the mix stays countable with any form of colour blindness and in a
+   * monochrome screenshot. 1.18 is the floor the gate holds them to.
+   *
+   * Ranked by how much the reader needs to tell them apart: succeeded is
+   * brightest and cancelled quietest, so the two that matter — succeeded and
+   * failed — sit at opposite ends and can never be confused.
+   *
+   * Spacing them by OKLCH lightness does NOT work: that is perceptual, and the
+   * contrast ratio is computed from relative luminance, so an even perceptual
+   * ramp left every pair at 1.1:1. Solved in luminance space instead. */
+  --run-mix-succeeded: #76edb9;
+  --run-mix-waiting: #e9b642;
+  --run-mix-failed: #e1918e;
+  --run-mix-in-flight: #2d9bca;
+  --run-mix-cancelled: #767d90;
+
   --surface-neutral-bg: var(--depth-3);
   --surface-neutral-border: var(--border-subtle);
   --surface-neutral-text: var(--text-muted);
@@ -234,15 +262,22 @@
   --bg-selection: rgba(124, 108, 246, 0.28);
 
   /* Text — neutral */
-  /* Four steps the eye can actually separate: 10.6 / 7.5 / 5.8 / 4.7 against the
+  /* Four steps the eye can actually separate: 10.6 / 7.8 / 6.5 / 5.4 against the
    * L2 card. --text-dim is the faintest tier but it is still TEXT, so it clears
-   * the 4.5:1 body floor rather than only the 3:1 large-text one — asserted in
-   * tokens.test.ts against both the card and the canvas, since the tier is
-   * solved against one surface and rendered on both. */
+   * the 4.5:1 body floor rather than only the 3:1 large-text one.
+   *
+   * Solved against the WHOLE ladder, not against one plane. A faint tier tuned
+   * on the card alone still has to clear the floor on the nested and overlay
+   * planes above it, which carry the modals, the drawers and every dropdown
+   * menu — so both ends meet in the middle: the faint tiers sit high enough for
+   * the overlay, and the planes above the card sit low enough for them. The
+   * card, the chrome and the canvas are fixed points. tokens.test.ts asserts
+   * every tier on every plane, so a retune cannot open a gap on one plane while
+   * looking correct on another. */
   --text-primary: #e3e6ed;
-  --text-secondary: #bec3d0;
-  --text-muted: #a5abbb;
-  --text-dim: #9299ab;
+  --text-secondary: #c2c7d4;
+  --text-muted: #b2b4c7;
+  --text-dim: #9ea5b9;
 
   /* Brand accents — Tangle */
   --brand-primary: #7C6CF6;
@@ -284,6 +319,18 @@
   --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
   --shadow-glow: none;
   --shadow-accent: 0 1px 2px rgba(0, 0, 0, 0.3);
+  /* The lift above --shadow-dropdown, for a surface that covers the page
+     rather than sitting beside it: a drawer, a modal, a floating dock.
+     Two layers — a tight contact shadow plus a wide ambient one.
+     Alone among the shadows this is derived from --hsl-foreground instead of
+     a fixed rgba, so it INVERTS with the theme. That is what makes it work in
+     dark: a black shadow on a dark canvas renders as nothing (see the ladder
+     note at the top of this file), while the foreground is near-white there,
+     so the same declaration reads as a soft halo. One definition therefore
+     serves both themes and the light block does not restate it. */
+  --shadow-overlay:
+    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
+    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
   --shadow-status-running: none;
   --shadow-status-creating: none;
   --shadow-status-error: none;
@@ -485,7 +532,7 @@
   --surface-success-text: #047857;
   --surface-warning-bg: #fffbeb;
   --surface-warning-border: #fde68a;
-  --surface-warning-text: #b45309;
+  --surface-warning-text: #ab4f09;
   --surface-danger-bg: #fff1f2;
   --surface-danger-border: #fecdd3;
   --surface-danger-text: #b91c1c;
@@ -501,6 +548,31 @@
   --surface-orange-bg: #fff7ed;
   --surface-orange-border: #fed7aa;
   --surface-orange-text: #c2410c;
+
+  /* Run-mix ramp — the fills of a proportional status bar.
+   *
+   * Separate from the `--surface-*-text` tones because a 6px bar is read
+   * differently from a chip: it is told by hue alone, at a size too small to
+   * carry a glyph or a label, so its slices must ALSO separate from each other
+   * in greyscale. These five are spaced at least 1.18:1 apart in relative
+   * luminance — 1.30 in dark, 1.20 in light, where the ramp has less room
+   * before it runs into the paper — and each clears 3:1 against the track, so
+   * the mix stays countable with any form of colour blindness and in a
+   * monochrome screenshot. 1.18 is the floor the gate holds them to.
+   *
+   * Ranked by how much the reader needs to tell them apart: succeeded is
+   * brightest and cancelled quietest, so the two that matter — succeeded and
+   * failed — sit at opposite ends and can never be confused.
+   *
+   * Spacing them by OKLCH lightness does NOT work: that is perceptual, and the
+   * contrast ratio is computed from relative luminance, so an even perceptual
+   * ramp left every pair at 1.1:1. Solved in luminance space instead. */
+  --run-mix-succeeded: #3c9b78;
+  --run-mix-waiting: #c16227;
+  --run-mix-failed: #cd342f;
+  --run-mix-in-flight: #00679e;
+  --run-mix-cancelled: #515367;
+
   --surface-neutral-bg: var(--depth-3);
   --surface-neutral-border: var(--border-subtle);
   --surface-neutral-text: var(--text-muted);

package/src/styles/tokens.test.ts

@@ -185,34 +185,179 @@ describe("the faint ink tiers are still TEXT, on every plane they land on", () =
   // surface, so any move in the ladder — lifting the card, softening the canvas,
   // recasting the hue — silently drops them under the floor, and nothing about
   // the result LOOKS wrong: it renders as slightly faint captions that happen to
-  // be unreadable. Every plane is asserted, not just the one each was tuned on.
+  // be unreadable.
+  //
+  // EVERY plane, not just the two a tier is easiest to tune on. Asserting the
+  // canvas and the card alone would leave the nested and overlay planes
+  // unguarded while this test's name still claimed the whole ladder — and those
+  // are the planes that carry a modal, a drawer, a w-80 dashboard panel and four
+  // dropdown menus, so a tier that fails only there fails where the reading
+  // actually happens.
   //
   // Compared hex-to-hex through the MD3 ladder rather than the HSL bridge,
-  // because these tokens ARE hexes; `--md3-surface` and `--md3-surface-container`
-  // are the canvas and the card at the same positions.
+  // because these tokens ARE hexes, and the ladder names each plane at the same
+  // position in both themes.
   const ratioOf = (a: number, b: number) =>
     (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
 
+  /** Every plane the spine paints resting content on, floor to overlay. */
+  const PLANES = [
+    ["canvas", "md3-surface"],
+    ["chrome / field well", "md3-surface-container-low"],
+    ["card", "md3-surface-container"],
+    ["nested / hover", "md3-surface-container-high"],
+    ["overlay", "md3-surface-container-highest"],
+  ] as const;
+
   for (const [theme, spine] of [
     ["dark", DARK],
     ["light", LIGHT],
   ] as const) {
     for (const tier of ["text-dim", "text-muted"] as const) {
-      it(`${theme}: --${tier} clears 4.5:1 on both the card and the canvas`, () => {
+      it(`${theme}: --${tier} clears 4.5:1 on every plane in the ladder`, () => {
         expect(spine, `--${tier} must be defined`).toContain(`--${tier}:`);
         const ink = hexRelativeLuminanceIn(spine, tier);
-        for (const [plane, token] of [
-          ["card", "md3-surface-container"],
-          ["canvas", "md3-surface"],
-        ] as const) {
+        for (const [plane, token] of PLANES) {
           expect(
             ratioOf(ink, hexRelativeLuminanceIn(spine, token)),
-            `--${tier} on the ${plane}`,
+            `--${tier} on the ${plane} (--${token})`,
           ).toBeGreaterThanOrEqual(4.5);
         }
       });
     }
   }
+
+  it("keeps a real STEP between the ink tiers, not merely an order", () => {
+    // A tier that has to clear AA on a lighter plane can always be brightened
+    // until it does — but once it sits within a hair of the tier above it, the
+    // rung has been deleted rather than repaired, and both an ordering check
+    // and a pure contrast check call that a pass.
+    //
+    // 1.2:1 is the floor because that is roughly where two greys on the same
+    // surface stop being separable side by side. The ramp is solved to it, so a
+    // retune that compresses one end reds here instead of quietly flattening.
+    const MIN_TIER_STEP = 1.2;
+    const ratioOf = (a: number, b: number) =>
+      (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    for (const [theme, spine] of [
+      ["dark", DARK],
+      ["light", LIGHT],
+    ] as const) {
+      const tiers = ["text-dim", "text-muted", "text-secondary", "text-primary"];
+      const lums = tiers.map((t) => hexRelativeLuminanceIn(spine, t));
+      for (let i = 1; i < tiers.length; i++) {
+        expect(
+          ratioOf(lums[i], lums[i - 1]),
+          `${theme}: --${tiers[i - 1]} and --${tiers[i]} are too close to read as different tiers`,
+        ).toBeGreaterThanOrEqual(MIN_TIER_STEP);
+      }
+      // Monotonic in the direction the theme recedes: dark quiets by darkening,
+      // light by lightening.
+      const rising = lums.every((l, i) => i === 0 || l > lums[i - 1]);
+      const falling = lums.every((l, i) => i === 0 || l < lums[i - 1]);
+      expect(
+        theme === "dark" ? rising : falling,
+        `${theme}: the ink ramp must move in one direction from dim to primary`,
+      ).toBe(true);
+    }
+  });
+
+  it("keeps a status chip a TINT in light and a RAISED FILL in dark", () => {
+    // The two themes want opposite things from a chip's fill, and treating them
+    // the same is how this got broken once already: a dark-mode rule — "the fill
+    // must separate from the card so the chip reads as a plane" — was applied to
+    // light, where the card is white, so 1.5:1 from it IS a dark grey. Every
+    // contrast floor still passed and every chip turned to mud.
+    //
+    // Light: the fill stays a WASH near paper and the border does the
+    // separating. Dark: the fill is a raised tint that has to lift off the card,
+    // because a dark chip with a near-card fill is just coloured text.
+    const ratioOf = (a: number, b: number) =>
+      (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    const TONES = ["success", "warning", "danger", "info"] as const;
+
+    for (const tone of TONES) {
+      const lightFill = ratioOf(
+        hexRelativeLuminanceIn(LIGHT, `surface-${tone}-bg`),
+        hexRelativeLuminanceIn(LIGHT, "md3-surface-container"),
+      );
+      expect(
+        lightFill,
+        `light --surface-${tone}-bg must stay a tint near paper — the border separates the chip, not the fill`,
+      ).toBeLessThanOrEqual(1.25);
+
+      const darkFill = ratioOf(
+        hexRelativeLuminanceIn(DARK, `surface-${tone}-bg`),
+        hexRelativeLuminanceIn(DARK, "md3-surface-container"),
+      );
+      expect(
+        darkFill,
+        `dark --surface-${tone}-bg must lift off the card, or the chip is only coloured text`,
+      ).toBeGreaterThanOrEqual(1.3);
+    }
+  });
+
+  it("keeps the run-mix ramp countable without colour", () => {
+    // The bar is 6px tall and told by hue alone, so its slices must separate in
+    // GREYSCALE too. Spacing them evenly by OKLCH lightness does not do it —
+    // that is perceptual, while the ratio is computed from relative luminance —
+    // so the ramp is solved in luminance space and pinned here.
+    const RAMP = [
+      "run-mix-succeeded",
+      "run-mix-waiting",
+      "run-mix-failed",
+      "run-mix-in-flight",
+      "run-mix-cancelled",
+    ] as const;
+    const ratioOf = (a: number, b: number) =>
+      (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    // The bar's track is `bg-background-tertiary` -> `--muted`, which is an HSL
+    // bridge token. `--md3-surface-container-high` is the same plane expressed
+    // as a hex, which is what this helper can read.
+    for (const [theme, spine, track] of [
+      ["dark", DARK, "md3-surface-container-high"],
+      ["light", LIGHT, "md3-surface-container-high"],
+    ] as const) {
+      const lums = RAMP.map((t) => hexRelativeLuminanceIn(spine, t));
+      const trackLum = hexRelativeLuminanceIn(spine, track);
+      for (const [i, l] of lums.entries()) {
+        expect(
+          ratioOf(l, trackLum),
+          `${theme}: --${RAMP[i]} against the bar's track`,
+        ).toBeGreaterThanOrEqual(2.9);
+      }
+      for (let i = 1; i < lums.length; i++) {
+        expect(
+          ratioOf(lums[i], lums[i - 1]),
+          `${theme}: --${RAMP[i - 1]} and --${RAMP[i]} are indistinguishable in greyscale`,
+        ).toBeGreaterThanOrEqual(1.18);
+      }
+    }
+  });
+
+  it("keeps every status TEXT legible on the bare page canvas", () => {
+    // Each status text token is solved against its own paired background, and
+    // that pairing is what `StatusPill` guarantees. But the tokens also get used
+    // as bare text — a "required" hint, a warning headline — where the plane
+    // behind them is the page itself, and nothing about that use announces it
+    // has left the pairing. So every tone is held to the body floor on the
+    // canvas as well, and the set stands or falls together rather than one tone
+    // being quietly scoped tighter than its siblings.
+    const ratioOf = (a: number, b: number) =>
+      (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+    for (const [theme, spine] of [
+      ["dark", DARK],
+      ["light", LIGHT],
+    ] as const) {
+      const canvas = hexRelativeLuminanceIn(spine, "md3-surface");
+      for (const tone of ["success", "warning", "danger", "info"] as const) {
+        expect(
+          ratioOf(hexRelativeLuminanceIn(spine, `surface-${tone}-text`), canvas),
+          `${theme}: --surface-${tone}-text on the page canvas`,
+        ).toBeGreaterThanOrEqual(4.5);
+      }
+    }
+  });
 });
 
 describe("input tokens carry two DIFFERENT roles and must not be conflated", () => {