@tangle-network/brand 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- 15402db: Ship the indigo surface ladder as the canonical Tangle palette.
+
+  The `:root` spine was a flat, desaturated neutral. Every product app overrode it with its own hand-written palette, so brand's own colors were rendered almost nowhere — and the apps that did inherit them read as grey and washed out, because a flat ladder forces surface separation onto borders instead of fills.
+
+  Both themes now ship the ladder the products actually converged on: an indigo-cast dark scale stepped in even ~4-5% lightness increments, and a light scale of white paper on a tinted canvas rather than white-on-white. Surfaces, depth scale, sidebar and `--bg-root` all move together so the ladder stays coherent.
+
+  Visual change for every consumer. Apps that were overriding the spine should delete those overrides; apps that were inheriting it get the branded look with no code change.
+
+  Also adds a dark-only `intelligence` named theme — a violet surface ramp — and exports the named-theme stylesheet as `./styles/named-themes.css`, so named themes can be imported at all (they shipped, but no export reached them). The name is deliberately not `themes.css`: one letter from the existing `./styles/theme.css` (the Tailwind `@theme` map) is a typo that resolves successfully to the wrong stylesheet. No published version ever exported `./styles/themes.css` — 1.0.0's export map is `./styles/{index,tokens,globals,theme}.css` — so this adds an export rather than renaming a public one, and nothing downstream can break. A named theme re-skins surfaces only; the Tangle accent stays put.
+
+## 1.0.0
+
+### Major Changes
+
+- 0ef3a1a: Graduate `@tangle-network/brand` to stable 1.0.0. The design-token + prose layer is mature and consumed across every app; declaring 1.0 lets its future minors stay within `@tangle-network/ui`'s `^1.x` peer range. Combined with the new `onlyUpdatePeerDependentsWhenOutOfRange` changeset option, this ends the churn where every brand minor force-majored `ui` (5→6→7… all the way to 10). After this one-time coordinated bump, brand token/prose changes no longer re-version `ui` at all — `ui` versions only when its own component code changes.
+
 ## 0.9.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
     "./styles/index.css": "./src/styles/index.css",
     "./styles/tokens.css": "./src/styles/tokens.css",
     "./styles/globals.css": "./src/styles/globals.css",
