@tangle-network/brand 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.3.0
+
+### Minor Changes
+
+- f3c5262: Add the missing `tangle-dark` named theme. The named set shipped `tangle-light` with no dark sibling, so `data-theme="tangle-dark"` matched no rule and silently fell through to whatever the element inherited — the light spine's values, inside a light-named wrapper. `tangle-dark` now selects the canonical dark spine by name: same indigo family as `tangle-light`, held to the dark contrast discipline, and self-sufficient inside a light-named wrapper (foregrounds and destructive included, so nothing leaks the light values).
+
+## 1.2.0
+
+### Minor Changes
+
+- 2088fb9: Retune the token spine to a neutral-grey surface ladder with indigo as trim rather than as field, in both themes. Surfaces separate by their own fill so a card, a nested panel and an overlay each read as a distinct plane, and the canvas sits off pure black so long reading sessions land away from the glare end of the range.
+
+  Faint text in `Input`, `Textarea`, `StatCard` and `TerminalLine` now takes a dedicated `--text-dim` token instead of a faded stronger one. A translucent foreground renders as its colour composited over the plane behind it, so those hints, subtitles and timestamps measured differently on a card than on the canvas and fell under the 4.5:1 floor on both.
+
+  **Worth a look after upgrading:** in dark mode `--sidebar-background` is now one step BELOW the canvas rather than above it, so the nav reads as chrome the content sits in front of instead of as another raised card. Apps that composited their own surfaces on top of the sidebar assuming it was the lighter plane should give that area a visual pass. Light mode is unchanged — the sidebar is still paper on a grey canvas.
+
 ## 1.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",
@@ -47,9 +47,9 @@
     }
   },
   "devDependencies": {
-    "@storybook/react": "^8.6.18",
+    "@storybook/react": "^10.5.5",
     "@types/react": "^19.0.0",
-    "react": "^19.0.0",
+    "react": "^19.2.8",
     "tsup": "^8.3.5",
     "typescript": "^5.6.0"
   },

package/src/styles/css-test-utils.ts

