@tangle-network/brand 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.30.0
+
+### Minor Changes
+
+- 29e2a49: One loop period, one shadow colour and one radius ramp.
+  
+  - `--duration-ambient` (2000ms) and `--motion-ambient` (ease-in-out) are the only loop period on a page; the shared `tangle-breathe` keyframe breathes a running mark on them, opacity only. Reduced motion keeps that period, so the essential "still working" signal survives.
+  - `--shadow-color` is the one shadow colour, as HSL channels: black in dark, `220 40% 8%` in light. Every spine shadow, the agents and hospitality themes and system.css draw in it; hospitality's forest-tinted shadow becomes the light shadow colour. The dark `--shadow-overlay` no longer inverts into a white halo.
+  - Radius roles are one ramp: `--radius-tag` 4, `--radius-control` 8, `--radius-card` 12, `--radius-container` 16, `--radius-pill`. `--radius-chip`, `--radius-field` and `--radius-panel` keep their values as aliases of control, card and container.
+
+## 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/README.md

@@ -82,7 +82,7 @@ The Agent App light-default contract is an explicit exception to Brand's default
 /* Import globals.css separately only when the host already intends those globals. */
 ```
 
-Choose this **instead of** `styles`, `tokens.css` and `named-themes.css`; do not stack the two default contracts. The projection contains canonical declarations with a zero-specificity light root default, keeps all explicit mode selectors, and omits `--radius`, which the legacy consumer deliberately leaves to its host. It includes no global component rules, keyframes or automatic ladder/system imports.
+Choose this **instead of** `styles`, `tokens.css` and `named-themes.css`; do not stack the two default contracts. The projection contains canonical declarations with a zero-specificity light root default, keeps all explicit mode selectors, and omits `--radius`, which the legacy consumer deliberately leaves to its host. It includes no global component rules or automatic ladder/system imports; its one keyframe, `tangle-breathe`, runs only where a component names it.
 
 This export is the shared migration boundary, **not a claim that Agent App has already migrated** and not a replacement for that package's entire stylesheet. Its component-specific variables, neutral-ramp API, keyframes and structural rules remain consumer-owned until a separate, explicit migration reconciles them. Remove duplicate shared palette declarations in that migration rather than placing competing global token systems on the same page.
 
@@ -123,9 +123,9 @@ Renderers that cannot read CSS variables (PDF, canvas, WebGL, email, the `theme-
 
 The base surface ladder is the one GTM proved out: dark is indigo-lifted `#0a0a14` / `#191826` / `#221f33` / `#2c2942`; light is a cool `#eceef3` canvas, white paper cards and overlays, and `#f1f2f7` nested wells. The cast stays below 0.1 chroma and ink stays achromatic, so indigo still reads as the interaction accent, not the base field. Existing named products may supply deliberate surface overrides.
 
-Chrome radii are 6/8/10/12px in both base modes; the composer has its own 26px role. Inter (variable, then static) leads body and display stacks, with Geist fallbacks; Geist Mono leads code with JetBrains Mono and system fallbacks. Runtime font/radius registrations retain their public override names; tests keep Tailwind registration defaults aligned with the canonical declarations.
+Chrome radii are 6/8/10/12px in both base modes; the composer has its own 26px role. Role radii are one ramp: `--radius-tag` 4, `--radius-control` 8, `--radius-card` 12, `--radius-container` 16, and `--radius-pill` for every chip; `--radius-chip`, `--radius-field` and `--radius-panel` are older names of control, card and container. Every shadow is drawn in `--shadow-color`, HSL channels that are black in dark and `220 40% 8%` in light; a named theme retints its shadows by setting that one token. Inter (variable, then static) leads body and display stacks, with Geist fallbacks; Geist Mono leads code with JetBrains Mono and system fallbacks. Runtime font/radius registrations retain their public override names; tests keep Tailwind registration defaults aligned with the canonical declarations.
 
