@tangle-network/brand 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.29.0
+
+### Minor Changes
+
+- 4678ab2: The canonical spine (`:root`, `.dark`, `.light`, `data-theme` `dark`, `light`
+  and `tangle-dark`) has a real surface ladder. `--hsl-raised` is now the spine's
+  L3 plane and `--hsl-raised-2` its L4 plane, instead of both repeating the card,
+  and every adjacent plane and well is at least 4.4 OKLCH L apart (gated in
+  `surface-ladder.test.ts`):
+  
+  - Dark: page `#0a0a14`, card `#191826`, raised `#252237`, raised-2 and popover
+    `#312e47`. A field in a raised card takes the card colour instead of the page's
+    near-black well, and dark cards and menus carry the 1px top highlight
+    (`--edge-highlight`).
+  - Light: page `#eceef3`, card white, raised `#edeff4`, raised-2 white. A field in
+    a raised card is white.
+  
+  `--hsl-secondary` and `--hsl-popover` moved with the ladder (dark `#221f33` to
+  `#252237`, `#2c2942` to `#312e47`; light `#f2f3f8` to `#edeff4`). Named themes
+  other than Hospitality keep their flat ladder.
+  
+  One hairline: `--border-subtle` and `--border-default` now alias `--hsl-border`
+  in the spine, so every divider, card edge and table rule renders one colour. The
+  dark hairline is `#37364a` (1.5:1 on the card, as documented; it measured 1.2:1).
+  `--glass-border-hover` now follows `--border-hover`.
+  
+  The `--font-size-xs`, `-sm`, `-base` and `-lg` tokens now equal Tailwind's
+  `text-xs`, `text-sm`, `text-base` and `text-lg` (12, 14, 16 and 18px; they were
+  11, 12, 15 and 16px), so `sm` means 14px in CSS and in a class. `text-eyebrow`,
+  the `Heading` eyebrow and subsection variants and `.tangle-api-meta` keep their
+  rendered sizes on the new steps. Code that relied on the old values reads
+  `--font-size-xs` for 12px captions and `--font-size-base` for 16px emphasis.
+
 ## 1.28.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -54,7 +54,7 @@ export declare const palettes: {
     readonly canvas: "#eceef3";
     readonly card: "#ffffff";
     readonly well: "#f5f6fa";
-    readonly nested: "#f2f3f8";
+    readonly nested: "#edeff4";
     readonly overlay: "#ffffff";
     readonly deepest: "#ffffff";
     readonly hairline: "#c8c7d6";