@@ -18,30 +18,62 @@ function rulesOnly(css: string): string {
 
 /** Extract a rule's body by selector, tolerant of formatting and of nesting. */
 export function blockIn(source: string, selector: string): string {
+  const blocks = blocksIn(source, selector);
+  if (blocks.length === 0) throw new Error(`missing theme block: ${selector}`);
+  return blocks[0];
+}
+
+/**
+ * Every rule body whose selector list ENDS in `selector`, in source order — the
+ * match requires the selector immediately before the `{`, so a selector earlier
+ * in a comma-separated group (`selector, .other {`) is not returned.
+ *
+ * One selector can head MORE than one rule — `[data-theme="tangle-light"]` names
+ * both the shared light-status override group and the theme's own block — so a
+ * first-match read can silently slice the wrong region. Return them all and let
+ * the caller pick (e.g. the one that declares `--hsl-background`).
+ */
+export function blocksIn(source: string, selector: string): string[] {
   // Comments first: a block's own doc-comment routinely spells its selector out,
   // and anchoring on that prose would slice the wrong region — silently, since
   // the result still looks like CSS.
   const css = rulesOnly(source);
   // Tolerate any whitespace between selector and brace — a formatter that closes
   // the gap must not turn a passing suite into a "missing block" error.
-  const open = new RegExp(`${escapeRegex(selector)}\\s*\\{`).exec(css);
-  if (!open) throw new Error(`missing theme block: ${selector}`);
-  const start = open.index;
-
-  // Walk braces to find THIS block's close. Matching the first `}` would end the
-  // block at the first nested rule's close instead (an `@media`, a nested
-  // selector) — and the slice would still look like CSS, so assertions would run
-  // against a truncated region rather than failing. Depth-counting is exact, and
-  // an unterminated block throws instead of returning something plausible.
-  let depth = 0;
-  for (let i = css.indexOf("{", start); i < css.length; i++) {
-    if (css[i] === "{") depth += 1;
-    else if (css[i] === "}") {
-      depth -= 1;
-      if (depth === 0) return css.slice(start, i);
+  const pattern = new RegExp(`${escapeRegex(selector)}\\s*\\{`, "g");
+
+  const blocks: string[] = [];
+  for (const open of css.matchAll(pattern)) {
+    const start = open.index;
+
+    // Walk braces to find THIS block's close. Matching the first `}` would end the
+    // block at the first nested rule's close instead (an `@media`, a nested
+    // selector) — and the slice would still look like CSS, so assertions would run
+    // against a truncated region rather than failing. Depth-counting is exact, and
+    // an unterminated block throws instead of returning something plausible.
+    let depth = 0;
+    let closed = false;
+    for (let i = css.indexOf("{", start); i < css.length; i++) {
+      if (css[i] === "{") depth += 1;
+      else if (css[i] === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          blocks.push(css.slice(start, i));
+          closed = true;
+          break;
+        }
+      }
     }
+    if (!closed) throw new Error(`unterminated theme block: ${selector}`);
   }
-  throw new Error(`unterminated theme block: ${selector}`);
+  return blocks;
+}
+
+/** Read a token's raw declaration value, whitespace-normalized. */
+export function declIn(css: string, token: string): string {
+  const m = css.match(new RegExp(`--${token}:\\s*([^;]+)`));
+  if (!m) throw new Error(`missing token --${token}`);
+  return m[1].trim().replace(/\s+/g, " ");
 }
 
 /** Read an `H S% L%` channel triple. */
@@ -60,6 +92,32 @@ export function hslIn(
 
 type Rgb = [number, number, number];
 
+/**
+ * Read a hex surface token as RGB 0-255.
+ *
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` (alpha is dropped — compositing is a
+ * separate question, answered by `compositeOver`). A token that exists but is not
+ * hex reports exactly that, rather than claiming it is missing.
+ */
+export function hexIn(css: string, token: string): Rgb {
+  const declaration = css.match(new RegExp(`--${token}:\\s*([^;]+)`));
+  if (!declaration) throw new Error(`missing surface --${token}`);
+
+  const value = declaration[1].trim();
+  const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/.exec(value);
+  if (!hex) {
+    throw new Error(`--${token} is not a hex color (found "${value}")`);
+  }
+
+  const digits = hex[1];
+  // #rgb is shorthand for #rrggbb; #rrggbbaa carries an alpha byte we drop.
+  const pairs =
+    digits.length === 3
+      ? [...digits].map((d) => d + d)
+      : [digits.slice(0, 2), digits.slice(2, 4), digits.slice(4, 6)];
+  return pairs.map((p) => Number.parseInt(p, 16)) as Rgb;
+}
+
 /** `H S% L%` → RGB 0-255. */
 export function hslToRgb({
   h,
@@ -120,33 +178,9 @@ export function contrastRatio(a: Rgb, b: Rgb): number {
  * Relative luminance, not HSL lightness: the ladder varies hue and saturation as
  * it rises, and HSL L is not perceptually uniform — two steps can share an L and
  * still read as different brightnesses, so an "is each plane brighter than the one
- * below" assertion made on HSL L would be measuring the wrong thing.
- *
- * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` (alpha is ignored — luminance is a
- * property of the color, not of how much of it you can see through). A token that
- * exists but is not hex reports exactly that, rather than claiming it is missing.
+ * below" assertion made on HSL L would be measuring the wrong thing. Hex parsing
+ * (and its error reporting) is `hexIn`'s.
  */
 export function hexRelativeLuminanceIn(css: string, token: string): number {
-  const declaration = css.match(new RegExp(`--${token}:\\s*([^;]+)`));
-  if (!declaration) throw new Error(`missing surface --${token}`);
-
-  const value = declaration[1].trim();
-  const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/.exec(value);
-  if (!hex) {
-    throw new Error(
-      `--${token} is not a hex color (found "${value}") — luminance is undefined for it`,
-    );
-  }
-
-  const digits = hex[1];
-  // #rgb is shorthand for #rrggbb; #rrggbbaa carries an alpha byte we drop.
-  const pairs =
-    digits.length === 3
-      ? [...digits].map((d) => d + d)
-      : [digits.slice(0, 2), digits.slice(2, 4), digits.slice(4, 6)];
-
-  const [r, g, b] = pairs.map((p) => Number.parseInt(p, 16) / 255);
-  const lin = (c: number) =>
-    c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+  return relativeLuminance(hexIn(css, token));
 }

package/src/styles/named-themes.css

@@ -2,7 +2,8 @@
  * components re-skin automatically because they reference the semantic tokens
  * (bg-card / border-border / surface-container, mapped in theme.css). Apply with
  * data-theme="<name>" on a wrapper (or <html>). The default :root / .dark spine
- * is the neutral "tangle" theme; "<name>-light" scopes are the light variants. */
+ * is the neutral "tangle" theme — also selectable by name as "tangle-dark";
+ * "<name>-light" scopes are the light variants. */
 
 /* Bridge — the actual re-skin mechanism. Tailwind utilities read the --color-*
  * layer (theme.css @theme: `bg-card` → var(--color-card) = hsl(var(--card))).
@@ -166,8 +167,42 @@
   --text-primary: #06231a; --text-secondary: #285048; --text-muted: #5f8472; --text-dim: #82a699;
 }
 
-/* ───────────────────────── Tangle (neutral) — light variant alias ─────────── */
-/* dark = default :root spine; this is its light mode for the showcase. */
+/* ───────────────────────── Tangle (neutral) — the canonical pair ──────────── */
+/* tangle-dark names the default :root/.dark spine explicitly — the values mirror
+ * tokens.css exactly (pinned in named-themes.test.ts). The named scope matters the
+ * moment the attribute would NOT resolve to :root: a dark island inside a
+ * light-named wrapper inherits the light --hsl-* without it, and a theme picker
+ * switching between named themes needs a `tangle-dark` that actually selects. Same
+ * indigo hue family as tangle-light (~239-246), held to the dark discipline —
+ * graphite-indigo neutrals, elevation by lightening, the fill indigo that carries
+ * white (7.4:1) with the bright indigo reserved for accent text. The foreground
+ * and destructive redeclares equal :root standalone, but the block must be
+ * self-sufficient: in the island nesting an omitted token inherits the WRAPPER's
+ * light value (near-black secondary text on the dark secondary measured ~1.5:1).
+ * Status tokens are deliberately not redeclared: the :root dark status palette is
+ * already dark-tuned, same as aubergine/arena. */
+[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-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-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;
+  --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;
+  --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;
+}
+/* Its light mode. */
 [data-theme="tangle-light"] {
   --hsl-background: 240 33% 98%;  --hsl-foreground: 245 32% 14%;
   --hsl-card: 0 0% 100%;          --hsl-card-foreground: 245 32% 14%;

package/src/styles/named-themes.test.ts

@@ -1,7 +1,16 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { blockIn, hslIn } from "./css-test-utils";
+import {
+  blockIn,
+  blocksIn,
+  contrastRatio,
+  declIn,
+  hexIn,
+  hexRelativeLuminanceIn,
+  hslIn,
+  hslToRgb,
+} from "./css-test-utils";
 
 /**
  * The named-theme contract.
@@ -16,6 +25,15 @@ const themes = readFileSync(
   path.resolve(import.meta.dirname, "named-themes.css"),
   "utf8",
 );
+const tokens = readFileSync(
+  path.resolve(import.meta.dirname, "tokens.css"),
+  "utf8",
+);
+
+// The canonical dark spine, anchored on the LAST selector of its multi-selector
+// header (`:root, [data-sandbox-ui], [data-theme="dark"], .dark {`) — the same
+// trick tokens.test.ts uses.
+const CANON = blockIn(tokens, ".dark");
 
 function block(selector: string): string {
   return blockIn(themes, selector);
@@ -69,3 +87,218 @@ describe('named theme: .dark[data-theme="intelligence"]', () => {
     expect(rules).not.toContain('[data-theme="intelligence-light"]');
   });
 });
+
+describe('named theme: [data-theme="tangle-dark"]', () => {
+  const css = block('[data-theme="tangle-dark"]');
+  // `[data-theme="tangle-light"]` heads two rules — the shared light-status
+  // override group AND the theme's own block; the theme block is the one that
+  // declares the spine.
+  const light = blocksIn(themes, '[data-theme="tangle-light"]').find((b) =>
+    b.includes("--hsl-background"),
+  );
+  if (!light) throw new Error('missing theme block: [data-theme="tangle-light"]');
+
+  it("IS the canonical dark spine, named — no drift from tokens.css", () => {
+    // tangle-dark exists so the attribute can NAME the default spine (a dark
+    // island in a light-named wrapper, a picker's explicit selection). If its
+    // values diverge from :root, "tangle dark" becomes two palettes.
+    const hslTokens = [
+      "hsl-background",
+      "hsl-foreground",
+      "hsl-card",
+      "hsl-card-foreground",
+      "hsl-popover",
+      "hsl-popover-foreground",
+      "hsl-primary",
+      "hsl-primary-foreground",
+      "hsl-secondary",
+      "hsl-secondary-foreground",
+      "hsl-muted",
+      "hsl-muted-foreground",
+      "hsl-accent",
+      "hsl-accent-foreground",
+      "hsl-destructive",
+      "hsl-destructive-foreground",
+      "hsl-border",
+      "hsl-input",
+      "hsl-ring",
+    ];
+    for (const token of hslTokens) {
+      expect(hslIn(css, token), `--${token} must equal the :root dark spine`).toEqual(
+        hslIn(CANON, token),
+      );
+    }
+    const hexTokens = [
+      "depth-1",
+      "depth-2",
+      "depth-3",
+      "depth-4",
+      "md3-surface-container-lowest",
+      "md3-surface-container-low",
+      "md3-surface-container",
+      "md3-surface-container-high",
+      "md3-surface-container-highest",
+      "md3-outline-variant",
+      "accent-text",
+      "brand-primary",
+      "brand-glow",
+      "text-primary",
+      "text-secondary",
+      "text-muted",
+      "text-dim",
+    ];
+    for (const token of hexTokens) {
+      expect(hexIn(css, token), `--${token} must equal the :root dark spine`).toEqual(
+        hexIn(CANON, token),
+      );
+    }
+    // Aliased and rgba declarations don't fit hslIn/hexIn — compare them raw.
+    for (const token of [
+      "bg-root",
+      "bg-card",
+      "bg-input",
+      "border-subtle",
+      "border-default",
+      "border-hover",
+    ]) {
+      expect(declIn(css, token), `--${token} must equal the :root dark spine`).toBe(
+        declIn(CANON, token),
+      );
+    }
+  });
+
+  it("shares tangle-light's indigo hue family — same brand, dark register", () => {
+    for (const token of ["hsl-primary", "hsl-ring", "hsl-background"]) {
+      const dark = hslIn(css, token);
+      const lite = hslIn(light, token);
+      expect(
+        Math.abs(dark.h - lite.h),
+        `--${token} hue must sit within 10 of tangle-light's`,
+      ).toBeLessThanOrEqual(10);
+    }
+  });
+
+  it("tints its neutrals with the hue — nothing achromatic", () => {
+    for (const token of [
+      "hsl-background",
+      "hsl-card",
+      "hsl-popover",
+      "hsl-secondary",
+      "hsl-muted",
+      "hsl-accent",
+      "hsl-border",
+      "hsl-input",
+    ]) {
+      const { h, s } = hslIn(css, token);
+      expect(h, `--${token} hue in the indigo band`).toBeGreaterThanOrEqual(220);
+      expect(h, `--${token} hue in the indigo band`).toBeLessThanOrEqual(250);
+      expect(s, `--${token} is hue-tinted, not dead grey`).toBeGreaterThan(5);
+    }
+  });
+
+  it("elevates by lightening, never darkening", () => {
+    const planes = ["depth-1", "depth-2", "depth-3", "depth-4"].map((t) =>
+      hexRelativeLuminanceIn(css, t),
+    );
+    for (let i = 1; i < planes.length; i++) {
+      expect(planes[i], `depth step ${i} must be brighter than the one below`).toBeGreaterThan(
+        planes[i - 1],
+      );
+    }
+    const ladder = ["hsl-background", "hsl-card", "hsl-popover"].map(
+      (t) => hslIn(css, t).l,
+    );
+    for (let i = 1; i < ladder.length; i++) {
+      expect(ladder[i], `step ${i} lightness must rise`).toBeGreaterThan(
+        ladder[i - 1],
+      );
+    }
+  });
+
+  it("holds the dark contrast discipline — AA floors, AAA ink", () => {
+    const canvas = hslToRgb(hslIn(css, "hsl-background"));
+    const card = hslToRgb(hslIn(css, "hsl-card"));
+    const fg = hslToRgb(hslIn(css, "hsl-foreground"));
+    expect(contrastRatio(fg, canvas), "ink on canvas").toBeGreaterThanOrEqual(7);
+    expect(contrastRatio(fg, card), "ink on card").toBeGreaterThanOrEqual(7);
+
+    const muted = hslToRgb(hslIn(css, "hsl-muted-foreground"));
+    expect(contrastRatio(muted, card), "muted ink on card").toBeGreaterThanOrEqual(
+      4.5,
+    );
+
+    const primary = hslToRgb(hslIn(css, "hsl-primary"));
+    const onPrimary = hslToRgb(hslIn(css, "hsl-primary-foreground"));
+    expect(
+      contrastRatio(onPrimary, primary),
+      "the fill indigo carries white",
+    ).toBeGreaterThanOrEqual(4.5);
+
+    // The ring is NON-TEXT: it must clear 3:1 against both planes it sits on.
+    const ring = hslToRgb(hslIn(css, "hsl-ring"));
+    expect(contrastRatio(ring, canvas), "ring on canvas").toBeGreaterThanOrEqual(3);
+    expect(contrastRatio(ring, card), "ring on card").toBeGreaterThanOrEqual(3);
+
+    expect(
+      contrastRatio(hexIn(css, "accent-text"), card),
+      "bright indigo accent text on card",
+    ).toBeGreaterThanOrEqual(4.5);
+
+    // The faintest tier is still TEXT: it clears the body floor on both planes.
+    const dim = hexIn(css, "text-dim");
+    expect(contrastRatio(dim, card), "text-dim on card").toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(dim, canvas), "text-dim on canvas").toBeGreaterThanOrEqual(
+      4.5,
+    );
+  });
+
+  it("is self-sufficient inside a light-named wrapper — the island it exists for", () => {
+    // The feature's stated scenario: tangle-dark nested in a tangle-light
+    // wrapper. The browser composes the two scopes, so a token the island omits
+    // inherits the WRAPPER's light value, not :root's — the light group's
+    // near-black secondary-foreground on the dark secondary measured ~1.5:1
+    // before the block redeclared its foregrounds. Model that cascade: every
+    // tangle-light rule (the shared light group AND the theme block), with the
+    // island's declarations overriding.
+    const wrapper = blocksIn(themes, '[data-theme="tangle-light"]').join("\n");
+    const effective = (token: string) => {
+      const read = (source: string) => {
+        try {
+          return hslIn(source, token);
+        } catch {
+          return null;
+        }
+      };
+      const value = read(css) ?? read(wrapper);
+      if (!value) {
+        throw new Error(`--${token} resolves to nothing inside the island`);
+      }
+      return value;
+    };
+    for (const [fgToken, bgToken] of [
+      ["hsl-secondary-foreground", "hsl-secondary"],
+      ["hsl-accent-foreground", "hsl-accent"],
+      ["hsl-destructive-foreground", "hsl-destructive"],
+    ] as const) {
+      expect(
+        contrastRatio(hslToRgb(effective(fgToken)), hslToRgb(effective(bgToken))),
+        `effective ${fgToken} on ${bgToken}, island inside tangle-light`,
+      ).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+
+  it("keeps the dark-tuned :root status palette instead of redeclaring it", () => {
+    // Same contract as aubergine/arena: dark named themes inherit status from the
+    // dark spine, so there is exactly one dark status palette to tune. What must
+    // be proven is that the inherited pairs pass AA on their dark surfaces.
+    expect(css).not.toMatch(/--surface-(success|warning|danger|info)-/);
+    for (const name of ["success", "warning", "danger", "info"]) {
+      const text = hexIn(CANON, `surface-${name}-text`);
+      const bg = hexIn(CANON, `surface-${name}-bg`);
+      expect(
+        contrastRatio(text, bg),
+        `inherited ${name} status text on its dark surface`,
+      ).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+});

package/src/styles/tokens.css

@@ -1,10 +1,10 @@
 /* Tangle design tokens — the single palette every Tangle surface renders from.
  *
- * The surface ladder carries an indigo cast and steps in even ~4-5% lightness
- * increments, so a card, a nested panel and an overlay each read as a distinct
- * plane by their own fill. A flat, desaturated ladder forces separation onto
- * borders instead, which is what makes an app read as grey and washed out.
- * Light mirrors it: white paper on a tinted canvas, never white-on-white.
+ * The surface ladder is NEUTRAL GREY and the indigo is trim — accent, never
+ * field. It steps in even lightness increments so a card, a nested panel and an
+ * overlay each read as a distinct plane by their own fill, and carries a crisp
+ * hairline (1.6:1 against the card in dark) because shadow does no work on a dark
+ * canvas. Light mirrors it: white paper on a grey canvas, never white-on-white.
  *
  * Apps consume this spine as-is. If a product needs its own accent identity,
  * add a named theme in named-themes.css (`data-theme="<name>"`) — do NOT re-declare
@@ -14,25 +14,47 @@
 /* Dark is the default theme (`:root`/`[data-sandbox-ui]`). It also responds to
  * the standard `[data-theme="dark"]` / `.dark` switch so any consumer can pin or
  * toggle a theme without inventing an ad-hoc `data-sandbox-theme` name. */
+/*
+ * Surfaces are NEUTRAL GREY and the indigo is trim.
+ *
+ * Colour in the surface competes with colour in the accent: on an indigo-cast
+ * ladder the indigo nav pill, link and focus ring are one more indigo thing on
+ * an indigo page, and the eye stops finding them. Neutral planes give the brand
+ * a field to sit on, so a single accent does all the signalling.
+ *
+ * The canvas sits OFF pure black (#151523). A near-black page under near-white
+ * ink is the glare end of the range, and it is the reading surface for long
+ * sessions.
+ *
+ * Elevation is carried by surface lightness plus a hairline that can actually be
+ * seen — a black shadow on a dark canvas renders as nothing, so shadow does no
+ * work here. The hairline is 1.6:1 against the resting card — quiet by design,
+ * enough to state an edge without drawing a box around every panel.
+ */
 :root,
 [data-sandbox-ui],
 [data-theme="dark"],
 .dark {
-  --md3-surface: #0a0a14;                   /* L0 page canvas */
-  --md3-surface-dim: #060610;               /* recessed page */
-  --md3-surface-bright: #232238;
-  --md3-surface-container-lowest: #050509;  /* L-1 terminal/code well */
-  --md3-surface-container-low: #12111f;     /* L1 chrome, field wells */
-  --md3-surface-container: #191826;         /* L2 resting card */
-  --md3-surface-container-high: #221f33;    /* L3 nested / hover */
-  --md3-surface-container-highest: #2c2942; /* L4 overlay */
-  --md3-surface-variant: #2c2942;
-  --md3-on-surface: #fdfdfd;
-  --md3-on-surface-variant: #aaa8b8;
-
-  --md3-primary: #818CF8;
-  --md3-primary-dim: #6366F1;
-  --md3-primary-container: #4F46E5;
+  --md3-surface: #151523;                   /* L0 page canvas */
+  --md3-surface-dim: #0f0f1a;               /* recessed page */
+  --md3-surface-bright: #434365;
+  /* 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)
+   * and the recessed page is grey (#d9d9e6) — a consumer binding to the wrong one
+   * there gets the wrong surface. */
+  --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-on-surface: #e3e6ed;
+  --md3-on-surface-variant: #a5abbb;
+
+  --md3-primary: #A5B4FC;
+  --md3-primary-dim: #7C6CF6;
+  --md3-primary-container: #4C3FC5;
   --md3-on-primary: #ffffff;
   --md3-on-primary-container: #E0E7FF;
   --md3-primary-fixed: #A5AAFC;
@@ -45,8 +67,8 @@
   --md3-on-secondary-container: #E8E5FF;
 
   --md3-tertiary: #10B981;
-  --md3-outline: #4a4965;
-  --md3-outline-variant: #2a293d;
+  --md3-outline: #898da9;
+  --md3-outline-variant: #474a6b;
 
   --md3-error: #ff5277;
   --md3-error-dim: #eb2855;
@@ -55,32 +77,43 @@
   --md3-on-error-container: #ffbdf2;
 
   --md3-inverse-surface: #fdfdfd;
-  --md3-inverse-primary: #4F46E5;
+  --md3-inverse-primary: #4C3FC5;
   --md3-inverse-on-surface: #000000;
-  --md3-surface-tint: #818CF8;
-
-  /* Semantic HSL bridge — the indigo-cast surface ladder */
-  --hsl-background: 240 33% 6%;     /* L0 canvas #0a0a14 */
-  --hsl-foreground: 240 6% 93%;    /* #ececee */
-  --hsl-card: 244 23% 12%;          /* L2 card #191826 */
-  --hsl-card-foreground: 240 6% 93%;
-  --hsl-popover: 247 23% 21%;       /* L4 overlay #2c2942 */
-  --hsl-popover-foreground: 240 6% 93%;
-  --hsl-primary: 239 84% 62%;
+  --md3-surface-tint: #A5B4FC;
+
+  /* Semantic HSL bridge — the neutral-grey surface ladder */
+  --hsl-background: 240 24% 11%;     /* L0 canvas #151523 */
+  /* 92% L, not pure white: near-white ink on the canvas is the glare end of the
+   * range, and the tiers below it need room to separate. 91% holds 10.6:1 on the
+   * card — AAA with headroom — and leaves four ink steps the eye can tell apart. */
+  --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-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: 249 24% 16%;     /* L3 #221f33 */
-  --hsl-secondary-foreground: 240 6% 93%;
-  --hsl-muted: 249 24% 16%;         /* L3 hover well */
-  --hsl-muted-foreground: 240 5% 68%;  /* #a9a9b1 — high enough that the
+  --hsl-secondary: 240 22% 27%;      /* L3 #363654 */
+  --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
      reduced-opacity caption derivatives (/70, /60) still clear the large-text
      contrast floor against the L2 card. */
-  --hsl-accent: 249 24% 16%;        /* neutral hover (indigo lives in accent-surface-strong) */
-  --hsl-accent-foreground: 240 6% 93%;
+  --hsl-accent: 240 22% 27%;         /* 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%;
-  --hsl-border: 243 19.6% 20%;      /* #2a293d = --md3-outline-variant */
-  --hsl-input: 244 29% 9%;          /* recessed field well #12111f */
-  --hsl-ring: 239 84% 67%;
+  /* Quiet on purpose: 1.6:1 against the resting card. Shadow does no work on a
+   * dark canvas, so the hairline is what states where a plane ends. */
+  --hsl-border: 236 20% 35%;         /* #474a6b = --md3-outline-variant */
+  --hsl-input: 240 24% 15%;          /* recessed field well */
+  /* Brighter than --primary on purpose: the ring is NON-TEXT and has to clear
+   * 3:1 against BOTH canvas and card. The fill indigo is tuned to carry white
+   * text instead, so the two cannot be the same value. */
+  --hsl-ring: 233 100% 87%;
   --hsl-success: 160 84% 39%;
   --hsl-warning: 40 94% 56%;
   --hsl-info: 200 88% 56%;
@@ -115,26 +148,26 @@
   --error: var(--hsl-destructive);
   --info: var(--hsl-info);
 
-  /* Sidebar tokens — L1 chrome: one step ABOVE the canvas in lightness, so the
-   * panel reads as its own plane rather than a hole in the page. */
-  --sidebar-background: 244 29% 9%;  /* L1 chrome #12111f */
-  --sidebar-foreground: 240 6% 93%;
-  --sidebar-primary: 239 84% 67%;
+  /* Sidebar tokens — L1 chrome: one step BELOW the canvas here, so the nav reads
+   * as chrome the content sits in front of rather than as another card. */
+  --sidebar-background: 242 26% 8%;   /* L1 chrome #0f0f1a */
+  --sidebar-foreground: 225 22% 91%;
+  --sidebar-primary: 246 54% 51%;
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 249 24% 16%;     /* L3 hover well */
-  --sidebar-accent-foreground: 240 6% 93%;
-  --sidebar-border: 243 19.6% 20%;   /* = --md3-outline-variant */
-  --sidebar-ring: 239 84% 67%;
+  --sidebar-accent: 240 22% 27%;      /* L3 hover well */
+  --sidebar-accent-foreground: 225 22% 91%;
+  --sidebar-border: 236 20% 35%;
+  --sidebar-ring: 233 100% 87%;
 
   /* Depth scale — tracks the MD3 ladder (canvas / card / nested / overlay) */
-  --depth-1: #0a0a14;
-  --depth-2: #191826;
-  --depth-3: #221f33;
-  --depth-4: #2c2942;
+  --depth-1: #151523;
+  --depth-2: #2d2e43;
+  --depth-3: #363654;
+  --depth-4: #434365;
 
   /* Status colors */
   --status-running: #10B981;
-  --status-creating: #9B93F0;
+  --status-creating: #A5B4FC;
   --status-stopped: #FFB800;
   --status-warm: #FF8A4C;
   --status-cold: #4AABFF;
@@ -180,32 +213,39 @@
   --mesh-blue: transparent;
 
   /* Brand gradients — the indigo spark, kept ONLY for the logo mark + send button */
-  --tangle-gradient: linear-gradient(135deg, #6366F1, #818CF8);
-  --tangle-gradient-text: linear-gradient(135deg, #A5AAFC, #818CF8);
-  --accent-gradient-strong: linear-gradient(135deg, #6366F1, #818CF8);
+  --tangle-gradient: linear-gradient(135deg, #4C3FC5, #A5B4FC);
+  --tangle-gradient-text: linear-gradient(135deg, #C7D2FE, #A5B4FC);
+  --accent-gradient-strong: linear-gradient(135deg, #4C3FC5, #7C6CF6);
   /* Accent wells — soft = hover neutral, strong = active/selected row (indigo) */
-  --accent-surface-soft: rgba(255, 255, 255, 0.04);
-  --accent-surface-strong: rgba(129, 140, 248, 0.14);
-  --accent-text: #b9bffb;
+  --accent-surface-soft: rgba(165, 180, 252, 0.07);
+  --accent-surface-strong: rgba(76, 63, 197, 0.30);
+  /* The BRIGHT indigo, and only ever as text: --primary is the fill (it carries
+   * white), and at 6.7:1 on the card this is the one that stays legible as ink. */
+  --accent-text: #A5B4FC;
 
   /* Surfaces — solid fills off the ladder (no radial mesh) */
-  --bg-root: #0a0a14;
+  --bg-root: #151523;
   --bg-dark: var(--depth-1);
   --bg-card: var(--depth-2);
   --bg-elevated: var(--depth-4);
   --bg-section: var(--depth-1);
   --bg-input: hsl(var(--hsl-input));  /* the field well — same color, hex-free */
-  --bg-hover: rgba(255, 255, 255, 0.04);
-  --bg-selection: rgba(129, 140, 248, 0.14);
+  --bg-hover: rgba(165, 180, 252, 0.07);
+  --bg-selection: rgba(124, 108, 246, 0.28);
 
   /* Text — neutral */
-  --text-primary: #ececee;
-  --text-secondary: #c8c8cd;
-  --text-muted: #9a9aa2;
-  --text-dim: #6b6b73;
+  /* Four steps the eye can actually separate: 10.6 / 7.5 / 5.8 / 4.7 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. */
+  --text-primary: #e3e6ed;
+  --text-secondary: #bec3d0;
+  --text-muted: #a5abbb;
+  --text-dim: #9299ab;
 
   /* Brand accents — Tangle */
-  --brand-primary: #6366F1;
+  --brand-primary: #7C6CF6;
   --brand-strong: #2E2A5E;
   --brand-strong-text: #ffffff;
   --brand-strong-text-muted: rgba(255, 255, 255, 0.7);
@@ -217,17 +257,17 @@
   --brand-emerald: #10B981;
 
   /* Borders — neutral hairlines */
-  --border-subtle: rgba(255, 255, 255, 0.05);
-  --border-default: rgba(255, 255, 255, 0.07);
-  --border-hover: rgba(255, 255, 255, 0.12);
-  --border-accent: rgba(129, 140, 248, 0.20);
-  --border-accent-hover: rgba(129, 140, 248, 0.35);
+  --border-subtle: rgba(165, 180, 252, 0.10);
+  --border-default: rgba(165, 180, 252, 0.16);
+  --border-hover: rgba(165, 180, 252, 0.28);
+  --border-accent: rgba(129, 140, 248, 0.35);
+  --border-accent-hover: rgba(129, 140, 248, 0.50);
 
   /* Buttons */
-  --btn-primary-bg: #5B4ED4;
-  --btn-primary-hover: #4F46E5;
+  --btn-primary-bg: #4C3FC5;
+  --btn-primary-hover: #5A50D6;
   --btn-primary-text: #ffffff;
-  --btn-cta-bg: #4F46E5;
+  --btn-cta-bg: #4C3FC5;
   --btn-cta-text: #FFFFFF;
 
   /* Code / runtime syntax */
@@ -342,17 +382,17 @@
    * by shadow and ring, not by fill — which is how light-mode elevation actually
    * reads. Forcing a strictly-darkening ladder here is what produced the
    * white-on-white flatness this palette replaced. Pinned in tokens.test.ts. */
-  --md3-surface: #eceef3;                   /* L0 page canvas — tinted */
-  --md3-surface-dim: #dcdee6;
+  --md3-surface: #e9e9f1;                   /* L0 page canvas — neutral grey, BELOW the wells */
+  --md3-surface-dim: #d9d9e6;
   --md3-surface-bright: #ffffff;
   --md3-surface-container-lowest: #ffffff;  /* insets read as paper */
-  --md3-surface-container-low: #f6f7fa;     /* L1 chrome, field wells — well */
+  --md3-surface-container-low: #f7f7fa;     /* L1 chrome, field wells — well */
   --md3-surface-container: #ffffff;         /* L2 resting card — paper */
-  --md3-surface-container-high: #f1f2f7;    /* L3 nested / hover — well */
+  --md3-surface-container-high: #f2f2f7;    /* L3 nested / hover — well */
   --md3-surface-container-highest: #ffffff; /* L4 overlay — paper + shadow */
-  --md3-surface-variant: #f1f2f7;
-  --md3-on-surface: #191c24;
-  --md3-on-surface-variant: #464858;
+  --md3-surface-variant: #f2f2f7;
+  --md3-on-surface: #2b2c3e;
+  --md3-on-surface-variant: #494b5d;
 
   --md3-primary: #3E349E;
   --md3-primary-dim: #352B88;
@@ -370,8 +410,8 @@
 
   --md3-tertiary: #065F46;
   --md3-tertiary-container: #D1FAE5;
-  --md3-outline: #6B6E8A;
-  --md3-outline-variant: #C7C6D6;
+  --md3-outline: #737696;
+  --md3-outline-variant: #cecfde;
 
   --md3-error: #ba1a1a;
   --md3-error-dim: #93000a;
@@ -384,26 +424,36 @@
   --md3-inverse-on-surface: #f0f1f4;
   --md3-surface-tint: #6366F1;
 
-  /* Semantic HSL bridge — white paper on a tinted canvas */
-  --hsl-background: 223 23% 94%;    /* L0 canvas #eceef3 */
-  --hsl-foreground: 0 0% 5%;        /* #0d0d0d */
+  /* Semantic HSL bridge — white paper on a neutral-grey canvas */
+  --hsl-background: 240 24% 93%;     /* L0 canvas #e9e9f1 */
+  /* Ink, not black. Pure #0d0d0d on white paper measures 19.5:1 — a hair off the
+   * 21:1 ceiling — and that maximum is what reads as glare rather than as
+   * legibility. 20.5% L lands 13.7:1 on the card and 11.4:1 on the canvas: AAA with
+   * headroom in both places, and a step the eye reads as text instead of as a
+   * hole. */
+  --hsl-foreground: 235 18% 20.5%;     /* #2b2c3e */
   --hsl-card: 0 0% 100%;            /* L2 card = white paper */
-  --hsl-card-foreground: 0 0% 5%;
+  --hsl-card-foreground: 235 18% 20.5%;
   --hsl-popover: 0 0% 100%;
-  --hsl-popover-foreground: 0 0% 5%;
-  --hsl-primary: 245 62% 57%;       /* #5B4ED4 light accent */
+  --hsl-popover-foreground: 235 18% 20.5%;
+  --hsl-primary: 246 54% 51%;       /* #4c3fc6 — carries white at 7.4:1 */
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 230 27% 96%;     /* L3 #f1f2f7 */
-  --hsl-secondary-foreground: 0 0% 10%;
-  --hsl-muted: 230 27% 96%;         /* L3 hover well */
-  --hsl-muted-foreground: 240 5% 38%;  /* #5d5d66 text-muted */
-  --hsl-accent: 230 27% 96%;        /* neutral hover */
-  --hsl-accent-foreground: 0 0% 10%;
+  --hsl-secondary: 240 26% 96%;      /* L3 #f2f2f7 */
+  --hsl-secondary-foreground: 235 18% 20.5%;
+  --hsl-muted: 240 26% 96%;          /* L3 hover well */
+  /* 34% L: the shared components fade captions with /70 and /60, and a
+   * translucent foreground renders as the token COMPOSITED over the plane behind
+   * it. Against white paper that compositing is brutal — a lighter value puts the
+   * /60 caption under the 3:1 large-text floor. This holds 3.0:1 there and 8.6:1
+   * at full strength, still a clear step below the 13.7:1 body ink. */
+  --hsl-muted-foreground: 235 12% 32.5%;  /* #494b5d text-muted */
+  --hsl-accent: 240 26% 96%;         /* neutral hover */
+  --hsl-accent-foreground: 235 18% 20.5%;
   --hsl-destructive: 0 72% 41%;
   --hsl-destructive-foreground: 0 0% 100%;
-  --hsl-border: 244 16.3% 80.8%;    /* #c7c6d6 = --md3-outline-variant */
-  --hsl-input: 225 29% 97%;         /* field well #f6f7fa */
-  --hsl-ring: 245 62% 57%;
+  --hsl-border: 238 20% 84%;         /* #cecfde = --md3-outline-variant */
+  --hsl-input: 240 30% 97%;          /* field well */
+  --hsl-ring: 246 54% 51%;
   --hsl-success: 160 84% 30%;
   --hsl-warning: 41 96% 50%;
   --hsl-info: 212 80% 50%;
@@ -411,9 +461,9 @@
   /* depth-2 (card) and depth-4 (elevated) are BOTH paper, on purpose: in light,
    * a popover does not out-lighten a white card — it lifts by shadow. See the
    * ladder note above. */
-  --depth-1: #eceef3;  /* canvas */
+  --depth-1: #e9e9f1;  /* canvas */
   --depth-2: #ffffff;  /* card — paper */
-  --depth-3: #f1f2f7;  /* nested well */
+  --depth-3: #f2f2f7;  /* nested well */
   --depth-4: #ffffff;  /* elevated — paper, separated by shadow */
 
   --status-running: #059669;
@@ -457,20 +507,20 @@
 
   /* Sidebar — light, flat surface + hairline */
   --sidebar-background: 0 0% 100%;     /* white paper */
-  --sidebar-foreground: 0 0% 5%;
-  --sidebar-primary: 245 62% 57%;     /* #5B4ED4 */
+  --sidebar-foreground: 235 18% 20.5%;
+  --sidebar-primary: 246 54% 51%;     /* #4c3fc6 */
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 230 27% 96%;       /* L3 hover well */
-  --sidebar-accent-foreground: 0 0% 10%;
-  --sidebar-border: 244 16.3% 80.8%;   /* = --md3-outline-variant */
-  --sidebar-ring: 245 62% 57%;
+  --sidebar-accent: 240 26% 96%;       /* L3 hover well */
+  --sidebar-accent-foreground: 235 18% 20.5%;
+  --sidebar-border: 238 20% 84%;   /* = --md3-outline-variant */
+  --sidebar-ring: 246 54% 51%;
 
   --mesh-teal: transparent;
   --mesh-violet: transparent;
   --mesh-blue: transparent;
 
   /* Surfaces — flat single-neutral light */
-  --bg-root: #eceef3;
+  --bg-root: #e9e9f1;
   --bg-dark: var(--depth-1);
   --bg-card: var(--depth-2);
   /* Paper, exactly like --bg-card: in light you cannot raise a plane by making it
@@ -481,13 +531,22 @@
   --bg-elevated: var(--depth-4);
   --bg-section: var(--depth-1);
   --bg-input: hsl(var(--hsl-input));  /* the field well — same color, hex-free */
-  --bg-hover: rgba(0, 0, 0, 0.04);
-  --bg-selection: rgba(91, 78, 212, 0.10);
-
-  --text-primary: #0d0d0d;
-  --text-secondary: #2a2a30;
-  --text-muted: #5d5d66;
-  --text-dim: #8e8e98;
+  --bg-hover: rgba(76, 63, 198, 0.06);
+  --bg-selection: rgba(76, 63, 198, 0.16);
+
+  /* Mirrors the dark ramp's spacing: 13.7 / 10.5 / 8.6 / 5.6 against white paper.
+   * Every step carries the 240 cast so the ink belongs to the palette.
+   *
+   * --text-dim is pinned from the CANVAS (#e9e9f1), not the white card: it is
+   * the faintest tier, so the tinted L0 is the surface that binds it, and a
+   * value chosen against paper alone sits under the 4.5:1 body floor there.
+   * 4.6 on the canvas, 5.6 on the card — both floors are asserted in
+   * tokens.test.ts, because a ratio quoted in a comment drifts the moment a
+   * surface moves and nothing catches it. */
+  --text-primary: #2b2c3e;
+  --text-secondary: #3d3e52;
+  --text-muted: #494b5d;
+  --text-dim: #65677b;
 
   --brand-primary: #6366F1;
   --brand-strong: #2E2A5E;
@@ -500,16 +559,16 @@
   --brand-vibrant: #6366F1;
   --brand-emerald: #059669;
 
-  --border-subtle: rgba(0, 0, 0, 0.06);
-  --border-default: rgba(0, 0, 0, 0.08);
-  --border-hover: rgba(0, 0, 0, 0.13);
+  --border-subtle: rgba(60, 52, 140, 0.10);
+  --border-default: rgba(60, 52, 140, 0.14);
+  --border-hover: rgba(60, 52, 140, 0.24);
   --border-accent: rgba(91, 78, 212, 0.18);
   --border-accent-hover: rgba(91, 78, 212, 0.35);
 
-  --btn-primary-bg: #5B4ED4;
-  --btn-primary-hover: #4F46E5;
+  --btn-primary-bg: #4C3FC5;
+  --btn-primary-hover: #5A50D6;
   --btn-primary-text: #ffffff;
-  --btn-cta-bg: #5B4ED4;
+  --btn-cta-bg: #4C3FC5;
   --btn-cta-text: #ffffff;
 
   --code-keyword: #3E349E;
@@ -530,9 +589,9 @@
   --tangle-gradient: linear-gradient(135deg, #4F46E5, #5B4ED4);
   --tangle-gradient-text: linear-gradient(135deg, #4F46E5, #5B4ED4);
   --accent-gradient-strong: linear-gradient(135deg, #4F46E5, #5B4ED4);
-  --accent-surface-soft: rgba(0, 0, 0, 0.04);
-  --accent-surface-strong: rgba(91, 78, 212, 0.10);
-  --accent-text: #4F46E5;
+  --accent-surface-soft: rgba(76, 63, 198, 0.05);
+  --accent-surface-strong: rgba(76, 63, 198, 0.13);
+  --accent-text: #5047eb;
 
   /* Typography — unified on Inter */
   --font-sans: "Inter", "Geist", ui-sans-serif, system-ui, -apple-system, sans-serif;

package/src/styles/tokens.test.ts

@@ -32,17 +32,36 @@ const DARK = blockIn(tokens, ".dark");
 const LIGHT = blockIn(tokens, ".light");
 
 describe("canonical dark spine", () => {
-  it("is indigo-cast, not grey — the canvas carries real saturation", () => {
+  it("keeps the canvas in the brand's hue family, at any strength", () => {
     const bg = hslIn(DARK, "hsl-background");
+    // HUE is the brand constraint and does not move: the greys are cool and sit
+    // in the indigo band, so they belong to the same family as the accent rather
+    // than reading as a foreign neutral pasted underneath it.
     expect(bg.h, "canvas hue sits in the indigo band").toBeGreaterThanOrEqual(
-      235,
+      215,
+    );
+    expect(bg.h).toBeLessThanOrEqual(260);
+    // SATURATION is a taste dial, not a contract. How far the surfaces lean —
+    // near-neutral graphite with the indigo purely in the accents, or a fully
+    // indigo-cast ground — is a live product decision, so the only thing pinned
+    // here is that the canvas is not dead grey. Asserting a band instead makes
+    // this test fail every time that decision is revisited, which tells you
+    // nothing about whether the palette is correct.
+    expect(bg.s, "a colourless canvas has left the brand behind").toBeGreaterThan(
+      5,
+    );
+  });
+
+  it("guards reading comfort at the INK, not at the canvas", () => {
+    // A deep canvas is fine — glare comes from the ratio between ink and ground,
+    // not from the ground alone. So the floor here is loose, and the real guard
+    // is the 16:1 comfort ceiling on body text in contrast.test.ts. Pinning the
+    // canvas instead would forbid a deep spine that is perfectly comfortable
+    // once its ink is tuned.
+    const bg = hslIn(DARK, "hsl-background");
+    expect(bg.l, "an unlit canvas still needs to be a surface").toBeGreaterThan(
+      3,
     );
-    expect(bg.h).toBeLessThanOrEqual(250);
-    // The flat spine this replaced sat at 7%. Anything near that reads grey.
-    expect(
-      bg.s,
-      "a desaturated canvas is the bug, not the design",
-    ).toBeGreaterThan(20);
   });
 
   it("lifts the card off the canvas by fill, not by border", () => {
@@ -101,6 +120,101 @@ describe("muted text stays legible at the opacities the UI actually uses", () =>
   }
 });
 
+describe("the sidebar is its own plane", () => {
+  // Which SIDE of the canvas the nav sits on is a taste call — it is chrome
+  // below the content in dark and paper above it in light, and either reads
+  // fine. What is not a taste call is the two collapsing onto the same value:
+  // the nav would stop being a distinct region and the page would lose the edge
+  // that separates navigation from content, with no border to fall back on.
+  // Pinned as a minimum separation so a retune can move it without erasing it.
+  for (const [theme, spine] of [
+    ["dark", DARK],
+    ["light", LIGHT],
+  ] as const) {
+    it(`${theme}: sidebar and canvas stay separable`, () => {
+      const sidebar = hslIn(spine, "sidebar-background");
+      const canvas = hslIn(spine, "hsl-background");
+      expect(
+        Math.abs(sidebar.l - canvas.l),
+        "sidebar and canvas lightness must not converge",
+      ).toBeGreaterThanOrEqual(2);
+    });
+  }
+});
+
+describe("a hex quoted beside an HSL token is the value that token resolves to", () => {
+  // The spine is authored in HSL, but it is READ in hex — every comment here
+  // annotates a triple with the colour it produces, because `238 20% 22%` tells
+  // a reader nothing. That makes the annotations load-bearing documentation, and
+  // load-bearing documentation that nothing checks is documentation that lies:
+  // retuning a triple leaves the old hex sitting beside it, and the next person
+  // to trust it picks a neighbouring value against a surface that moved.
+  //
+  // Every declaration of the form `--token: H S% L%; /* … #rrggbb … */`, in every
+  // block, not just the two spines.
+  const ANNOTATED =
+    /^[^\S\n]*(--[a-z0-9-]+):\s*([\d.]+)\s+([\d.]+)%\s+([\d.]+)%;[^\S\n]*\/\*([^*]*)\*\//gm;
+
+  const annotated = [...tokens.matchAll(ANNOTATED)].flatMap(
+    ([, token, h, s, l, comment]) =>
+      (comment.match(/#[0-9a-fA-F]{6}/g) ?? []).map((quoted) => ({
+        token,
+        quoted,
+        hsl: { h: Number(h), s: Number(s), l: Number(l) },
+      })),
+  );
+
+  it("finds the annotations to check", () => {
+    // Without this, rewriting a comment into a shape the pattern misses would
+    // empty the suite below and read as a pass.
+    expect(annotated.length).toBeGreaterThanOrEqual(15);
+  });
+
+  for (const { token, quoted, hsl } of annotated) {
+    it(`${token} resolves to ${quoted}`, () => {
+      const actual = `#${hslToRgb(hsl)
+        .map((c) => Math.round(c).toString(16).padStart(2, "0"))
+        .join("")}`;
+      expect(actual).toBe(quoted.toLowerCase());
+    });
+  }
+});
+
+describe("the faint ink tiers are still TEXT, on every plane they land on", () => {
+  // These two tiers are the ones that break. They are solved against a specific
+  // 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.
+  //
+  // 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.
+  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) {
+    for (const tier of ["text-dim", "text-muted"] as const) {
+      it(`${theme}: --${tier} clears 4.5:1 on both the card and the canvas`, () => {
+        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) {
+          expect(
+            ratioOf(ink, hexRelativeLuminanceIn(spine, token)),
+            `--${tier} on the ${plane}`,
+          ).toBeGreaterThanOrEqual(4.5);
+        }
+      });
+    }
+  }
+});
+
 describe("input tokens carry two DIFFERENT roles and must not be conflated", () => {
   // `--input` is shadcn's input BORDER and the Switch off-track: a mid-tone that
   // must stay visible AGAINST a surface. `--hsl-input` / `--bg-input` are the
@@ -129,7 +243,7 @@ describe("input tokens carry two DIFFERENT roles and must not be conflated", ()
 });
 
 describe("canonical light spine", () => {
-  it("is white paper on a TINTED canvas, never white-on-white", () => {
+  it("is white paper on a tinted canvas, never white-on-white", () => {
     const canvas = hslIn(LIGHT, "hsl-background");
     const card = hslIn(LIGHT, "hsl-card");
     expect(card.l, "the card is paper").toBe(100);
@@ -137,10 +251,17 @@ describe("canonical light spine", () => {
       canvas.l,
       "a pure-white canvas gives a white card nothing to lift off",
     ).toBeLessThan(97);
-    expect(
-      canvas.s,
-      "the canvas carries a tint, not flat grey",
-    ).toBeGreaterThan(10);
+    // Mirrors the dark spine exactly: HUE is the brand constraint and is pinned;
+    // saturation is a taste dial and is not. How far the surfaces lean is a live
+    // product decision, so asserting a band here only guarantees this test fails
+    // the next time that decision is revisited.
+    expect(canvas.h, "canvas hue sits in the indigo band").toBeGreaterThanOrEqual(
+      215,
+    );
+    expect(canvas.h).toBeLessThanOrEqual(260);
+    expect(canvas.s, "a colourless canvas has left the brand behind").toBeGreaterThan(
+      5,
+    );
   });
 
   it("ALTERNATES paper and well — light elevation is not a darkening ramp", () => {