-Existing `--transition-*` values are preserved. The shared `--duration-*`, `--ease-*` and `--motion-*` vocabulary comes from the existing Agent App contract. It does not apply animations automatically. Reduced motion zeroes those durations and re-resolves composites at theme boundaries. The adjacent `--interaction-*` roles are elapsed acknowledgment/loading thresholds for existing product instrumentation, not animation durations; reduced motion does not change them.
+Existing `--transition-*` values are preserved. The shared `--duration-*`, `--ease-*` and `--motion-*` vocabulary comes from the existing Agent App contract. It does not apply animations automatically. Reduced motion zeroes those durations and re-resolves composites at theme boundaries. `--duration-ambient` (2000 ms; `--motion-ambient` adds ease-in-out) is the only loop period on a page: a running mark breathes on it with the `tangle-breathe` keyframe, opacity only. Reduced motion keeps that one, because it is the essential "still working" signal and moves nothing. The adjacent `--interaction-*` roles are elapsed acknowledgment/loading thresholds for existing product instrumentation, not animation durations; reduced motion does not change them.
 
 Focus uses `--focus-border`, `--focus-halo`, their danger variants, and `--border-strong`, derived from the local ring/border palette. UI's `focusField` / `focusRing` consume them. `globals.css` supplies the existing fallback for controls without their own focus treatment.
 

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.30.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: 83dde77644ce502513ced146ea7ed7dad93fc736195530c0c2bef82849bf1f21
  * 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;
@@ -272,12 +272,12 @@
     --code-success: var(--surface-success-text);
     --code-comment: var(--syntax-comment);
     --code-error: var(--syntax-error);
-    --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
-    --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
+    --shadow-color: 0 0% 0%;
+    --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.3);
+    --shadow-dropdown: 0 8px 30px hsl(var(--shadow-color) / 0.45);
     --shadow-glow: none;
-    --shadow-accent: 0 1px 2px rgba(0, 0, 0, 0.3);
-    --shadow-overlay: 0 2px 6px hsl(var(--hsl-foreground) / 0.1),
-    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
+    --shadow-accent: var(--shadow-card);
+    --shadow-overlay: 0 2px 6px hsl(var(--shadow-color) / 0.3), 0 16px 40px hsl(var(--shadow-color) / 0.5);
     --scrim: rgb(0 0 0 / 0.4);
     --scrim-strong: rgb(0 0 0 / 0.72);
     --on-media: #ffffff;
@@ -292,9 +292,12 @@
     --radius-full: 999px;
     --radius-composer: 26px;
     --radius-tag: 4px;
-    --radius-chip: 8px;
-    --radius-field: 12px;
-    --radius-panel: 16px;
+    --radius-control: var(--radius-md);
+    --radius-card: var(--radius-xl);
+    --radius-container: 16px;
+    --radius-chip: var(--radius-control);
+    --radius-field: var(--radius-card);
+    --radius-panel: var(--radius-container);
     --radius-cover: 20px;
     --radius-sheet: 24px;
     --control-height: 2.25rem;
@@ -311,10 +314,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;
@@ -377,6 +380,8 @@
     --motion-dismiss: var(--duration-instant) var(--ease-exit);
     --motion-stream: var(--duration-stream) var(--ease-expo);
     --motion-arrive: var(--duration-arrive) var(--ease-expo);
+    --duration-ambient: 2000ms;
+    --motion-ambient: var(--duration-ambient) ease-in-out;
     --interaction-feedback-budget: 100ms;
     --interaction-pending-delay: 200ms;
     --interaction-long-work-delay: 1000ms;
@@ -408,7 +413,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 +428,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;
@@ -535,10 +538,10 @@
     --run-mix-cancelled: #515367;
     --glass-bg-strong: var(--depth-1);
     --code-header-bg: color-mix(in srgb, hsl(var(--hsl-muted)) 50%, transparent);