-    "./styles/theme.css": "./src/styles/theme.css"
+    "./styles/theme.css": "./src/styles/theme.css",
+    "./styles/named-themes.css": "./src/styles/named-themes.css"
   },
   "peerDependencies": {
     "react": ">=18"

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

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { blockIn, hexRelativeLuminanceIn, hslIn } from "./css-test-utils";
+
+/**
+ * The helpers every other suite's correctness rests on.
+ *
+ * Their failure mode is the dangerous one: they return something that still looks
+ * like CSS, so a wrong answer here makes assertions pass or fail against the wrong
+ * text instead of erroring. Each case below is a way that can happen.
+ */
+describe("blockIn", () => {
+  it("anchors on the rule, not on prose that names the selector", () => {
+    const css = `
+/* the .light spine is defined below */
+.dark { --x: 1; }
+.light { --x: 2; }`;
+    expect(blockIn(css, ".light")).toContain("--x: 2");
+  });
+
+  it("closes on THIS block's brace, not the first nested one", () => {
+    const css = `
+.dark {
+  --outer: 1;
+  @media (min-width: 40rem) { --inner: 2; }
+  --after-nested: 3;
+}
+.light { --x: 9; }`;
+    const block = blockIn(css, ".dark");
+    expect(block, "a nested rule must not end the block early").toContain(
+      "--after-nested",
+    );
+    expect(block, "and must not swallow the following rule").not.toContain(
+      "--x: 9",
+    );
+  });
+
+  it("tolerates a missing space before the brace", () => {
+    expect(blockIn(".dark{ --x: 1; }", ".dark")).toContain("--x: 1");
+  });
+
+  it("throws on a missing or unterminated block rather than returning junk", () => {
+    expect(() => blockIn(".dark { --x: 1; }", ".nope")).toThrow(/missing/);
+    expect(() => blockIn(".dark { --x: 1;", ".dark")).toThrow(/unterminated/);
+  });
+});
+
+describe("hexRelativeLuminanceIn", () => {
+  it("reads #rgb, #rrggbb and #rrggbbaa alike", () => {
+    // #fff and #ffffff are the same color; the alpha byte does not change its
+    // luminance.
+    expect(hexRelativeLuminanceIn("--a: #fff;", "a")).toBeCloseTo(1, 10);
+    expect(hexRelativeLuminanceIn("--a: #ffffff;", "a")).toBeCloseTo(1, 10);
+    expect(hexRelativeLuminanceIn("--a: #ffffff80;", "a")).toBeCloseTo(1, 10);
+    expect(hexRelativeLuminanceIn("--a: #000;", "a")).toBeCloseTo(0, 10);
+  });
+
+  it("orders planes by perceived brightness, not by HSL lightness", () => {
+    const canvas = hexRelativeLuminanceIn("--a: #0a0a14;", "a");
+    const card = hexRelativeLuminanceIn("--a: #191826;", "a");
+    expect(card).toBeGreaterThan(canvas);
+  });
+
+  it("says a token is non-hex rather than claiming it is missing", () => {
+    expect(() => hexRelativeLuminanceIn("--a: var(--b);", "a")).toThrow(
+      /not a hex color/,
+    );
+    expect(() => hexRelativeLuminanceIn("--a: #fff;", "b")).toThrow(/missing/);
+  });
+});
+
+describe("hslIn", () => {
+  it("reads an `H S% L%` triple", () => {
+    expect(hslIn("--a: 240 33% 6%;", "a")).toEqual({ h: 240, s: 33, l: 6 });
+  });
+
+  it("throws when the slot is absent", () => {
+    expect(() => hslIn("--a: 240 33% 6%;", "b")).toThrow(/missing HSL slot/);
+  });
+});

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

@@ -0,0 +1,152 @@
+/**
+ * Helpers for asserting on the stylesheets as source text.
+ *
+ * Deliberately NOT a `.test.ts` file: importing one test file from another makes
+ * Vitest register the imported file's top-level suites a second time, in the
+ * importing file's context.
+ */
+
+/** Escape every regex metacharacter, so a selector is matched literally. */
+function escapeRegex(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Strip CSS comments, so a selector named in prose is never mistaken for a rule. */
+function rulesOnly(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Extract a rule's body by selector, tolerant of formatting and of nesting. */
+export function blockIn(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);
+    }
+  }
+  throw new Error(`unterminated theme block: ${selector}`);
+}
+
+/** Read an `H S% L%` channel triple. */
+export function hslIn(
+  css: string,
+  token: string,
+): { h: number; s: number; l: number } {
+  const m = css.match(
+    new RegExp(
+      `--${token}:\\s*(\\d+(?:\\.\\d+)?)\\s+(\\d+(?:\\.\\d+)?)%\\s+(\\d+(?:\\.\\d+)?)%`,
+    ),
+  );
+  if (!m) throw new Error(`missing HSL slot --${token}`);
+  return { h: Number(m[1]), s: Number(m[2]), l: Number(m[3]) };
+}
+
+type Rgb = [number, number, number];
+
+/** `H S% L%` → RGB 0-255. */
+export function hslToRgb({
+  h,
+  s,
+  l,
+}: {
+  h: number;
+  s: number;
+  l: number;
+}): Rgb {
+  const sat = s / 100;
+  const lit = l / 100;
+  const c = (1 - Math.abs(2 * lit - 1)) * sat;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = lit - c / 2;
+  const [r, g, b] =
+    h < 60
+      ? [c, x, 0]
+      : h < 120
+        ? [x, c, 0]
+        : h < 180
+          ? [0, c, x]
+          : h < 240
+            ? [0, x, c]
+            : h < 300
+              ? [x, 0, c]
+              : [c, 0, x];
+  return [(r + m) * 255, (g + m) * 255, (b + m) * 255];
+}
+
+function relativeLuminance([r, g, b]: Rgb): number {
+  const lin = (c: number) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/**
+ * What a translucent foreground actually becomes once the surface behind it shows
+ * through. A `/70` utility does not render the token's color — it renders this.
+ */
+export function compositeOver(fg: Rgb, bg: Rgb, alpha: number): Rgb {
+  return fg.map((c, i) => alpha * c + (1 - alpha) * bg[i]) as Rgb;
+}
+
+/** WCAG contrast ratio between two opaque colors. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+  const [hi, lo] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => y - x,
+  );
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Read a hex surface token as WCAG relative luminance (0-1).
+ *
+ * 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.
+ */
+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);
+}

