@tangle-network/brand 1.27.1 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # 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
+
+- 069f422: Each colour in the canonical spine is declared once, as a role, and every other
+  name of that colour aliases it: planes derive from the `--hsl-*` channels, the
+  four indigos (`--hsl-primary` fill, `--brand-primary` mark, `--brand-cool` line,
+  `--accent-text` ink) carry every `brand-*`, `md3-primary*` and gradient name, and
+  one ink per status hue carries its `surface-*`, `status-*`, `md3-*`, `code-*`,
+  `syntax-*` and shadcn channel. Every public token name is kept.
+  
+  Values that moved, all toward the hand-tuned inks: dark `--status-*`,
+  `--hsl-success`, `--hsl-warning`, `--hsl-info` and `--hsl-destructive` are the
+  pastel `--surface-*-text` inks instead of saturated fills (a status fill now
+  carries dark text, as the destructive one did); light `--hsl-warning` is the
+  `--surface-warning-text` orange instead of the 1.6:1 yellow; `--brand-glow` is
+  the accent ink (`#A5B4FC` dark, the bright indigo in light, so prose links read
+  on paper); `--brand-vibrant` is the brand mark; syntax and `--code-*` colours are
+  the status and tone inks, with keywords on the categorical violet instead of the
+  accent; `--hsl-primary` and `--btn-primary-bg` agree at `#4c3fc6`; the sidebar
+  hover and border are the spine's L3 plane and hairline; one-unit plane drifts
+  (`#12111f`, `#f6f7fa`, `#f1f2f7`, `#c7c6d6`) collapse onto their channels.
+  
+  Tailwind's `bg-brand`, `text-brand-glow` and `bg-status-*` utilities now follow
+  the mode and the named theme instead of one static value. `tangle-dark` declares
+  nothing: `tokens.css` seeds the complete dark spine on its selector. A shared
+  `scripts/css-resolve.mjs` reads aliases for the generators and the style tests,
+  and `tokens.test.ts` holds a ratchet on hex literals per spine (28 dark, 25 light,
+  outside the generated tones).
+
 ## 1.27.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { knot, knotGradientIds, knotSvg } from "./knot.js";
 import * as React from "react";