-    --shadow-card: 0 1px 2px rgba(25, 28, 36, 0.06);
-    --shadow-dropdown: 0 8px 30px rgba(25, 28, 36, 0.10);
-    --shadow-glow: none;
-    --shadow-accent: 0 1px 2px rgba(25, 28, 36, 0.06);
+    --shadow-color: 220 40% 8%;
+    --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.06);
+    --shadow-dropdown: 0 8px 30px hsl(var(--shadow-color) / 0.1);
+    --shadow-overlay: 0 2px 6px hsl(var(--shadow-color) / 0.1), 0 16px 40px hsl(var(--shadow-color) / 0.16);
 }
 :where(:root),
 .dark,
@@ -558,17 +561,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 +592,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);
@@ -635,6 +645,11 @@
     --chart-tier-a: #5b5bd6;
     --chart-tier-s: #272962;
 }
+@keyframes tangle-breathe {
+    50% {
+        opacity: 0.45;
+    }
+}
 @media (prefers-reduced-motion: reduce) {
     :where(:root),
   .dark,
@@ -746,7 +761,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);
@@ -1257,9 +1272,9 @@
     --field-border: #798479;
     --border-accent: rgba(40, 88, 66, 0.20);
     --border-accent-hover: rgba(40, 88, 66, 0.36);
-    --shadow-card: 0 1px 2px rgba(23, 38, 29, 0.07), 0 4px 14px -4px rgba(23, 38, 29, 0.10);
-    --shadow-raised: 0 1px 1px rgba(23, 38, 29, 0.05), 0 2px 6px -2px rgba(23, 38, 29, 0.07);
-    --shadow-well: inset 0 1px 2px rgba(23, 38, 29, 0.06);
+    --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.07), 0 4px 14px -4px hsl(var(--shadow-color) / 0.1);
+    --shadow-raised: 0 1px 1px hsl(var(--shadow-color) / 0.05), 0 2px 6px -2px hsl(var(--shadow-color) / 0.07);
+    --shadow-well: inset 0 1px 2px hsl(var(--shadow-color) / 0.06);
     --edge-highlight: 0 0 0 0 transparent;
     --accent-text: #285842;
     --accent-surface-soft: rgba(40, 88, 66, 0.05);
@@ -1359,9 +1374,9 @@
     --field-border: #939c94;
     --border-accent: rgba(118, 183, 145, 0.35);
     --border-accent-hover: rgba(118, 183, 145, 0.50);
-    --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.45), 0 10px 24px -14px rgba(0, 0, 0, 0.6);
-    --shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.35);
-    --shadow-well: inset 0 1px 2px rgba(0, 0, 0, 0.5);
+    --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.45), 0 10px 24px -14px hsl(var(--shadow-color) / 0.6);
+    --shadow-raised: 0 1px 2px hsl(var(--shadow-color) / 0.35);
+    --shadow-well: inset 0 1px 2px hsl(var(--shadow-color) / 0.5);
     --edge-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.06);
     --accent-text: #b2dbc2;
     --accent-surface-soft: rgba(118, 183, 145, 0.07);
@@ -1443,8 +1458,8 @@
     --border-default: #49474e;
     --border-hover: #625f69;
     --shadow-card: inset 0 0 0 1px rgb(255 255 255 / 0.06);