package/src/styles/index.css

@@ -7,5 +7,5 @@
 
 @import "./tokens.css";
 @import "./theme.css";
-@import "./themes.css";
+@import "./named-themes.css";
 @import "./globals.css";

package/src/styles/{themes.css → named-themes.css}

@@ -187,3 +187,58 @@
   --brand-primary: #6366f1; --brand-glow: #818cf8;
   --text-primary: #15131f; --text-secondary: #3f3a52; --text-muted: #6a6680; --text-dim: #9490a6;
 }
+
+/* ───────────────────── Intelligence — violet surface ramp ────────────────────
+ * A violet retint of the surface ladder (hue ~260-265, saturation tapering as
+ * lightness rises). The brand indigo primary / ring / accent-text are
+ * deliberately NOT overridden: the accent stays Tangle, only the surfaces carry
+ * the product's identity.
+ *
+ * Apply `data-theme="intelligence"` on <html> alongside the `.dark` class.
+ * The selector REQUIRES `.dark` rather than trusting the consumer to swap the
+ * attribute on every mode change: a violet dark ramp left standing over a light
+ * page would repaint every surface. Dark-only is the contract, so the selector —
+ * not the caller — enforces it. There is deliberately no `-light` variant;
+ * light falls through to brand's canonical light spine. */
+.dark[data-theme="intelligence"] {
+  --md3-surface: #0d0a10;
+  --md3-surface-dim: #0a080d;
+  --md3-surface-bright: #2e2936;
+  --md3-surface-container-lowest: #070509;
+  --md3-surface-container-low: #100d15;
+  --md3-surface-container: #14111a;
+  --md3-surface-container-high: #1b1821;
+  --md3-surface-container-highest: #24202b;
+  --md3-surface-variant: #24202b;
+  --md3-on-surface-variant: #aaa6bb;
+
+  --hsl-background: 262 24% 5%;
+  --hsl-card: 262 19% 11%;
+  --hsl-popover: 260 16% 13%;
+  --hsl-secondary: 262 15% 18%;
+  --hsl-muted: 262 17% 15%;
+  --hsl-muted-foreground: 255 12% 62%;
+  --hsl-accent: 262 15% 20%;
+  --hsl-border: 262 12% 28%;
+  --hsl-input: 260 14% 16%;
+
+  /* seated a touch deeper than the canvas so the panel reads as a base plane */
+  --sidebar-background: 264 26% 4%;
+  --sidebar-accent: 262 16% 16%;
+  --sidebar-border: 262 12% 13%;
+
+  --depth-1: #0e0b13;
+  --depth-2: #16131c;
+  --depth-3: #201c28;
+  --depth-4: #2a2533;
+  --bg-elevated: hsl(262 17% 15%);
+  --bg-section: hsl(262 22% 7%);
+  --bg-root:
+    radial-gradient(ellipse 70% 50% at 20% 0%, rgba(129, 99, 241, 0.08), transparent),
+    radial-gradient(ellipse 50% 40% at 80% 10%, rgba(129, 140, 248, 0.06), transparent),
+    linear-gradient(180deg, var(--depth-1), #0d0a12 100%);
+
+  --border-subtle: rgba(120, 108, 158, 0.1);
+  --border-default: rgba(120, 108, 158, 0.18);
+  --border-hover: rgba(120, 108, 158, 0.28);
+}

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

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { blockIn, hslIn } from "./css-test-utils";
+
+/**
+ * The named-theme contract.
+ *
+ * A named theme re-skins the SURFACE ladder and nothing else — the Tangle accent
+ * (primary / ring / accent-text) stays put, so a product carries its identity in
+ * its planes, not by inventing a second brand colour. These assertions live here
+ * rather than in the consuming app because the palette lives here: an app's job
+ * is only to opt in.
+ */
+const themes = readFileSync(
+  path.resolve(import.meta.dirname, "named-themes.css"),
+  "utf8",
+);
+
+function block(selector: string): string {
+  return blockIn(themes, selector);
+}
+
+describe('named theme: .dark[data-theme="intelligence"]', () => {
+  const css = block('.dark[data-theme="intelligence"]');
+
+  it("retints the surface canvas to violet", () => {
+    for (const token of ["background", "card", "popover", "muted", "border"]) {
+      const { h } = hslIn(css, `hsl-${token}`);
+      expect(h, `--hsl-${token} hue`).toBeGreaterThanOrEqual(255);
+      expect(h, `--hsl-${token} hue`).toBeLessThanOrEqual(268);
+    }
+  });
+
+  it("reads as graded depth, not mud: lightness rises, saturation tapers, hue locked", () => {
+    const ladder = ["hsl-background", "hsl-card", "hsl-secondary"].map((t) =>
+      hslIn(css, t),
+    );
+    for (let i = 1; i < ladder.length; i++) {
+      expect(ladder[i].l, `step ${i} lightness must rise`).toBeGreaterThan(
+        ladder[i - 1].l,
+      );
+      expect(
+        ladder[i].s,
+        `step ${i} saturation must not rise as it lightens`,
+      ).toBeLessThanOrEqual(ladder[i - 1].s);
+    }
+  });
+
+  it("never recolors the Tangle accent — surfaces carry the identity, not the brand", () => {
+    for (const token of ["--hsl-primary", "--hsl-ring", "--accent-text"]) {
+      expect(css, `${token} must not be overridden by a named theme`).not.toContain(
+        `${token}:`,
+      );
+    }
+  });
+
+  it("is dark-only — the SELECTOR enforces it, not the caller", () => {
+    // An unscoped `[data-theme="intelligence"]` would repaint every surface with
+    // the violet dark ramp if a consumer left the attribute on while switching to
+    // light. The `.dark` requirement makes that impossible.
+    //
+    // Checked against the RULES, not the raw file: prose in a comment may well
+    // spell the selector out, and a doc edit must not be able to fail this.
+    const rules = themes.replace(/\/\*[\s\S]*?\*\//g, "");
+    expect(rules).toContain('.dark[data-theme="intelligence"]');
+    expect(rules).not.toMatch(/(?<!\.dark)\[data-theme="intelligence"\]/);
+    // No light variant: light falls through to brand's canonical light spine.
+    expect(rules).not.toContain('[data-theme="intelligence-light"]');
+  });
+});

package/src/styles/tokens.css

@@ -1,5 +1,14 @@
-/* Tangle Sandbox UI design tokens */
-/* Brand: warm purple palette, #5B4ED4 primary */
+/* 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.
+ *
+ * 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
+ * these tokens in the app, or its surfaces silently stop tracking the brand. */
 
 /* MD3 surface hierarchy */
 /* Dark is the default theme (`:root`/`[data-sandbox-ui]`). It also responds to
@@ -9,15 +18,15 @@
 [data-sandbox-ui],
 [data-theme="dark"],
 .dark {
-  --md3-surface: #16161f;
-  --md3-surface-dim: #111119;
-  --md3-surface-bright: #2a2940;
-  --md3-surface-container-lowest: #101017;
-  --md3-surface-container-low: #16161f;
-  --md3-surface-container: #1c1b27;
-  --md3-surface-container-high: #232231;
-  --md3-surface-container-highest: #2c2b3d;
-  --md3-surface-variant: #2c2b3d;
+  --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;
 
@@ -37,7 +46,7 @@
 
   --md3-tertiary: #10B981;
   --md3-outline: #4a4965;
-  --md3-outline-variant: #34324a;
+  --md3-outline-variant: #2a293d;
 
   --md3-error: #ff5277;
   --md3-error-dim: #eb2855;
@@ -50,25 +59,27 @@
   --md3-inverse-on-surface: #000000;
   --md3-surface-tint: #818CF8;
 
-  /* Semantic HSL bridge — flat neutral spine (Tangle Quiet) */
-  --hsl-background: 240 7% 9%;     /* #15151a canvas — lifted off pure black */
+  /* Semantic HSL bridge — the indigo-cast surface ladder */
+  --hsl-background: 240 33% 6%;     /* L0 canvas #0a0a14 */
   --hsl-foreground: 240 6% 93%;    /* #ececee */
-  --hsl-card: 240 5% 13%;          /* #1f1f23 surface, clearly above canvas */
+  --hsl-card: 244 23% 12%;          /* L2 card #191826 */
   --hsl-card-foreground: 240 6% 93%;
-  --hsl-popover: 240 5% 17%;       /* #28282d elevated */
+  --hsl-popover: 247 23% 21%;       /* L4 overlay #2c2942 */
   --hsl-popover-foreground: 240 6% 93%;
   --hsl-primary: 239 84% 62%;
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 240 5% 15%;     /* #242428 surface-2 */
+  --hsl-secondary: 249 24% 16%;     /* L3 #221f33 */
   --hsl-secondary-foreground: 240 6% 93%;
-  --hsl-muted: 240 5% 15%;         /* #242428 — neutral hover well */
-  --hsl-muted-foreground: 240 4% 64%;  /* #9c9ca6 text-muted */
-  --hsl-accent: 240 5% 15%;        /* neutral hover (indigo lives in accent-surface-strong) */
+  --hsl-muted: 249 24% 16%;         /* L3 hover well */
+  --hsl-muted-foreground: 240 5% 68%;  /* #a9a9b1 — 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-destructive: 348 74% 48%;
   --hsl-destructive-foreground: 0 0% 100%;
-  --hsl-border: 240 5% 16%;        /* soft edge — fill carries separation, not the line */
-  --hsl-input: 240 5% 15%;
+  --hsl-border: 243 19.6% 20%;      /* #2a293d = --md3-outline-variant */
+  --hsl-input: 244 29% 9%;          /* recessed field well #12111f */
   --hsl-ring: 239 84% 67%;
   --hsl-success: 160 84% 39%;
   --hsl-warning: 40 94% 56%;
@@ -92,6 +103,11 @@
   --destructive: var(--hsl-destructive);
   --destructive-foreground: var(--hsl-destructive-foreground);
   --border: var(--hsl-border);
+  /* shadcn's `--input` is the input BORDER and the Switch's off-track — a
+   * mid-tone that has to stay visible AGAINST a surface. It is deliberately NOT
+   * the field fill: pointing it at the recessed well would tint a border and a
+   * track the same color as the plane behind them, and both would vanish. The
+   * field fill is --hsl-input / --bg-input below. */
   --input: var(--hsl-muted-foreground);
   --ring: var(--hsl-ring);
   --success: var(--hsl-success);
@@ -99,21 +115,22 @@
   --error: var(--hsl-destructive);
   --info: var(--hsl-info);
 
-  /* Sidebar tokens — flat surface + hairline */
-  --sidebar-background: 240 6% 11%;  /* #1a1a1f surface */
+  /* 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-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 240 5% 15%;      /* neutral hover */
+  --sidebar-accent: 249 24% 16%;     /* L3 hover well */
   --sidebar-accent-foreground: 240 6% 93%;
-  --sidebar-border: 240 5% 16%;      /* soft edge */
+  --sidebar-border: 243 19.6% 20%;   /* = --md3-outline-variant */
   --sidebar-ring: 239 84% 67%;
 
-  /* Depth scale — flat neutral spine (Tangle Quiet) */
-  --depth-1: #15151a;
-  --depth-2: #1f1f23;
-  --depth-3: #26262b;
-  --depth-4: #2e2e34;
+  /* Depth scale — tracks the MD3 ladder (canvas / card / nested / overlay) */
+  --depth-1: #0a0a14;
+  --depth-2: #191826;
+  --depth-3: #221f33;
+  --depth-4: #2c2942;
 
   /* Status colors */
   --status-running: #10B981;
@@ -157,7 +174,7 @@
   --glass-border-hover: var(--border-default);
   --glass-blur: 0px;
 
-  /* Mesh glows — quieted to off; chrome is flat in Tangle Quiet */
+  /* Mesh glows — off; depth comes from the ladder, not from glow */
   --mesh-teal: transparent;
   --mesh-violet: transparent;
   --mesh-blue: transparent;
@@ -171,13 +188,13 @@
   --accent-surface-strong: rgba(129, 140, 248, 0.14);
   --accent-text: #b9bffb;
 
-  /* Surfaces — flat single-neutral (no radial mesh) */
-  --bg-root: #15151a;
+  /* Surfaces — solid fills off the ladder (no radial mesh) */
+  --bg-root: #0a0a14;
   --bg-dark: var(--depth-1);
   --bg-card: var(--depth-2);
   --bg-elevated: var(--depth-4);
   --bg-section: var(--depth-1);
-  --bg-input: var(--depth-3);
+  --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);
 
@@ -319,15 +336,21 @@
   /* Light theme — clean professional, warm purple accents */
 
   /* MD3 surface hierarchy */
-  --md3-surface: #f8f9fb;
-  --md3-surface-dim: #d9dae0;
-  --md3-surface-bright: #f8f9fb;
-  --md3-surface-container-lowest: #ffffff;
-  --md3-surface-container-low: #f3f4f7;
-  --md3-surface-container: #edeef2;
-  --md3-surface-container-high: #e7e8ed;
-  --md3-surface-container-highest: #e1e2e8;
-  --md3-surface-variant: #e1e2e8;
+  /* The light ladder ALTERNATES; it is not monotonic, and that is deliberate.
+   * On a tinted canvas, a raised plane is PAPER (white) and a recessed one is a
+   * tinted WELL. So card and overlay are both white and separate from each other
+   * 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-bright: #ffffff;
+  --md3-surface-container-lowest: #ffffff;  /* insets read as paper */
+  --md3-surface-container-low: #f6f7fa;     /* 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-highest: #ffffff; /* L4 overlay — paper + shadow */
+  --md3-surface-variant: #f1f2f7;
   --md3-on-surface: #191c24;
   --md3-on-surface-variant: #464858;
 
@@ -361,34 +384,37 @@
   --md3-inverse-on-surface: #f0f1f4;
   --md3-surface-tint: #6366F1;
 
-  /* Semantic HSL bridge — flat neutral light (Tangle Quiet) */
-  --hsl-background: 0 0% 100%;      /* #ffffff */
+  /* Semantic HSL bridge — white paper on a tinted canvas */
+  --hsl-background: 223 23% 94%;    /* L0 canvas #eceef3 */
   --hsl-foreground: 0 0% 5%;        /* #0d0d0d */
-  --hsl-card: 240 7% 97%;           /* #f7f7f8 surface */
+  --hsl-card: 0 0% 100%;            /* L2 card = white paper */
   --hsl-card-foreground: 0 0% 5%;
   --hsl-popover: 0 0% 100%;
   --hsl-popover-foreground: 0 0% 5%;
   --hsl-primary: 245 62% 57%;       /* #5B4ED4 light accent */
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 240 6% 93%;      /* #ececee surface-2 */
+  --hsl-secondary: 230 27% 96%;     /* L3 #f1f2f7 */
   --hsl-secondary-foreground: 0 0% 10%;
-  --hsl-muted: 240 6% 93%;          /* #ececee neutral hover */
+  --hsl-muted: 230 27% 96%;         /* L3 hover well */
   --hsl-muted-foreground: 240 5% 38%;  /* #5d5d66 text-muted */
-  --hsl-accent: 240 6% 93%;         /* neutral hover */
+  --hsl-accent: 230 27% 96%;        /* neutral hover */
   --hsl-accent-foreground: 0 0% 10%;
   --hsl-destructive: 0 72% 41%;
   --hsl-destructive-foreground: 0 0% 100%;
-  --hsl-border: 240 6% 89%;         /* hairline ≈ rgba(0,0,0,0.08) */
-  --hsl-input: 240 6% 89%;
+  --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-success: 160 84% 30%;
   --hsl-warning: 41 96% 50%;
   --hsl-info: 212 80% 50%;
 
-  --depth-1: #ffffff;
-  --depth-2: #f7f7f8;
-  --depth-3: #ececee;
-  --depth-4: #e3e3e6;
+  /* 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-2: #ffffff;  /* card — paper */
+  --depth-3: #f1f2f7;  /* nested well */
+  --depth-4: #ffffff;  /* elevated — paper, separated by shadow */
 
   --status-running: #059669;
   --status-creating: #3E349E;
@@ -430,13 +456,13 @@
   --surface-neutral-text: var(--text-muted);
 
   /* Sidebar — light, flat surface + hairline */
-  --sidebar-background: 240 7% 97%;   /* #f7f7f8 surface */
+  --sidebar-background: 0 0% 100%;     /* white paper */
   --sidebar-foreground: 0 0% 5%;
   --sidebar-primary: 245 62% 57%;     /* #5B4ED4 */
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 240 6% 93%;       /* neutral hover */
+  --sidebar-accent: 230 27% 96%;       /* L3 hover well */
   --sidebar-accent-foreground: 0 0% 10%;
-  --sidebar-border: 240 6% 89%;       /* hairline */
+  --sidebar-border: 244 16.3% 80.8%;   /* = --md3-outline-variant */
   --sidebar-ring: 245 62% 57%;
 
   --mesh-teal: transparent;
@@ -444,12 +470,17 @@
   --mesh-blue: transparent;
 
   /* Surfaces — flat single-neutral light */
-  --bg-root: #ffffff;
-  --bg-dark: #f7f7f8;
-  --bg-card: #f7f7f8;
-  --bg-elevated: #ffffff;
-  --bg-section: #f7f7f8;
-  --bg-input: #ececee;
+  --bg-root: #eceef3;
+  --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
+   * lighter than white, so an overlay lifts by SHADOW. A consumer that fills with
+   * --bg-elevated and applies no shadow gets no separation from a card — that is
+   * the contract, not an oversight (--hsl-popover is white for the same reason).
+   * Pair it with --shadow-dropdown. */
+  --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);
 