-//#region src/logo.d.ts
 interface LogoProps {
   size?: "sm" | "md" | "lg" | "xl";
   variant?: "full" | "icon";
@@ -15,8 +14,6 @@ interface TangleKnotProps {
 }
 export declare function TangleKnot({ size, className, label }: TangleKnotProps): React.JSX.Element;
 export declare function Logo({ size, variant, suffix, className }: LogoProps): React.JSX.Element;
-//#endregion
-//#region src/palette.generated.d.ts
 /** A theme's resolved roles: hex strings, or rgba() where the token is translucent. */
 interface BrandPalette {
   canvas: string;
@@ -56,19 +53,19 @@ export declare const palettes: {
   readonly light: {
     readonly canvas: "#eceef3";
     readonly card: "#ffffff";
-    readonly well: "#f6f7fa";
-    readonly nested: "#f1f2f7";
+    readonly well: "#f5f6fa";
+    readonly nested: "#edeff4";
     readonly overlay: "#ffffff";
     readonly deepest: "#ffffff";
-    readonly hairline: "#c7c6d6";
+    readonly hairline: "#c8c7d6";
     readonly ink: "#2d2d2d";
     readonly inkSecondary: "#3f3f3f";
     readonly inkMuted: "#4c4c4c";
-    readonly accent: "#4c3fc5";
+    readonly accent: "#4c3fc6";
     readonly accentHover: "#5a50d6";
     readonly onAccent: "#ffffff";
     readonly accentText: "#3c32e9";
-    readonly danger: "#b41d1d";
+    readonly danger: "#b91c1c";
     readonly successBg: "#ecfdf5";
     readonly successBorder: "#a7f3d0";
     readonly successText: "#047857";
@@ -83,25 +80,25 @@ export declare const palettes: {
     readonly infoText: "#0369a1";
     readonly brandVibrant: "#6366f1";
     readonly brandCool: "#818cf8";
-    readonly brandGlow: "#a5aafc";
+    readonly brandGlow: "#3c32e9";
     readonly brandPurple: "#6366f1";
   };
   readonly dark: {
     readonly canvas: "#0a0a14";
     readonly card: "#191826";
-    readonly well: "#12111f";
-    readonly nested: "#221f33";
-    readonly overlay: "#2c2942";
+    readonly well: "#11101e";
+    readonly nested: "#252237";
+    readonly overlay: "#312e47";
     readonly deepest: "#040408";
-    readonly hairline: "#2a293d";
+    readonly hairline: "#37364a";
     readonly ink: "#e6e6e6";
     readonly inkSecondary: "#c7c7c7";
     readonly inkMuted: "#b5b5b5";
-    readonly accent: "#4c3fc5";
+    readonly accent: "#4c3fc6";
     readonly accentHover: "#5a50d6";
     readonly onAccent: "#ffffff";
     readonly accentText: "#a5b4fc";
-    readonly danger: "#f99090";
+    readonly danger: "#ffada9";
     readonly successBg: "#2f5146";
     readonly successBorder: "#3c7760";
     readonly successText: "#5ed7a4";
@@ -114,9 +111,9 @@ export declare const palettes: {
     readonly infoBg: "#2d4e67";
     readonly infoBorder: "#3d7292";
     readonly infoText: "#67cdff";
-    readonly brandVibrant: "#6366f1";
+    readonly brandVibrant: "#7c6cf6";
     readonly brandCool: "#818cf8";
-    readonly brandGlow: "#a5aafc";
+    readonly brandGlow: "#a5b4fc";
     readonly brandPurple: "#c7d2fe";
   };
   readonly websiteLight: {
@@ -130,11 +127,11 @@ export declare const palettes: {
     readonly ink: "#191c24";
     readonly inkSecondary: "#3a3a50";
     readonly inkMuted: "#5e5e7a";
-    readonly accent: "#4c3fc5";
+    readonly accent: "#4c3fc6";
     readonly accentHover: "#5a50d6";
     readonly onAccent: "#ffffff";
     readonly accentText: "#3c32e9";
-    readonly danger: "#b41d1d";
+    readonly danger: "#b91c1c";
     readonly successBg: "#ecfdf5";
     readonly successBorder: "#a7f3d0";
     readonly successText: "#047857";
@@ -149,7 +146,7 @@ export declare const palettes: {
     readonly infoText: "#0369a1";
     readonly brandVibrant: "#6366f1";
     readonly brandCool: "#818cf8";
-    readonly brandGlow: "#a5aafc";
+    readonly brandGlow: "#3c32e9";
     readonly brandPurple: "#6366f1";
   };
   readonly websiteDark: {
@@ -163,11 +160,11 @@ export declare const palettes: {
     readonly ink: "#fdfdfd";
     readonly inkSecondary: "#aaa8b8";
     readonly inkMuted: "#9496bc";
-    readonly accent: "#4c3fc5";
+    readonly accent: "#4c3fc6";
     readonly accentHover: "#5a50d6";
     readonly onAccent: "#ffffff";
     readonly accentText: "#a5b4fc";
-    readonly danger: "#f99090";
+    readonly danger: "#ffada9";
     readonly successBg: "#2f5146";
     readonly successBorder: "#3c7760";
     readonly successText: "#5ed7a4";
@@ -180,11 +177,10 @@ export declare const palettes: {
     readonly infoBg: "#2d4e67";
     readonly infoBorder: "#3d7292";
     readonly infoText: "#67cdff";
-    readonly brandVibrant: "#6366f1";
+    readonly brandVibrant: "#7c6cf6";
     readonly brandCool: "#818cf8";
-    readonly brandGlow: "#a5aafc";
+    readonly brandGlow: "#a5b4fc";
     readonly brandPurple: "#c7d2fe";
   };
 };
-//#endregion
 export { type BrandPalette, type LogoProps, type TangleKnotProps, knot, knotGradientIds, knotSvg };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { knot, knotGradientIds, knotSvg } from "./knot.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/logo.tsx
+// src/logo.tsx
 const sizeConfig = {
 	sm: {
 		icon: 24,
@@ -88,26 +88,25 @@ function Logo({ size = "md", variant = "full", suffix = null, className }) {
 		})]
 	});
 }
-//#endregion
-//#region src/palette.generated.ts
+// src/palette.generated.ts
 /** Resolved palettes for the canonical light and dark themes and the website named theme. */
 const palettes = {
 	light: {
 		canvas: "#eceef3",
 		card: "#ffffff",
-		well: "#f6f7fa",
-		nested: "#f1f2f7",
+		well: "#f5f6fa",
+		nested: "#edeff4",
 		overlay: "#ffffff",
 		deepest: "#ffffff",
-		hairline: "#c7c6d6",
+		hairline: "#c8c7d6",
 		ink: "#2d2d2d",
 		inkSecondary: "#3f3f3f",
 		inkMuted: "#4c4c4c",
-		accent: "#4c3fc5",
+		accent: "#4c3fc6",
 		accentHover: "#5a50d6",
 		onAccent: "#ffffff",
 		accentText: "#3c32e9",
-		danger: "#b41d1d",
+		danger: "#b91c1c",
 		successBg: "#ecfdf5",
 		successBorder: "#a7f3d0",
 		successText: "#047857",
@@ -122,25 +121,25 @@ const palettes = {
 		infoText: "#0369a1",
 		brandVibrant: "#6366f1",
 		brandCool: "#818cf8",
-		brandGlow: "#a5aafc",
+		brandGlow: "#3c32e9",
 		brandPurple: "#6366f1"
 	},
 	dark: {
 		canvas: "#0a0a14",
 		card: "#191826",
-		well: "#12111f",
-		nested: "#221f33",
-		overlay: "#2c2942",
+		well: "#11101e",
+		nested: "#252237",
+		overlay: "#312e47",
 		deepest: "#040408",
-		hairline: "#2a293d",
+		hairline: "#37364a",
 		ink: "#e6e6e6",
 		inkSecondary: "#c7c7c7",
 		inkMuted: "#b5b5b5",
-		accent: "#4c3fc5",
+		accent: "#4c3fc6",
 		accentHover: "#5a50d6",
 		onAccent: "#ffffff",
 		accentText: "#a5b4fc",
-		danger: "#f99090",
+		danger: "#ffada9",
 		successBg: "#2f5146",
 		successBorder: "#3c7760",
 		successText: "#5ed7a4",
@@ -153,9 +152,9 @@ const palettes = {
 		infoBg: "#2d4e67",
 		infoBorder: "#3d7292",
 		infoText: "#67cdff",
-		brandVibrant: "#6366f1",
+		brandVibrant: "#7c6cf6",
 		brandCool: "#818cf8",
-		brandGlow: "#a5aafc",
+		brandGlow: "#a5b4fc",
 		brandPurple: "#c7d2fe"
 	},
 	websiteLight: {
@@ -169,11 +168,11 @@ const palettes = {
 		ink: "#191c24",
 		inkSecondary: "#3a3a50",
 		inkMuted: "#5e5e7a",
-		accent: "#4c3fc5",
+		accent: "#4c3fc6",
 		accentHover: "#5a50d6",
 		onAccent: "#ffffff",
 		accentText: "#3c32e9",
-		danger: "#b41d1d",
+		danger: "#b91c1c",
 		successBg: "#ecfdf5",
 		successBorder: "#a7f3d0",
 		successText: "#047857",
@@ -188,7 +187,7 @@ const palettes = {
 		infoText: "#0369a1",
 		brandVibrant: "#6366f1",
 		brandCool: "#818cf8",
-		brandGlow: "#a5aafc",
+		brandGlow: "#3c32e9",
 		brandPurple: "#6366f1"
 	},
 	websiteDark: {
@@ -202,11 +201,11 @@ const palettes = {
 		ink: "#fdfdfd",
 		inkSecondary: "#aaa8b8",
 		inkMuted: "#9496bc",
-		accent: "#4c3fc5",
+		accent: "#4c3fc6",
 		accentHover: "#5a50d6",
 		onAccent: "#ffffff",
 		accentText: "#a5b4fc",
-		danger: "#f99090",
+		danger: "#ffada9",
 		successBg: "#2f5146",
 		successBorder: "#3c7760",
 		successText: "#5ed7a4",
@@ -219,11 +218,10 @@ const palettes = {
 		infoBg: "#2d4e67",
 		infoBorder: "#3d7292",
 		infoText: "#67cdff",
-		brandVibrant: "#6366f1",
+		brandVibrant: "#7c6cf6",
 		brandCool: "#818cf8",
-		brandGlow: "#a5aafc",
+		brandGlow: "#a5b4fc",
 		brandPurple: "#c7d2fe"
 	}
 };
-//#endregion
 export { Logo, TangleKnot, knot, knotGradientIds, knotSvg, palettes };

package/dist/knot.d.ts

@@ -1,4 +1,3 @@
-//#region src/knot.d.ts
 /** Canonical geometry. This entry has no React or browser dependencies. */
 export declare const knot: {
   readonly viewBox: "20 45 156 140";
@@ -29,5 +28,4 @@ export declare function knotSvg({ id, size, label }: {
   id: string;
   size?: number;
   label?: string;
-}): string;
-//#endregion
+}): string;

package/dist/knot.js

@@ -1,4 +1,4 @@
-//#region src/knot.ts
+// src/knot.ts
 /** Canonical geometry. This entry has no React or browser dependencies. */
 const knot = {
 	viewBox: "20 45 156 140",
@@ -41,5 +41,4 @@ function knotSvg({ id, size = 32, label }) {
 	const accessibility = label ? `role="img" aria-label="${escape(label)}"` : "aria-hidden=\"true\"";
 	return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${knot.viewBox}" fill="none" focusable="false" ${accessibility}><defs>${knot.gradients.map((g, i) => `<linearGradient id="${ids[i]}" x1="${g.x1}" y1="${g.y1}" x2="${g.x2}" y2="${g.y2}" gradientUnits="userSpaceOnUse">${knot.stops.map((color, index) => `<stop offset="${index}" stop-color="${color}"/>`).join("")}</linearGradient>`).join("")}</defs>${knot.paths.map((path, i) => `<path d="${path.d}" opacity="${path.opacity}" fill="url(#${ids[i]})"/>`).join("")}</svg>`;
 }
-//#endregion
 export { knot, knotGradientIds, knotSvg };

package/dist/social.d.ts

@@ -1,4 +1,3 @@
-//#region src/social.d.ts
 export interface SocialImage {
   url: string;
   type: "image/png" | "image/jpeg" | "image/webp";
@@ -36,5 +35,4 @@ export type SocialMetaTag = {
 export declare function socialMetadata(page: SocialPage): {
   canonicalUrl: string;
   tags: SocialMetaTag[];
-};
-//#endregion
+};

package/dist/social.js

@@ -1,4 +1,4 @@
-//#region src/social.ts
+// src/social.ts
 function httpsUrl(value) {
 	const url = new URL(value);
 	if (url.protocol !== "https:" || url.username || url.password) throw new Error("Social metadata requires HTTPS URLs without credentials");
@@ -105,5 +105,4 @@ function socialMetadata(page) {
 		]
 	};
 }
-//#endregion
 export { socialMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.27.1",
+  "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",
@@ -73,10 +73,10 @@
     }
   },
   "devDependencies": {
-    "@storybook/react": "^10.6.0",
+    "@storybook/react": "^10.6.3",
     "@types/react": "^19.3.0",
-    "react": "^19.3.0",
-    "tsdown": "^0.23.0",
+    "react": "^19.3.1",
+    "tsdown": "0.23.1",
     "typescript": "^7.0.2"
   },
   "keywords": [

package/src/palette.generated.ts

@@ -42,19 +42,19 @@ export const palettes = {
   light: {
     canvas: "#eceef3",
     card: "#ffffff",
-    well: "#f6f7fa",
-    nested: "#f1f2f7",
+    well: "#f5f6fa",
+    nested: "#edeff4",
     overlay: "#ffffff",
     deepest: "#ffffff",
-    hairline: "#c7c6d6",
+    hairline: "#c8c7d6",
     ink: "#2d2d2d",
     inkSecondary: "#3f3f3f",
     inkMuted: "#4c4c4c",
-    accent: "#4c3fc5",
+    accent: "#4c3fc6",
     accentHover: "#5a50d6",
     onAccent: "#ffffff",
     accentText: "#3c32e9",
-    danger: "#b41d1d",
+    danger: "#b91c1c",
     successBg: "#ecfdf5",
     successBorder: "#a7f3d0",
     successText: "#047857",
@@ -69,25 +69,25 @@ export const palettes = {
     infoText: "#0369a1",
     brandVibrant: "#6366f1",
     brandCool: "#818cf8",
-    brandGlow: "#a5aafc",
+    brandGlow: "#3c32e9",
     brandPurple: "#6366f1",
   },
   dark: {
     canvas: "#0a0a14",
     card: "#191826",
-    well: "#12111f",
-    nested: "#221f33",
-    overlay: "#2c2942",
+    well: "#11101e",
+    nested: "#252237",
+    overlay: "#312e47",
     deepest: "#040408",
-    hairline: "#2a293d",
+    hairline: "#37364a",
     ink: "#e6e6e6",
     inkSecondary: "#c7c7c7",
     inkMuted: "#b5b5b5",
-    accent: "#4c3fc5",
+    accent: "#4c3fc6",
     accentHover: "#5a50d6",
     onAccent: "#ffffff",
     accentText: "#a5b4fc",
-    danger: "#f99090",
+    danger: "#ffada9",
     successBg: "#2f5146",
     successBorder: "#3c7760",
     successText: "#5ed7a4",
@@ -100,9 +100,9 @@ export const palettes = {
     infoBg: "#2d4e67",
     infoBorder: "#3d7292",
     infoText: "#67cdff",
-    brandVibrant: "#6366f1",
+    brandVibrant: "#7c6cf6",
     brandCool: "#818cf8",
-    brandGlow: "#a5aafc",
+    brandGlow: "#a5b4fc",
     brandPurple: "#c7d2fe",
   },
   websiteLight: {
@@ -116,11 +116,11 @@ export const palettes = {
     ink: "#191c24",
     inkSecondary: "#3a3a50",
     inkMuted: "#5e5e7a",
-    accent: "#4c3fc5",
+    accent: "#4c3fc6",
     accentHover: "#5a50d6",
     onAccent: "#ffffff",
     accentText: "#3c32e9",
-    danger: "#b41d1d",
+    danger: "#b91c1c",
     successBg: "#ecfdf5",
     successBorder: "#a7f3d0",
     successText: "#047857",
@@ -135,7 +135,7 @@ export const palettes = {
     infoText: "#0369a1",
     brandVibrant: "#6366f1",
     brandCool: "#818cf8",
-    brandGlow: "#a5aafc",
+    brandGlow: "#3c32e9",
     brandPurple: "#6366f1",
   },
   websiteDark: {
@@ -149,11 +149,11 @@ export const palettes = {
     ink: "#fdfdfd",
     inkSecondary: "#aaa8b8",
     inkMuted: "#9496bc",
-    accent: "#4c3fc5",
+    accent: "#4c3fc6",
     accentHover: "#5a50d6",
     onAccent: "#ffffff",
     accentText: "#a5b4fc",
-    danger: "#f99090",
+    danger: "#ffada9",
     successBg: "#2f5146",
     successBorder: "#3c7760",
     successText: "#5ed7a4",
@@ -166,9 +166,9 @@ export const palettes = {
     infoBg: "#2d4e67",
     infoBorder: "#3d7292",
     infoText: "#67cdff",
-    brandVibrant: "#6366f1",
+    brandVibrant: "#7c6cf6",
     brandCool: "#818cf8",
-    brandGlow: "#a5aafc",
+    brandGlow: "#a5b4fc",
     brandPurple: "#c7d2fe",
   },
 } as const satisfies Record<string, BrandPalette>;

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

@@ -60,11 +60,12 @@ describe("hexRelativeLuminanceIn", () => {
     expect(card).toBeGreaterThan(canvas);
   });
 
-  it("says a token is non-hex rather than claiming it is missing", () => {
-    expect(() => hexRelativeLuminanceIn("--a: var(--b);", "a")).toThrow(
-      /not a hex color/,
-    );
-    expect(() => hexRelativeLuminanceIn("--a: #fff;", "b")).toThrow(/missing/);
+  it("follows an alias to the colour it paints, and names an alias that leads nowhere", () => {
+    expect(hexRelativeLuminanceIn("--a: var(--b); --b: #fff;", "a")).toBe(1);
+    expect(hexRelativeLuminanceIn("--a: hsl(var(--b)); --b: 0 0% 100%;", "a")).toBe(1);
+    expect(() => hexRelativeLuminanceIn("--a: var(--b);", "a")).toThrow(/--b is not defined/);
+    expect(() => hexRelativeLuminanceIn("--a: rgba(0, 0, 0, 0.5);", "a")).toThrow(/not a hex color/);
+    expect(() => hexRelativeLuminanceIn("--a: #fff;", "b")).toThrow(/not defined/);
   });
 });
 
@@ -73,7 +74,9 @@ describe("hslIn", () => {
     expect(hslIn("--a: 240 33% 6%;", "a")).toEqual({ h: 240, s: 33, l: 6 });
   });
 
-  it("throws when the slot is absent", () => {
-    expect(() => hslIn("--a: 240 33% 6%;", "b")).toThrow(/missing HSL slot/);
+  it("follows an alias to its triple, and throws when the slot is absent or not a triple", () => {
+    expect(hslIn("--a: var(--b); --b: 240 33% 6%;", "a")).toEqual({ h: 240, s: 33, l: 6 });
+    expect(() => hslIn("--a: 240 33% 6%;", "b")).toThrow(/not defined/);
+    expect(() => hslIn("--a: #fff;", "a")).toThrow(/not an HSL triple/);
   });
 });

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

@@ -6,6 +6,32 @@
  * importing file's context.
  */
 
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { block as resolverBlock, decls, resolveValue } from "../../scripts/css-resolve.mjs";
+
+/** The canonical dark spine's declarations: what every other block inherits. */
+const BASELINE: Record<string, string> = decls(
+  resolverBlock(
+    readFileSync(path.resolve(import.meta.dirname, "tokens.css"), "utf8"),
+    ".dark",
+  ),
+);
+
+/**
+ * A token's concrete value in a block, with aliases followed: `var(--x)`
+ * chains and `hsl(var(--x))` wrappers, each hop reading the block first and
+ * the canonical dark baseline second, which is how the browser resolves a
+ * custom property declared on the same element as the light override.
+ */
+export function resolveIn(css: string | string[], token: string): string {
+  // A chain of blocks models the cascade on one element: the first block that
+  // declares a name wins, as a named theme's own rule beats the spine it sits on.
+  const sources = Array.isArray(css) ? css : [css];
+  const scope = Object.assign({}, ...sources.map(decls).reverse());
+  return resolveValue(scope, token, BASELINE);
+}
+
 /** Escape every regex metacharacter, so a selector is matched literally. */
 function escapeRegex(literal: string): string {
   return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -78,15 +104,12 @@ export function declIn(css: string, token: string): string {
 
 /** Read an `H S% L%` channel triple. */
 export function hslIn(
-  css: string,
+  css: string | string[],
   token: string,
 ): { h: number; s: number; l: number } {
-  const m = css.match(
-    new RegExp(
-      `--${token}:\\s*(\\d+(?:\\.\\d+)?)\\s+(\\d+(?:\\.\\d+)?)%\\s+(\\d+(?:\\.\\d+)?)%`,
-    ),
-  );
-  if (!m) throw new Error(`missing HSL slot --${token}`);
+  const value = resolveIn(css, token);
+  const m = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/.exec(value);
+  if (!m) throw new Error(`--${token} is not an HSL triple (found "${value}")`);
   return { h: Number(m[1]), s: Number(m[2]), l: Number(m[3]) };
 }
 
@@ -99,11 +122,13 @@ type Rgb = [number, number, number];
  * separate question, answered by `compositeOver`). A token that exists but is not
  * hex reports exactly that, rather than claiming it is missing.
  */
-export function hexIn(css: string, token: string): Rgb {
-  const declaration = css.match(new RegExp(`--${token}:\\s*([^;]+)`));
-  if (!declaration) throw new Error(`missing surface --${token}`);
-
-  const value = declaration[1].trim();
+export function hexIn(css: string | string[], token: string): Rgb {
+  const value = resolveIn(css, token);
+  // A plane authored as channels resolves to a triple; read it as the colour it paints.
+  const triple = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/.exec(value);
+  if (triple) {
+    return hslToRgb({ h: Number(triple[1]), s: Number(triple[2]), l: Number(triple[3]) }).map(Math.round) as Rgb;
+  }
   const hex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/.exec(value);
   if (!hex) {
     throw new Error(`--${token} is not a hex color (found "${value}")`);
@@ -181,7 +206,7 @@ export function contrastRatio(a: Rgb, b: Rgb): number {
  * below" assertion made on HSL L would be measuring the wrong thing. Hex parsing
  * (and its error reporting) is `hexIn`'s.
  */
-export function hexRelativeLuminanceIn(css: string, token: string): number {
+export function hexRelativeLuminanceIn(css: string | string[], token: string): number {
   return relativeLuminance(hexIn(css, token));
 }