-    --shadow-dropdown: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px rgb(0 0 0 / 0.5);
-    --shadow-overlay: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px rgb(0 0 0 / 0.6);
+    --shadow-dropdown: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px hsl(var(--shadow-color) / 0.5);
+    --shadow-overlay: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px hsl(var(--shadow-color) / 0.6);
 }
 [data-theme="agents-light"] {
     --bg-card: #ffffff;
@@ -1497,9 +1512,9 @@
     --border-subtle: #dbd8e0;
     --border-default: #d0cdd7;
     --border-hover: #bcbac7;
-    --shadow-card: 0 0 0 1px rgb(33 31 38 / 0.03), 0 2px 6px rgb(33 31 38 / 0.05), 0 4px 8px rgb(33 31 38 / 0.08);
-    --shadow-dropdown: 0 0 0 1px rgb(33 31 38 / 0.04), 0 6px 16px rgb(33 31 38 / 0.12);
-    --shadow-overlay: 0 8px 28px rgb(33 31 38 / 0.28);
+    --shadow-card: 0 0 0 1px hsl(var(--shadow-color) / 0.03), 0 2px 6px hsl(var(--shadow-color) / 0.05), 0 4px 8px hsl(var(--shadow-color) / 0.08);
+    --shadow-dropdown: 0 0 0 1px hsl(var(--shadow-color) / 0.04), 0 6px 16px hsl(var(--shadow-color) / 0.12);
+    --shadow-overlay: 0 8px 28px hsl(var(--shadow-color) / 0.28);
 }
 [data-theme="website"]:where(:not(.dark)) {
     --hsl-background: 240 42.9% 97.3%;

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);
@@ -393,9 +393,9 @@
   --border-hover: rgba(23, 38, 29, 0.28); --border-strong: #798479;
   --field-border: #798479;
   --border-accent: rgba(40, 88, 66, 0.20); --border-accent-hover: rgba(40, 88, 66, 0.36);
-  --shadow-card: 0 1px 2px rgba(23, 38, 29, 0.07), 0 4px 14px -4px rgba(23, 38, 29, 0.10);
-  --shadow-raised: 0 1px 1px rgba(23, 38, 29, 0.05), 0 2px 6px -2px rgba(23, 38, 29, 0.07);
-  --shadow-well: inset 0 1px 2px rgba(23, 38, 29, 0.06);
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.07), 0 4px 14px -4px hsl(var(--shadow-color) / 0.1);
+  --shadow-raised: 0 1px 1px hsl(var(--shadow-color) / 0.05), 0 2px 6px -2px hsl(var(--shadow-color) / 0.07);
+  --shadow-well: inset 0 1px 2px hsl(var(--shadow-color) / 0.06);
   --edge-highlight: 0 0 0 0 transparent;
   --accent-text: #285842;
   --accent-surface-soft: rgba(40, 88, 66, 0.05); --accent-surface-strong: rgba(40, 88, 66, 0.13);
@@ -443,9 +443,9 @@
   --border-hover: rgba(227, 233, 229, 0.28); --border-strong: #939c94;
   --field-border: #939c94;
   --border-accent: rgba(118, 183, 145, 0.35); --border-accent-hover: rgba(118, 183, 145, 0.50);
-  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.45), 0 10px 24px -14px rgba(0, 0, 0, 0.6);
-  --shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.35);
-  --shadow-well: inset 0 1px 2px rgba(0, 0, 0, 0.5);
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.45), 0 10px 24px -14px hsl(var(--shadow-color) / 0.6);
+  --shadow-raised: 0 1px 2px hsl(var(--shadow-color) / 0.35);
+  --shadow-well: inset 0 1px 2px hsl(var(--shadow-color) / 0.5);
   --edge-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.06);
   /* Lifted from #99caad so selected text on a primary tint still clears 4.5:1
    * over the lighter raised plane (L 37.9). */
@@ -517,8 +517,8 @@
   --border-default: #49474e;
   --border-hover: #625f69;
   --shadow-card: inset 0 0 0 1px rgb(255 255 255 / 0.06);