@@ -87,10 +87,10 @@ export declare const palettes: {
     readonly canvas: "#0a0a14";
     readonly card: "#191826";
     readonly well: "#11101e";
-    readonly nested: "#221f33";
-    readonly overlay: "#2c2942";
+    readonly nested: "#252237";
+    readonly overlay: "#312e47";
     readonly deepest: "#040408";
-    readonly hairline: "#2a293d";
+    readonly hairline: "#37364a";
     readonly ink: "#e6e6e6";
     readonly inkSecondary: "#c7c7c7";
     readonly inkMuted: "#b5b5b5";

package/dist/index.js

@@ -95,7 +95,7 @@ const palettes = {
 		canvas: "#eceef3",
 		card: "#ffffff",
 		well: "#f5f6fa",
-		nested: "#f2f3f8",
+		nested: "#edeff4",
 		overlay: "#ffffff",
 		deepest: "#ffffff",
 		hairline: "#c8c7d6",
@@ -128,10 +128,10 @@ const palettes = {
 		canvas: "#0a0a14",
 		card: "#191826",
 		well: "#11101e",
-		nested: "#221f33",
-		overlay: "#2c2942",
+		nested: "#252237",
+		overlay: "#312e47",
 		deepest: "#040408",
-		hairline: "#2a293d",
+		hairline: "#37364a",
 		ink: "#e6e6e6",
 		inkSecondary: "#c7c7c7",
 		inkMuted: "#b5b5b5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.28.0",
+  "version": "1.29.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/palette.generated.ts

@@ -43,7 +43,7 @@ export const palettes = {
     canvas: "#eceef3",
     card: "#ffffff",
     well: "#f5f6fa",
-    nested: "#f2f3f8",
+    nested: "#edeff4",
     overlay: "#ffffff",
     deepest: "#ffffff",
     hairline: "#c8c7d6",
@@ -76,10 +76,10 @@ export const palettes = {
     canvas: "#0a0a14",
     card: "#191826",
     well: "#11101e",
-    nested: "#221f33",
-    overlay: "#2c2942",
+    nested: "#252237",
+    overlay: "#312e47",
     deepest: "#040408",
-    hairline: "#2a293d",
+    hairline: "#37364a",
     ink: "#e6e6e6",
     inkSecondary: "#c7c7c7",
     inkMuted: "#b5b5b5",

package/src/styles/legacy-light.css

@@ -1,6 +1,6 @@
 /* GENERATED by scripts/gen-compat.mjs. Do not edit.
  * Source: tokens.css + named-themes.css
- * SHA-256: 2ba9485893147231527707a89a66e3898a9f3bcdce5d5acc6afe07ffcc570d3e
+ * SHA-256: 0a80a683644d15e5e56e938a3094142b9f1a2dd6f3fe136154af4b6bc7c033e0
  * Light-default compatibility; all explicit modes remain canonical.
  */
 :where(:root),
@@ -27,8 +27,8 @@
     --hsl-background: 240 33% 6%;
     --hsl-input: 244 29% 9%;
     --hsl-card: 244 23% 12%;
-    --hsl-secondary: 249 24% 16%;
-    --hsl-popover: 247 23% 21%;
+    --hsl-secondary: 249 24% 17.5%;
+    --hsl-popover: 247 21% 23%;
     --hsl-muted: var(--hsl-secondary);
     --hsl-accent: var(--hsl-secondary);
     --md3-surface-dim: #040408;
@@ -69,11 +69,11 @@
     --md3-on-surface: var(--text-primary);
     --md3-on-surface-variant: var(--text-muted);
     --md3-outline: #8e8e8e;
-    --hsl-border: 243 20% 20%;
+    --hsl-border: 244 16% 25%;
     --md3-outline-variant: hsl(var(--hsl-border));
     --sidebar-border: var(--hsl-border);
-    --border-subtle: rgba(255, 255, 255, 0.10);
-    --border-default: rgba(255, 255, 255, 0.16);
+    --border-subtle: hsl(var(--hsl-border));
+    --border-default: hsl(var(--hsl-border));
     --border-hover: rgba(255, 255, 255, 0.28);
     --hsl-primary: 246 54% 51%;
     --hsl-primary-foreground: 0 0% 100%;
@@ -250,7 +250,7 @@
     --glass-bg: var(--depth-2);
     --glass-bg-strong: var(--depth-3);
     --glass-border: var(--border-subtle);
-    --glass-border-hover: var(--border-default);
+    --glass-border-hover: var(--border-hover);
     --glass-blur: 0px;
     --mesh-teal: transparent;
     --mesh-violet: transparent;
@@ -311,10 +311,10 @@
     --shell-inset-gutter: 0.5rem;
     --transcript-font-size: 1rem;
     --transcript-line-height: var(--line-height-base);
-    --font-size-xs: 0.6875rem;
-    --font-size-sm: 0.75rem;
-    --font-size-base: 0.9375rem;
-    --font-size-lg: 1rem;
+    --font-size-xs: 0.75rem;
+    --font-size-sm: 0.875rem;
+    --font-size-base: 1rem;
+    --font-size-lg: 1.125rem;
     --font-size-xl: 1.25rem;
     --font-size-2xl: 1.5rem;
     --font-size-3xl: 1.875rem;
@@ -408,7 +408,7 @@
     --hsl-background: 223 23% 94%;
     --hsl-input: 225 29% 97%;
     --hsl-card: 0 0% 100%;
-    --hsl-secondary: 230 27% 96%;
+    --hsl-secondary: 228 25% 94.5%;
     --hsl-popover: var(--hsl-card);
     --md3-surface-dim: #dcdee6;
     --md3-surface-container-lowest: hsl(var(--hsl-card));
@@ -423,8 +423,6 @@
     --text-dim: #686868;
     --md3-outline: #787878;
     --hsl-border: 244 16% 81%;
-    --border-subtle: rgba(0, 0, 0, 0.10);
-    --border-default: rgba(0, 0, 0, 0.14);
     --border-hover: rgba(0, 0, 0, 0.24);
     --hsl-ring: var(--hsl-primary);
     --brand-primary: #6366F1;
@@ -558,17 +556,17 @@
 [data-sandbox-ui],
 [data-sandbox-theme],
 [data-theme] {
-    --hsl-raised: var(--hsl-card);
-    --hsl-raised-2: var(--hsl-card);
+    --hsl-raised: var(--hsl-secondary);
+    --hsl-raised-2: var(--hsl-popover);
     --well-page: color-mix(in oklab, hsl(var(--hsl-background)) 70%, black);
     --well-card: var(--well-page);
-    --well-raised: var(--well-page);
-    --well-raised-2: var(--well-page);
+    --well-raised: hsl(var(--hsl-card));
+    --well-raised-2: var(--well-raised);
     --well: var(--well-page);
     --field-border: color-mix(in oklab, hsl(var(--hsl-border)), hsl(var(--hsl-foreground)) 45%);
     --shadow-raised: var(--shadow-card);
     --shadow-well: 0 0 0 0 transparent;
-    --edge-highlight: 0 0 0 0 transparent;
+    --edge-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.06);
     --ix-hover: 0 0 0 1px hsl(var(--hsl-ring) / 0.45), 0 0 0 4px hsl(var(--hsl-ring) / 0.16);
     --ix-hover-border: hsl(var(--hsl-ring) / 0.7);
     --ix-press: 0 0 0 1px hsl(var(--hsl-ring) / 0.95), 0 0 0 4px hsl(var(--hsl-ring) / 0.3);
@@ -589,8 +587,15 @@
     --ix-hover-bg: hsl(var(--hsl-ring) / 0.07);
     --well-page: hsl(var(--hsl-card));
     --well-card: hsl(var(--hsl-background));
-    --well-raised: hsl(var(--hsl-background));
-    --well-raised-2: hsl(var(--hsl-background));
+    --well-raised-2: var(--well-card);
+    --edge-highlight: 0 0 0 0 transparent;
+}
+[data-theme="aubergine"], [data-theme="aubergine-light"], [data-theme="arena"], [data-theme="arena-light"], [data-theme="super"], [data-theme="super-light"], [data-theme="tangle-light"], [data-theme="agents"], [data-theme="agents-light"], [data-theme="website"], [data-theme="intelligence"] {
+    --hsl-raised: var(--hsl-card);
+    --hsl-raised-2: var(--hsl-card);
+    --well-raised: var(--well-card);
+    --well-raised-2: var(--well-card);
+    --edge-highlight: 0 0 0 0 transparent;
 }
 [data-slot="card"] :where(*) {
     --card: var(--hsl-raised);
@@ -746,7 +751,7 @@
     --text-hero: var(--font-size-hero);
     --text-page: var(--font-size-3xl);
     --text-section: var(--font-size-xl);
-    --text-eyebrow: var(--font-size-sm);
+    --text-eyebrow: var(--font-size-xs);
     --text-control-sm: var(--control-text-sm);
     --text-control-md: var(--control-text-md);
     --text-control-lg: var(--control-text-lg);

package/src/styles/named-themes.css

@@ -18,7 +18,7 @@
   --text-hero: var(--font-size-hero);
   --text-page: var(--font-size-3xl);
   --text-section: var(--font-size-xl);
-  --text-eyebrow: var(--font-size-sm);
+  --text-eyebrow: var(--font-size-xs);
   --text-control-sm: var(--control-text-sm);
   --text-control-md: var(--control-text-md);
   --text-control-lg: var(--control-text-lg);

package/src/styles/surface-ladder.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
-import { blockIn, blocksIn, contrastRatio, declIn, hexIn, hslIn, hslToRgb, oklchLightness } from "./css-test-utils";
+import { blockIn, blocksIn, contrastRatio, declIn, hexIn, hslIn, hslToRgb, oklchLightness, resolveIn } from "./css-test-utils";
 
 /**
  * The surface ladder and the interaction palette.
@@ -171,14 +171,13 @@ describe("shared surface context and interaction tokens (tokens.css)", () => {
     }
   });
 
-  it("defaults the raised planes and shadows to the plain spine (wells: the canonical suite below)", () => {
-    expect(declIn(body, "hsl-raised")).toBe("var(--hsl-card)");
-    expect(declIn(body, "hsl-raised-2")).toBe("var(--hsl-card)");
+  it("takes the raised planes from the spine's own L3 and L4 (values: the canonical suite below)", () => {
+    expect(declIn(body, "hsl-raised")).toBe("var(--hsl-secondary)");
+    expect(declIn(body, "hsl-raised-2")).toBe("var(--hsl-popover)");
     expect(declIn(body, "well")).toBe("var(--well-page)");
     expect(declIn(body, "shadow-raised")).toBe("var(--shadow-card)");
     // A shadow token joins a comma list; "none" would void the list.
     expect(declIn(body, "shadow-well")).toBe("0 0 0 0 transparent");
-    expect(declIn(body, "edge-highlight")).toBe("0 0 0 0 transparent");
   });
 
   it("derives the four interaction states from the focus ring at the specified alphas", () => {
@@ -223,19 +222,20 @@ describe("shared surface context and interaction tokens (tokens.css)", () => {
   });
 });
 
-describe("Canonical surface ladder (every theme without its own ladder)", () => {
-  // The spine's shared --bg-input sat +3.1 L above the dark page and -2.6 L under
-  // the white card, so a field read as the plane it was on. The defaults derive
-  // wells and the field border from each theme's own page, card, hairline and ink.
-  const withWells = (selector: string) => {
+describe("Canonical surface ladder (the spine: :root, .dark, .light, dark, light, tangle-dark)", () => {
+  // Drew, 2026-10-26, on a Discovery run page built from the spine: "no color
+  // depth ladder". Raised levels painted the card and every well was one value,
+  // so a card in a card, and a field in it, read as the plane they sat on.
+  const css = rules(tokens);
+  const ladderRule = (selector: string) => {
     const block = blocksIn(tokens, selector).find((b) => /--well-page:/.test(b));
-    if (!block) throw new Error(`no well defaults under ${selector}`);
+    if (!block) throw new Error(`no ladder rule under ${selector}`);
     return block;
   };
-  const defaults = withWells("[data-theme]");
-  const lightDefaults = withWells('[data-theme$="-light"]');
-  const DARK = blockIn(tokens, ".dark");
-  const LIGHT = blockIn(tokens, ".light");
+  const shared = ladderRule("[data-theme]");
+  const lightRule = ladderRule('[data-theme$="-light"]');
+  const DARK = [shared, blockIn(tokens, ".dark")];
+  const LIGHT = [lightRule, shared, blockIn(tokens, ".light")];
 
   type Rgb = [number, number, number];
   const toLab = (rgb: Rgb) => {
@@ -255,37 +255,104 @@ describe("Canonical surface ladder (every theme without its own ladder)", () =>
   };
   /** `color-mix(in oklab, a, b <t>)`. */
   const mix = (a: Rgb, b: Rgb, t: number) => fromLab(toLab(a).map((v, i) => v * (1 - t) + toLab(b)[i] * t));
-  const spine = (css: string, token: string) => hslToRgb(hslIn(css, token)) as Rgb;
+  /** A token as the browser paints it, including the `page + 30% black` well. */
+  const rgb = (sources: string[], token: string): Rgb => {
+    const recess = /^color-mix\(in oklab, hsl\(var\(--([a-z0-9-]+)\)\) (\d+)%, black\)$/.exec(resolveIn(sources, token));
+    if (recess) return mix(rgb(sources, recess[1]!), [0, 0, 0], 1 - Number(recess[2]) / 100);
+    return hexIn(sources, token);
+  };
+  const Lof = (sources: string[], token: string) => oklchLightness(rgb(sources, token));
+
+  const ladder: Array<[role: string, token: string, light: number, dark: number]> = [
+    ["page", "hsl-background", 94.9, 15.0],
+    ["card", "hsl-card", 100, 21.7],
+    ["raised", "hsl-raised", 95.2, 26.6],
+    ["raised-2", "hsl-raised-2", 100, 31.6],
+    ["popover", "hsl-popover", 100, 31.6],
+    ["well on page", "well-page", 100, 10.2],
+    ["well in card", "well-card", 94.9, 10.2],
+    ["well in raised", "well-raised", 100, 21.7],
+    ["well in raised-2", "well-raised-2", 94.9, 21.7],
+    ["hairline", "hsl-border", 83.5, 34.1],
+  ];
+  for (const [role, token, lightL, darkL] of ladder) {
+    it(`${role} (--${token}) lands at L ${lightL} light / ${darkL} dark`, () => {
+      expect(Lof(LIGHT, token)).toBeCloseTo(lightL, 0);
+      expect(Lof(DARK, token)).toBeCloseTo(darkL, 0);
+    });
+  }
 
-  it("declares the derivations this suite measures", () => {
-    expect(declIn(defaults, "well-page")).toBe("color-mix(in oklab, hsl(var(--hsl-background)) 70%, black)");
-    expect(declIn(defaults, "field-border")).toBe("color-mix(in oklab, hsl(var(--hsl-border)), hsl(var(--hsl-foreground)) 45%)");
-    expect(declIn(lightDefaults, "well-page")).toBe("hsl(var(--hsl-card))");
-    for (const token of ["well-card", "well-raised", "well-raised-2"]) {
-      expect(declIn(defaults, token)).toBe("var(--well-page)");
-      expect(declIn(lightDefaults, token)).toBe("hsl(var(--hsl-background))");
+  const steps: Array<[child: string, parent: string]> = [
+    ["hsl-card", "hsl-background"],
+    ["hsl-raised", "hsl-card"],
+    ["hsl-raised-2", "hsl-raised"],
+    ["well-page", "hsl-background"],
+    ["well-card", "hsl-card"],
+    ["well-raised", "hsl-raised"],
+    ["well-raised-2", "hsl-raised-2"],
+  ];
+  it.each([
+    ["light", LIGHT],
+    ["dark", DARK],
+  ])("steps every plane and well at least 4.4 L off its parent in %s", (_mode, sources) => {
+    for (const [child, parent] of steps) {
+      expect(Math.abs(Lof(sources, child) - Lof(sources, parent)), `${child} on ${parent}`).toBeGreaterThanOrEqual(4.4);
     }
   });
 
-  it("recesses the dark well at least 4 L below the page and the card", () => {
-    const well = mix(spine(DARK, "hsl-background"), [0, 0, 0], 0.3);
-    expect(oklchLightness(spine(DARK, "hsl-background")) - oklchLightness(well)).toBeGreaterThanOrEqual(4);
-    expect(oklchLightness(spine(DARK, "hsl-card")) - oklchLightness(well)).toBeGreaterThanOrEqual(10);
+  it("sinks every dark well below the plane it sits on, and lifts dark planes with a top highlight", () => {
+    for (const [well, parent] of steps.filter(([child]) => child.startsWith("well"))) {
+      expect(Lof(DARK, well), `${well} under ${parent}`).toBeLessThan(Lof(DARK, parent));
+    }
+    expect(declIn(shared, "edge-highlight")).toBe("inset 0 1px 0 rgba(255, 255, 255, 0.06)");
+    expect(declIn(lightRule, "edge-highlight")).toBe("0 0 0 0 transparent");
   });
 
-  it("steps the light well 4 L or more off the page and the card", () => {
-    const page = oklchLightness(spine(LIGHT, "hsl-background"));
-    const card = oklchLightness(spine(LIGHT, "hsl-card"));
-    expect(card - page).toBeGreaterThanOrEqual(4);
+  it("draws every line with one hairline: 1.5:1 on the dark card and still seen on the raised plane", () => {
+    for (const sources of [LIGHT, DARK]) {
+      for (const alias of ["border-subtle", "border-default", "md3-outline-variant"]) {
+        expect(hexIn(sources, alias), `--${alias}`).toEqual(hexIn(sources, "hsl-border"));
+      }
+    }
+    expect(contrastRatio(rgb(DARK, "hsl-border"), rgb(DARK, "hsl-card"))).toBeGreaterThanOrEqual(1.45);
+    expect(contrastRatio(rgb(DARK, "hsl-border"), rgb(DARK, "hsl-raised"))).toBeGreaterThanOrEqual(1.25);
+    expect(contrastRatio(rgb(LIGHT, "hsl-border"), rgb(LIGHT, "hsl-background"))).toBeGreaterThanOrEqual(1.4);
   });
 
   it.each([
-    ["dark", () => DARK],
-    ["light", () => LIGHT],
-  ])("draws a field border that clears 3:1 on the card and the page in %s (WCAG 1.4.11)", (_mode, css) => {
-    const border = mix(spine(css(), "hsl-border"), spine(css(), "hsl-foreground"), 0.45);
-    expect(contrastRatio(border, spine(css(), "hsl-card")), "on the card").toBeGreaterThanOrEqual(3);
-    expect(contrastRatio(border, spine(css(), "hsl-background")), "on the page").toBeGreaterThanOrEqual(3);
+    ["dark", DARK],
+    ["light", LIGHT],
+  ])("draws a field border that clears 3:1 on the page, card and raised plane in %s (WCAG 1.4.11)", (_mode, sources) => {
+    expect(declIn(shared, "field-border")).toBe("color-mix(in oklab, hsl(var(--hsl-border)), hsl(var(--hsl-foreground)) 45%)");
+    const border = mix(rgb(sources, "hsl-border"), rgb(sources, "hsl-foreground"), 0.45);
+    for (const plane of ["hsl-background", "hsl-card", "hsl-raised"]) {
+      expect(contrastRatio(border, rgb(sources, plane)), `on --${plane}`).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  it("keeps every named theme with its own planes on the flat ladder until it is tuned", () => {
+    // The canonical ladder is the spine's indigo planes; a named theme that
+    // inherited it would nest an indigo card inside its own card.
+    const flat = css.match(/([^{}]*)\{\s*--hsl-raised:\s*var\(--hsl-card\);[^}]*\}/);
+    expect(flat, "the named-theme flat rule").not.toBeNull();
+    const flatBody = flat![0];
+    for (const [token, value] of [
+      ["hsl-raised", "var(--hsl-card)"],
+      ["hsl-raised-2", "var(--hsl-card)"],
+      ["well-raised", "var(--well-card)"],
+      ["well-raised-2", "var(--well-card)"],
+      ["edge-highlight", "0 0 0 0 transparent"],
+    ]) {
+      expect(declIn(flatBody, token!), `--${token}`).toBe(value);
+    }
+    const names = (selectors: string) => [...selectors.matchAll(/data-theme="([^"]+)"/g)].map((m) => m[1]);
+    const ownPlanes = new Set(
+      [...rules(themes).matchAll(/([^{}]*)\{([^{}]*)\}/g)]
+        .filter((m) => m[2]!.includes("--hsl-background:"))
+        .flatMap((m) => names(m[1]!)),
+    );
+    const tuned = new Set(["hospitality"]);
+    expect(new Set(names(flat![1]!))).toEqual(new Set([...ownPlanes].filter((name) => !tuned.has(name!))));
   });
 });
 

package/src/styles/theme.css

@@ -66,7 +66,7 @@
   --text-hero: var(--font-size-hero);
   --text-page: var(--font-size-3xl);
   --text-section: var(--font-size-xl);
-  --text-eyebrow: var(--font-size-sm);
+  --text-eyebrow: var(--font-size-xs);
 
   /* Control and form type: text-control-sm/md/lg, text-label, text-help. */
   --text-control-sm: var(--control-text-sm);

package/src/styles/tokens.css

@@ -1,10 +1,11 @@
 /* Tangle design tokens — the single palette every Tangle surface renders from.
  *
- * 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.5: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.
+ * The surface ladder is near-neutral grey with a faint indigo cast; the indigo
+ * accent is trim, never field. Each plane steps at least 4.4 OKLCH L off the
+ * plane it sits on (surface-ladder.test.ts), so a card, a card in a card and a
+ * field each read by their own fill. Dark adds a 1.5:1 hairline and a top edge
+ * highlight, because a black shadow on a dark canvas renders as nothing; light
+ * is white paper on a grey canvas, separated by shadow.
  *
  * Each colour is declared ONCE, as a role (a plane, an ink tier, one of four
  * indigos, one ink per status hue), and every other name of that colour is an
@@ -15,26 +16,9 @@
  * 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
  * 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 stays above pure black (#0a0a14, lifted toward indigo). Near-white ink on it is the
- * glare end of the range, so its luminance leaves room for distinct text tiers.
- *
- * 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 about 1.5:1 against the resting card — quiet by design,
- * enough to state an edge without drawing a box around every panel.
- */
 /* Seed a complete baseline on every supported boundary BEFORE mode overrides.
  * Inherited var() aliases are already substituted at their parent; declaring
  * them here lets a nested light/dark/named scope resolve its own palette.
@@ -65,13 +49,14 @@
   /* ── Planes ─────────────────────────────────────────────────────────────
    * One ladder, authored once as HSL channels because the shadcn layer reads
    * hsl(var(--hsl-*)); every hex plane below is derived from it, so a step
-   * moves in one place. L0 is lifted off black toward indigo; L1 chrome sits
-   * below it and the cards step up from it in even increments. */
-  --hsl-background: 240 33% 6%;      /* L0 canvas #0a0a14 */
-  --hsl-input: 244 29% 9%;           /* L1 chrome and field wells #11101e */
-  --hsl-card: 244 23% 12%;           /* L2 resting card #191826 */
-  --hsl-secondary: 249 24% 16%;      /* L3 nested plane and hover well #221f33 */
-  --hsl-popover: 247 23% 21%;        /* L4 overlay #2c2942: a popover carries body text, so it sits on the top plane the ink ramp reaches */
+   * moves in one place. OKLCH L x100: page 15.0, card 21.7, raised 26.6,
+   * raised-2 and overlay 31.6, each at least 4.4 over the plane it sits on.
+   * The page is lifted off black so near-white ink keeps room for its tiers. */
+  --hsl-background: 240 33% 6%;      /* L0 page #0a0a14 */
+  --hsl-input: 244 29% 9%;           /* L1 chrome (the sidebar) and the legacy field fill #11101e */
+  --hsl-card: 244 23% 12%;           /* L2 card #191826 */
+  --hsl-secondary: 249 24% 17.5%;    /* L3 raised: a card in a card, and the hover well #252237 */
+  --hsl-popover: 247 21% 23%;        /* L4 raised-2 and overlay #312e47: a popover carries body text, so it sits on the top plane the ink ramp reaches */
   --hsl-muted: var(--hsl-secondary);
   --hsl-accent: var(--hsl-secondary); /* neutral hover; indigo lives in --accent-surface-strong */
   /* The floor of the ladder: the recessed page and the terminal well share it
@@ -125,15 +110,16 @@
   --md3-on-surface-variant: var(--text-muted);
   --md3-outline: #8e8e8e;
 
-  /* ── Hairlines ──────────────────────────────────────────────────────────
-   * 1.5:1 against the resting card, quiet by design: shadow does no work on a
-   * dark canvas, so the hairline states where a plane ends without drawing a
-   * box around every panel. */
-  --hsl-border: 243 20% 20%;           /* #2a293d */
+  /* ── Hairline ───────────────────────────────────────────────────────────
+   * ONE role for every divider, card edge and table rule, so lines never
+   * disagree. 1.5:1 against the card and 1.3:1 on the raised plane: quiet by
+   * design, it states where a plane ends without boxing every panel.
+   * --border-subtle and --border-default are its older names. */
+  --hsl-border: 244 16% 25%;           /* #37364a */
   --md3-outline-variant: hsl(var(--hsl-border));
   --sidebar-border: var(--hsl-border);
-  --border-subtle: rgba(255, 255, 255, 0.10);
-  --border-default: rgba(255, 255, 255, 0.16);
+  --border-subtle: hsl(var(--hsl-border));
+  --border-default: hsl(var(--hsl-border));
   --border-hover: rgba(255, 255, 255, 0.28);
 
   /* ── Accent: four indigos, each with one job ────────────────────────────
@@ -357,7 +343,7 @@
   --glass-bg: var(--depth-2);
   --glass-bg-strong: var(--depth-3);
   --glass-border: var(--border-subtle);
-  --glass-border-hover: var(--border-default);
+  --glass-border-hover: var(--border-hover);
   --glass-blur: 0px;
 
   /* Mesh glows — off; depth comes from the ladder, not from glow */
@@ -461,12 +447,13 @@
   --transcript-font-size: 1rem;   /* 16px: the chat reading size */
   --transcript-line-height: var(--line-height-base);
 
-  /* Typography scale — override per-app for custom type hierarchy.
-     Components reference these instead of hardcoded pixel values. */
-  --font-size-xs: 0.6875rem;      /* 11px — labels, timestamps */
-  --font-size-sm: 0.75rem;        /* 12px — captions, meta */
-  --font-size-base: 0.9375rem;    /* 15px — message body */
-  --font-size-lg: 1rem;           /* 16px — emphasized text */
+  /* Typography scale. Each --font-size-<step> is Tailwind's text-<step>, so a
+     step name means one size everywhere ("sm" is 14px); 12px is the floor.
+     Components reference these instead of pixel values; an app may override. */
+  --font-size-xs: 0.75rem;        /* 12px — meta, timestamps, eyebrows */
+  --font-size-sm: 0.875rem;       /* 14px — UI text */
+  --font-size-base: 1rem;         /* 16px — reading text */
+  --font-size-lg: 1.125rem;       /* 18px — emphasized text */
   --font-size-xl: 1.25rem;        /* 20px — section title (h2) */
   /* Display tier — page titles, marketing section heads, and heroes.
      Hero sizes are fluid (clamp) so they scale with the viewport without
@@ -589,7 +576,7 @@
   --hsl-background: 223 23% 94%;     /* L0 canvas #eceef3, BELOW the wells */
   --hsl-input: 225 29% 97%;          /* L1 chrome and field wells #f5f6fa */
   --hsl-card: 0 0% 100%;             /* L2 card: paper */
-  --hsl-secondary: 230 27% 96%;      /* L3 nested well #f2f3f8 */
+  --hsl-secondary: 228 25% 94.5%;    /* L3 raised: a card in a card #edeff4, 4.8 L under its paper */
   --hsl-popover: var(--hsl-card);    /* L4 overlay: paper, lifted by shadow, never out-lightening a card */
   --md3-surface-dim: #dcdee6;        /* the recessed page */
   --md3-surface-container-lowest: hsl(var(--hsl-card)); /* insets read as paper */
@@ -609,10 +596,8 @@
   --text-dim: #686868;
   --md3-outline: #787878;
 
-  /* ── Hairlines ──────────────────────────────────────────────────────────── */
+  /* ── Hairline: 1.7:1 on paper, 1.4:1 on the canvas ──────────────────────── */
   --hsl-border: 244 16% 81%;           /* #c8c7d6 */
-  --border-subtle: rgba(0, 0, 0, 0.10);
-  --border-default: rgba(0, 0, 0, 0.14);
   --border-hover: rgba(0, 0, 0, 0.24);
 
   /* ── Accent ─────────────────────────────────────────────────────────────
@@ -807,15 +792,13 @@
  *           level in, --hsl-raised-2 two levels in.
  *   --well  the field fill: --well-page on the page, --well-card in a card,
  *           --well-raised in a card in a card, --well-raised-2 deeper still.
- * A theme that tunes its ladder (Hospitality) sets these per mode. Every other
- * theme gets wells derived from its own page and card, so a field always sits
- * at least 3 OKLCH L points off the plane it is on (agent-app-signoff
- * surface-ladder): dark wells recess below the page (page + 30% black: -4.6 L on
- * the page, -10.9 L in a card on the spine); light wells take the opposite plane
- * (the card on the page, the page in a card: 5 L either way). The old shared
- * --bg-input sat +3.1 above the dark page and -2.6 under the white card. Raised
- * levels still paint the card here: --hsl-raised is an HSL triplet and cannot
- * be derived per theme.
+ * The canonical ladder is the spine's own planes: raised is L3 (--hsl-secondary),
+ * raised-2 is L4 (--hsl-popover), and each well is a plane at least 4.4 OKLCH L
+ * off the level it fills. Dark wells always sit deeper (page + 30% black on the
+ * page and in a card, the card in a raised plane); light wells take the
+ * opposite plane (paper on a grey level, the canvas on paper). Dark raised
+ * planes also carry a 1px top highlight. Hospitality tunes its own ladder; the
+ * other named themes keep a flat one (below) until theirs is tuned.
  *
  * INTERACTION. Four states, all from the focus ring hue (--hsl-ring), so one
  * green or one indigo marks every interactive thing in a theme:
@@ -833,20 +816,20 @@
 [data-sandbox-ui],
 [data-sandbox-theme],
 [data-theme] {
-  --hsl-raised: var(--hsl-card);
-  --hsl-raised-2: var(--hsl-card);
+  --hsl-raised: var(--hsl-secondary);
+  --hsl-raised-2: var(--hsl-popover);
   --well-page: color-mix(in oklab, hsl(var(--hsl-background)) 70%, black);
   --well-card: var(--well-page);
-  --well-raised: var(--well-page);
-  --well-raised-2: var(--well-page);
+  --well-raised: hsl(var(--hsl-card));
+  --well-raised-2: var(--well-raised);
   --well: var(--well-page);
   /* The hairline is 1.5:1 by design; a field edge is non-text UI and needs 3:1.
-   * 45% toward the ink measures 4.0:1 on the spine card in both modes. */
+   * 45% toward the ink clears 4:1 on the spine card in both modes. */
   --field-border: color-mix(in oklab, hsl(var(--hsl-border)), hsl(var(--hsl-foreground)) 45%);
   --shadow-raised: var(--shadow-card);
   /* A shadow token joins a comma list, so "none" would void the whole list. */
   --shadow-well: 0 0 0 0 transparent;
-  --edge-highlight: 0 0 0 0 transparent;
+  --edge-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.06);
   --ix-hover: 0 0 0 1px hsl(var(--hsl-ring) / 0.45), 0 0 0 4px hsl(var(--hsl-ring) / 0.16);
   --ix-hover-border: hsl(var(--hsl-ring) / 0.7);
   --ix-press: 0 0 0 1px hsl(var(--hsl-ring) / 0.95), 0 0 0 4px hsl(var(--hsl-ring) / 0.3);
@@ -870,8 +853,20 @@
   --ix-hover-bg: hsl(var(--hsl-ring) / 0.07);
   --well-page: hsl(var(--hsl-card));
   --well-card: hsl(var(--hsl-background));
-  --well-raised: hsl(var(--hsl-background));
-  --well-raised-2: hsl(var(--hsl-background));
+  --well-raised-2: var(--well-card);
+  --edge-highlight: 0 0 0 0 transparent;
+}
+
+/* Named themes with their own planes keep a flat ladder until each is tuned as
+ * Hospitality was: a nested card paints the card, and its field the card's well. */
+[data-theme="aubergine"], [data-theme="aubergine-light"], [data-theme="arena"], [data-theme="arena-light"],
+[data-theme="super"], [data-theme="super-light"], [data-theme="tangle-light"], [data-theme="agents"],
+[data-theme="agents-light"], [data-theme="website"], [data-theme="intelligence"] {
+  --hsl-raised: var(--hsl-card);
+  --hsl-raised-2: var(--hsl-card);
+  --well-raised: var(--well-card);
+  --well-raised-2: var(--well-card);
+  --edge-highlight: 0 0 0 0 transparent;
 }
 
 /* Surface context: keyed only on the Card primitive's data-slot, never on app