package/src/styles/tokens.test.ts

@@ -0,0 +1,193 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  blockIn,
+  compositeOver,
+  contrastRatio,
+  hexRelativeLuminanceIn,
+  hslIn,
+  hslToRgb,
+} from "./css-test-utils";
+
+/**
+ * The canonical spine's structural contract.
+ *
+ * The whole point of this palette is that a surface separates from the one below
+ * it by its own FILL. A flat, desaturated ladder pushes that job onto borders,
+ * and the app reads grey and washed out — which is the state this replaced. The
+ * numbers are therefore not decoration; they are the contract. These assertions
+ * pin the PROPERTIES rather than the exact values, so a retune stays free but a
+ * collapse back to flat does not.
+ */
+const tokens = readFileSync(
+  path.resolve(import.meta.dirname, "tokens.css"),
+  "utf8",
+);
+
+// Each spine is declared on a multi-selector header
+// (`:root, [data-sandbox-ui], [data-theme="dark"], .dark {`), so anchor on the
+// LAST selector — the one the opening brace actually follows.
+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", () => {
+    const bg = hslIn(DARK, "hsl-background");
+    expect(bg.h, "canvas hue sits in the indigo band").toBeGreaterThanOrEqual(
+      235,
+    );
+    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", () => {
+    const canvas = hslIn(DARK, "hsl-background");
+    const card = hslIn(DARK, "hsl-card");
+    expect(card.l, "the card must be lighter than the canvas").toBeGreaterThan(
+      canvas.l,
+    );
+    expect(
+      card.l - canvas.l,
+      "a <3% step is the flat ladder that forces separation onto borders",
+    ).toBeGreaterThanOrEqual(3);
+  });
+
+  it("defines the accent-TEXT token a named theme is forbidden from recoloring", () => {
+    // named-themes.test.ts asserts no named theme overrides --accent-text. That
+    // assertion is only meaningful if the base spine actually defines it.
+    expect(DARK).toContain("--accent-text:");
+    expect(LIGHT).toContain("--accent-text:");
+  });
+
+  it("steps canvas -> card -> nested -> overlay monotonically upward", () => {
+    const ladder = [
+      "md3-surface",
+      "md3-surface-container",
+      "md3-surface-container-high",
+      "md3-surface-container-highest",
+    ].map((t) => hexRelativeLuminanceIn(DARK, t));
+    for (let i = 1; i < ladder.length; i++) {
+      expect(
+        ladder[i],
+        `elevation step ${i} must be lighter than the plane below it`,
+      ).toBeGreaterThan(ladder[i - 1]);
+    }
+  });
+});
+
+describe("muted text stays legible at the opacities the UI actually uses", () => {
+  // The token is never rendered at full strength in the places that matter: the
+  // shared components fade captions with `/70` and `/60`, and a translucent
+  // foreground does not render the token's color — it renders the token composited
+  // over whatever is behind it. So the contrast that counts is the composited one,
+  // and asserting it here is the difference between a claim and a guarantee.
+  const CARD = hslToRgb(hslIn(DARK, "hsl-card"));
+  const MUTED = hslToRgb(hslIn(DARK, "hsl-muted-foreground"));
+
+  it("clears AA for normal text at full strength", () => {
+    expect(contrastRatio(MUTED, CARD)).toBeGreaterThanOrEqual(4.5);
+  });
+
+  for (const alpha of [0.7, 0.6]) {
+    it(`clears the 3:1 large-text floor at /${alpha * 100}`, () => {
+      const faded = compositeOver(MUTED, CARD, alpha);
+      expect(contrastRatio(faded, CARD)).toBeGreaterThanOrEqual(3);
+    });
+  }
+});
+
+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
+  // recessed field FILL. Pointing `--input` at the fill is a tempting-looking
+  // "fix" that makes every input border and every off-state switch track vanish
+  // into the plane behind it — a legibility bug with no error and no visual clue
+  // beyond "the toggle disappeared". Pinned so it can't happen quietly.
+  it("--input is the border/track token, not the field fill", () => {
+    // The shadcn alias layer is declared ONCE and re-resolves per theme through
+    // the --hsl-* spine, so this is asserted on the file rather than per scope.
+    expect(tokens).toMatch(/--input:\s*var\(--hsl-muted-foreground\)/);
+    expect(
+      tokens,
+      "--input must not resolve to the field well — input borders and off-state switch tracks would disappear into the plane behind them",
+    ).not.toMatch(/--input:\s*var\(--hsl-input\)/);
+  });
+
+  for (const [name, spine] of [
+    ["dark", DARK],
+    ["light", LIGHT],
+  ] as const) {
+    it(`${name}: the field fill is single-sourced from --hsl-input`, () => {
+      expect(spine).toMatch(/--bg-input:\s*hsl\(var\(--hsl-input\)\)/);
+    });
+  }
+});
+
+describe("canonical light spine", () => {
+  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);
+    expect(
+      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);
+  });
+
+  it("ALTERNATES paper and well — light elevation is not a darkening ramp", () => {
+    // Deliberately not monotonic. On a tinted canvas a raised plane is paper and
+    // a recessed one is a tinted well, so the ladder alternates. Pinning it stops
+    // a well-meaning "fix" from forcing a strictly-ordered ramp, which is exactly
+    // what produced the white-on-white flatness this palette replaced.
+    const paper = ["md3-surface-container", "md3-surface-container-highest"];
+    const wells = ["md3-surface-container-low", "md3-surface-container-high"];
+    const canvas = hexRelativeLuminanceIn(LIGHT, "md3-surface");
+
+    for (const t of paper) {
+      expect(hexRelativeLuminanceIn(LIGHT, t), `${t} is paper`).toBe(1);
+    }
+    for (const t of wells) {
+      const l = hexRelativeLuminanceIn(LIGHT, t);
+      expect(l, `${t} is a well — below paper`).toBeLessThan(1);
+      expect(l, `${t} still sits above the canvas`).toBeGreaterThan(canvas);
+    }
+  });
+
+  it("lets the overlay share the card's fill — it lifts by shadow, not lightness", () => {
+    // `--bg-card` (depth-2) and `--bg-elevated` (depth-4) are both paper by design;
+    // the semantic layer agrees (--hsl-card and --hsl-popover are both white). The
+    // separation is the shadow, so a shadow token must exist to carry it.
+    expect(hexRelativeLuminanceIn(LIGHT, "depth-2")).toBe(1);
+    expect(hexRelativeLuminanceIn(LIGHT, "depth-4")).toBe(1);
+    expect(LIGHT, "the overlay's separation depends on this").toMatch(
+      /--shadow-dropdown:/,
+    );
+  });
+
+  it("keeps the light canvas single-sourced — --depth-1 and --md3-surface agree", () => {
+    // Both are the L0 page canvas. Two hex literals for one plane is a divergence
+    // waiting to happen the next time one of them is retuned.
+    const canvasHex = (token: string) =>
+      LIGHT.match(new RegExp(`--${token}:\\s*(#[0-9a-fA-F]{6})`))?.[1];
+    expect(canvasHex("depth-1")).toBe(canvasHex("md3-surface"));
+  });
+
+  it("keeps the derived --bg-* surfaces on the ladder", () => {
+    // Hardcoded hex here is how `bg-card` (→ --hsl-card) and `var(--bg-card)`
+    // drifted into disagreeing about what a card is.
+    for (const token of ["bg-dark", "bg-card", "bg-elevated", "bg-section"]) {
+      expect(LIGHT, `--${token} must derive from the ladder`).toMatch(
+        new RegExp(`--${token}:\\s*var\\(--depth-`),
+      );
+    }
+  });
+});