-  --shadow-dropdown: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px rgb(0 0 0 / 0.5);
-  --shadow-overlay: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px rgb(0 0 0 / 0.6);
+  --shadow-dropdown: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px hsl(var(--shadow-color) / 0.5);
+  --shadow-overlay: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px hsl(var(--shadow-color) / 0.6);
 }
 [data-theme="agents-light"] {
   --bg-card: #ffffff;
@@ -571,9 +571,9 @@
   --border-subtle: #dbd8e0;
   --border-default: #d0cdd7;
   --border-hover: #bcbac7;
-  --shadow-card: 0 0 0 1px rgb(33 31 38 / 0.03), 0 2px 6px rgb(33 31 38 / 0.05), 0 4px 8px rgb(33 31 38 / 0.08);
-  --shadow-dropdown: 0 0 0 1px rgb(33 31 38 / 0.04), 0 6px 16px rgb(33 31 38 / 0.12);
-  --shadow-overlay: 0 8px 28px rgb(33 31 38 / 0.28);
+  --shadow-card: 0 0 0 1px hsl(var(--shadow-color) / 0.03), 0 2px 6px hsl(var(--shadow-color) / 0.05), 0 4px 8px hsl(var(--shadow-color) / 0.08);
+  --shadow-dropdown: 0 0 0 1px hsl(var(--shadow-color) / 0.04), 0 6px 16px hsl(var(--shadow-color) / 0.12);
+  --shadow-overlay: 0 8px 28px hsl(var(--shadow-color) / 0.28);
 }
 /* agents:end */
 

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

@@ -301,7 +301,7 @@ for (const [name, mode] of [
       it("is a white page whose cards separate by shadow", () => {
         expect(declIn(css, "hsl-background")).toBe("0 0% 100%");
         expect(declIn(css, "hsl-card")).toBe("0 0% 100%");
-        expect(declIn(css, "shadow-card")).toMatch(/rgb\(/);
+        expect(declIn(css, "shadow-card")).toMatch(/hsl\(var\(--shadow-color\)/);
       });
     }
   });

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/system.css

@@ -140,12 +140,15 @@
    * action. White text passes on every stop (5.37, 5.39 and 5.18:1). */
   --cta: linear-gradient(90deg, #5b5bd6 0%, #6e56cf 55%, #8e4ec6 100%);
   --cta-hover: linear-gradient(90deg, #5151cd 0%, #654dc4 55%, #8347b9 100%);
-  /* Radius by role. The numeric --radius-sm..xl scale is unchanged, so no
-   * existing surface re-rounds; new surfaces pick the role they play. */
+  /* Radius by role, the tokens.css ramp: tag 4, control 8, card 12,
+   * container 16, pill. Chip, field and panel are the older names. */
   --radius-tag: 4px;
-  --radius-chip: 8px;
-  --radius-field: 12px;
-  --radius-panel: 16px;
+  --radius-control: 8px;
+  --radius-card: 12px;
+  --radius-container: 16px;
+  --radius-chip: var(--radius-control);
+  --radius-field: var(--radius-card);
+  --radius-panel: var(--radius-container);
   --radius-cover: 20px;
   --radius-sheet: 24px;
   --radius-pill: 999px;
@@ -191,10 +194,11 @@
   --text-figure--line-height: 2.75rem;
   --text-figure--letter-spacing: -0.02em;
   --text-figure--font-weight: 600;
+  --shadow-color: 0 0% 0%;
   /* Elevation. In dark, a white hairline states the edge; only floating layers cast a shadow. */
   --shadow-1: inset 0 0 0 1px rgb(255 255 255 / 0.06);
-  --shadow-2: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px rgb(0 0 0 / 0.5);
-  --shadow-3: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px rgb(0 0 0 / 0.6);
+  --shadow-2: inset 0 0 0 1px rgb(255 255 255 / 0.08), 0 8px 24px hsl(var(--shadow-color) / 0.5);
+  --shadow-3: inset 0 0 0 1px rgb(255 255 255 / 0.1), 0 16px 48px hsl(var(--shadow-color) / 0.6);
   --shadow-card: var(--shadow-1);
   --shadow-dropdown: var(--shadow-2);
   --shadow-overlay: var(--shadow-3);
@@ -332,12 +336,15 @@
    * action. White text passes on every stop (5.37, 5.39 and 5.18:1). */
   --cta: linear-gradient(90deg, #5b5bd6 0%, #6e56cf 55%, #8e4ec6 100%);
   --cta-hover: linear-gradient(90deg, #5151cd 0%, #654dc4 55%, #8347b9 100%);
-  /* Radius by role. The numeric --radius-sm..xl scale is unchanged, so no
-   * existing surface re-rounds; new surfaces pick the role they play. */
+  /* Radius by role, the tokens.css ramp: tag 4, control 8, card 12,
+   * container 16, pill. Chip, field and panel are the older names. */
   --radius-tag: 4px;
-  --radius-chip: 8px;
-  --radius-field: 12px;
-  --radius-panel: 16px;
+  --radius-control: 8px;
+  --radius-card: 12px;
+  --radius-container: 16px;
+  --radius-chip: var(--radius-control);
+  --radius-field: var(--radius-card);
+  --radius-panel: var(--radius-container);
   --radius-cover: 20px;
   --radius-sheet: 24px;
   --radius-pill: 999px;
@@ -383,10 +390,11 @@
   --text-figure--line-height: 2.75rem;
   --text-figure--letter-spacing: -0.02em;
   --text-figure--font-weight: 600;
+  --shadow-color: 220 40% 8%;
   /* Elevation. In light, shadow separates a card from the white page. */
-  --shadow-1: 0 0 0 1px rgb(33 31 38 / 0.03), 0 2px 6px rgb(33 31 38 / 0.05), 0 4px 8px rgb(33 31 38 / 0.08);
-  --shadow-2: 0 0 0 1px rgb(33 31 38 / 0.04), 0 6px 16px rgb(33 31 38 / 0.12);
-  --shadow-3: 0 8px 28px rgb(33 31 38 / 0.28);
+  --shadow-1: 0 0 0 1px hsl(var(--shadow-color) / 0.03), 0 2px 6px hsl(var(--shadow-color) / 0.05), 0 4px 8px hsl(var(--shadow-color) / 0.08);
+  --shadow-2: 0 0 0 1px hsl(var(--shadow-color) / 0.04), 0 6px 16px hsl(var(--shadow-color) / 0.12);
+  --shadow-3: 0 8px 28px hsl(var(--shadow-color) / 0.28);
   --shadow-card: var(--shadow-1);
   --shadow-dropdown: var(--shadow-2);
   --shadow-overlay: var(--shadow-3);

package/src/styles/theme.css

@@ -36,12 +36,10 @@
   --radius-xl: 12px;
   --radius-full: 999px;
 
-  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
-  --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.3);
+  --shadow-dropdown: 0 8px 30px hsl(var(--shadow-color) / 0.45);
   --shadow-glow: none;
-  --shadow-overlay:
-    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
-    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
+  --shadow-overlay: 0 2px 6px hsl(var(--shadow-color) / 0.3), 0 16px 40px hsl(var(--shadow-color) / 0.5);
 }
 
 /* Inline variable-dependent utilities so their source is resolved on the
@@ -66,7 +64,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 */
@@ -388,23 +374,18 @@
   --code-comment: var(--syntax-comment);
   --code-error: var(--syntax-error);
 
-  /* Shadows — flat, no inner ring, no indigo glow */
-  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
-  --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
+  /* Shadows — flat, no inner ring, no glow. Every shadow is one colour,
+     --shadow-color, as HSL channels so each sets its own alpha: black here, a
+     deep cool ink in light. A shadow never inverts into a light halo; dark
+     elevation is the plane step plus --edge-highlight. --shadow-overlay is the
+     lift above --shadow-dropdown, for a surface that covers the page (a
+     drawer, a modal, a floating dock): a tight contact layer plus a wide one. */
+  --shadow-color: 0 0% 0%;
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.3);
+  --shadow-dropdown: 0 8px 30px hsl(var(--shadow-color) / 0.45);
   --shadow-glow: none;
-  --shadow-accent: 0 1px 2px rgba(0, 0, 0, 0.3);
-  /* The lift above --shadow-dropdown, for a surface that covers the page
-     rather than sitting beside it: a drawer, a modal, a floating dock.
-     Two layers — a tight contact shadow plus a wide ambient one.
-     Alone among the shadows this is derived from --hsl-foreground instead of
-     a fixed rgba, so it INVERTS with the theme. That is what makes it work in
-     dark: a black shadow on a dark canvas renders as nothing (see the ladder
-     note at the top of this file), while the foreground is near-white there,
-     so the same declaration reads as a soft halo. One definition therefore
-     serves both themes and the light block does not restate it. */
-  --shadow-overlay:
-    0 2px 6px hsl(var(--hsl-foreground) / 0.1),
-    0 16px 40px hsl(var(--hsl-foreground) / 0.16);
+  --shadow-accent: var(--shadow-card);
+  --shadow-overlay: 0 2px 6px hsl(var(--shadow-color) / 0.3), 0 16px 40px hsl(var(--shadow-color) / 0.5);
   /* Scrim and media ink. A scrim dims the page behind a modal or sheet, or
      darkens a photo under its caption. It is black in every theme: a dimming
      layer that inverted in dark mode would brighten the page it covers.
@@ -424,12 +405,18 @@
   --radius-pill: 999px;
   --radius-full: 999px;
   --radius-composer: 26px;    /* centered composer pill */
-  /* Radius by role. New surfaces pick the role they play; system.css repeats
-     these for pages that load it on its own ladders. */
+  /* Radius by role, one ramp: tag 4, control 8, card 12, container 16, and
+     --radius-pill for every chip and status pill. Chip, field and panel are
+     the older names of control, card and container. Cover and sheet are the
+     media and bottom-sheet radii. system.css repeats these for pages that load
+     it on its own ladders. */
   --radius-tag: 4px;
-  --radius-chip: 8px;
-  --radius-field: 12px;
-  --radius-panel: 16px;
+  --radius-control: var(--radius-md);
+  --radius-card: var(--radius-xl);
+  --radius-container: 16px;
+  --radius-chip: var(--radius-control);
+  --radius-field: var(--radius-card);
+  --radius-panel: var(--radius-container);
   --radius-cover: 20px;
   --radius-sheet: 24px;
   --radius: 0.5rem;           /* 8px chrome default (was 10px) */
@@ -461,12 +448,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
@@ -540,6 +528,11 @@
   --motion-dismiss: var(--duration-instant) var(--ease-exit);
   --motion-stream: var(--duration-stream) var(--ease-expo);
   --motion-arrive: var(--duration-arrive) var(--ease-expo);
+  /* The only loop period on a page. A running mark breathes on it with
+     `tangle-breathe` (opacity, never position or scale), so every live thing
+     shares one rhythm. Reduced motion keeps it: see the rule below. */
+  --duration-ambient: 2000ms;
+  --motion-ambient: var(--duration-ambient) ease-in-out;
 
   /* Elapsed interaction thresholds, not animation durations. See
    * docs/design-bible.md#interaction. Reduced motion leaves these unchanged. */
@@ -589,7 +582,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 +602,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 ─────────────────────────────────────────────────────────────
@@ -752,11 +743,11 @@
   --glass-bg-strong: var(--depth-1);
   --code-header-bg: color-mix(in srgb, hsl(var(--hsl-muted)) 50%, transparent);
 
-  /* Shadows — flat, no inner ring, no glow */
-  --shadow-card: 0 1px 2px rgba(25, 28, 36, 0.06);
-  --shadow-dropdown: 0 8px 30px rgba(25, 28, 36, 0.10);
-  --shadow-glow: none;
-  --shadow-accent: 0 1px 2px rgba(25, 28, 36, 0.06);
+  /* Shadows — the dark roles in the light shadow colour, at light alphas. */
+  --shadow-color: 220 40% 8%;
+  --shadow-card: 0 1px 2px hsl(var(--shadow-color) / 0.06);
+  --shadow-dropdown: 0 8px 30px hsl(var(--shadow-color) / 0.1);
+  --shadow-overlay: 0 2px 6px hsl(var(--shadow-color) / 0.1), 0 16px 40px hsl(var(--shadow-color) / 0.16);
 }
 
 
@@ -807,15 +798,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 +822,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 +859,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
@@ -945,7 +946,11 @@
 
 
 /* Motion is opt-in at the component, but its reduced-motion preference is
- * shared. Re-declare composites at the same boundary as their durations. */
+ * shared. Re-declare composites at the same boundary as their durations.
+ * --duration-ambient is not zeroed: the essential running mark
+ * (data-motion="essential") keeps its opacity-only breathe, because it is the
+ * only "still working" signal and it never moves anything. */
+@keyframes tangle-breathe { 50% { opacity: 0.45; } }
 @media (prefers-reduced-motion: reduce) {
   :root,
   .dark,

package/src/styles/tokens.test.ts

@@ -5,10 +5,12 @@ import {
   blockIn,
   compositeOver,
   contrastRatio,
+  declIn,
   hexIn,
   hexRelativeLuminanceIn,
   hslIn,
   hslToRgb,
+  resolveIn,
 } from "./css-test-utils";
 
 /**
@@ -608,3 +610,39 @@ describe("each colour is declared once: a role, then aliases", () => {
     expect(literalsOutsideTones(spine).size).toBeLessThanOrEqual(ceiling);
   });
 });
+
+describe("shadow, radius and loop period are one role each", () => {
+  // The run-UI critique of 2026-10-27 (fixes 9, 10 and 22) found a white shadow
+  // haze in dark mode, six radii and seven loop periods. Each is now one role
+  // that every other name aliases, so a surface cannot drift to a second value.
+  it.each([
+    ["dark", DARK, "0 0% 0%"],
+    ["light", LIGHT, "220 40% 8%"],
+  ] as const)("%s: every shadow is drawn in --shadow-color and never inverts", (_, spine, colour) => {
+    expect(declIn(spine, "shadow-color")).toBe(colour);
+    for (const token of ["shadow-card", "shadow-dropdown", "shadow-overlay"]) {
+      const value = declIn(spine, token);
+      expect(value, `--${token}`).toMatch(/^[^,]*hsl\(var\(--shadow-color\) \/ [\d.]+\)/);
+      expect(value, `--${token} names a colour of its own`).not.toMatch(/rgba?\(|#[0-9a-f]{3,8}\b|--hsl-foreground/i);
+    }
+  });
+
+  it("draws radii from one ramp, and the older role names alias it", () => {
+    const ramp = { tag: "4px", control: "8px", card: "12px", container: "16px", pill: "999px" };
+    for (const [role, px] of Object.entries(ramp)) expect(resolveIn(DARK, `radius-${role}`), role).toBe(px);
+    for (const [older, role] of [["chip", "control"], ["field", "card"], ["panel", "container"]]) {
+      expect(declIn(DARK, `radius-${older}`)).toBe(`var(--radius-${role})`);
+    }
+  });
+
+  it("has one loop period, which reduced motion keeps for an opacity-only breathe", () => {
+    expect(declIn(DARK, "duration-ambient")).toBe("2000ms");
+    expect(declIn(DARK, "motion-ambient")).toBe("var(--duration-ambient) ease-in-out");
+    const reduced = tokens.match(/@media \(prefers-reduced-motion: reduce\) \{([\s\S]*?)\n\}/)![1];
+    expect(reduced).toContain("--duration-fast: 0ms");
+    expect(reduced, "the essential breathe keeps its period").not.toContain("--duration-ambient");
+    const breathe = tokens.match(/@keyframes tangle-breathe \{([\s\S]*?)\}\s*\}/)?.[1];
+    expect(breathe, "the shared breathe keyframe").toMatch(/opacity/);
+    expect(breathe, "a loop never moves or scales").not.toMatch(/transform|translate|scale|rotate/);
+  });
+});