@tangle-network/brand 1.23.1 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.24.0
+
+### Minor Changes
+
+- 33cfa62: Canonical surface ladder: every theme without its own ladder now derives its field wells and field border from its own page, card, hairline and ink. Dark wells recess 4.6 L under the page (they sat 3.1 above it), light wells take the opposite plane (5 L either way; the old well sat 2.6 under the white card), and the field border clears 4:1 on the card in both modes (it was the 1.5:1 hairline). Hospitality keeps its tuned ladder.
+
 ## 1.23.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.23.1",
+  "version": "1.24.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/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: d9f91f8d9c731a2b37749d49fcb621a42a5e4fe4a2d6e7157e6b4eef71a5f3b5
+ * SHA-256: 6c805f42ca39150c46bc17c76de5083bf24e8b1e12baa70614d51a27e94777f7
  * Light-default compatibility; all explicit modes remain canonical.
  */
 :where(:root),
@@ -647,12 +647,12 @@
 [data-theme] {
     --hsl-raised: var(--hsl-card);
     --hsl-raised-2: var(--hsl-card);
-    --well-page: var(--bg-input);
-    --well-card: var(--bg-input);
-    --well-raised: var(--bg-input);
-    --well-raised-2: var(--bg-input);
+    --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: var(--well-page);
-    --field-border: hsl(var(--hsl-border));
+    --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;
@@ -674,6 +674,10 @@
 :where(:root) {
     --ix-sel-bg: hsl(var(--hsl-ring) / 0.13);
     --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));
 }
 [data-slot="card"] :where(*) {
     --card: var(--hsl-raised);

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, contrastRatio, declIn, hexIn, hslIn, hslToRgb, oklchLightness } from "./css-test-utils";
+import { blockIn, blocksIn, contrastRatio, declIn, hexIn, hslIn, hslToRgb, oklchLightness } from "./css-test-utils";
 
 /**
  * The surface ladder and the interaction palette.
@@ -168,14 +168,10 @@ describe("shared surface context and interaction tokens (tokens.css)", () => {
     }
   });
 
-  it("defaults every new ladder token to the plain spine, so other themes look as they did", () => {
+  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)");
-    for (const well of ["well-page", "well-card", "well-raised", "well-raised-2"]) {
-      expect(declIn(body, well)).toBe("var(--bg-input)");
-    }
     expect(declIn(body, "well")).toBe("var(--well-page)");
-    expect(declIn(body, "field-border")).toBe("hsl(var(--hsl-border))");
     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");
@@ -190,7 +186,7 @@ describe("shared surface context and interaction tokens (tokens.css)", () => {
     expect(declIn(body, "ix-sel-ring")).toBe("hsl(var(--hsl-ring) / 0.85)");
     expect(declIn(body, "ix-sel-bg")).toBe("hsl(var(--hsl-ring) / 0.18)");
     expect(declIn(body, "ix-hover-bg")).toBe("hsl(var(--hsl-ring) / 0.08)");
-    const lightTint = css.match(/([^{}]*)\{\s*--ix-sel-bg:\s*hsl\(var\(--hsl-ring\) \/ 0\.13\);\s*--ix-hover-bg:\s*hsl\(var\(--hsl-ring\) \/ 0\.07\);\s*\}/);
+    const lightTint = css.match(/([^{}]*)\{\s*--ix-sel-bg:\s*hsl\(var\(--hsl-ring\) \/ 0\.13\);\s*--ix-hover-bg:\s*hsl\(var\(--hsl-ring\) \/ 0\.07\);[^{}]*\}/);
     expect(lightTint, "light tint override").not.toBeNull();
     expect(lightTint![1]).toContain('[data-theme="hospitality"]:where(:not(.dark))');
     expect(lightTint![1]).toContain(".light");
@@ -223,3 +219,69 @@ 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) => {
+    const block = blocksIn(tokens, selector).find((b) => /--well-page:/.test(b));
+    if (!block) throw new Error(`no well defaults 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");
+
+  type Rgb = [number, number, number];
+  const toLab = (rgb: Rgb) => {
+    const lin = (c: number) => ((c /= 255) <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+    const [r, g, b] = rgb.map(lin);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return [0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s, 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s, 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s];
+  };
+  const fromLab = ([L, a, b]: number[]): Rgb => {
+    const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const enc = (c: number) => 255 * Math.min(1, Math.max(0, c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055));
+    return [enc(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), enc(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), enc(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)];
+  };
+  /** `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;
+
+  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))");
+    }
+  });
+
+  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("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.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);
+  });
+});

package/src/styles/tokens.css

@@ -950,9 +950,15 @@
  *           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. The defaults
- * below reproduce the plain spine exactly — every level paints the card and
- * every well is --bg-input — so a theme that does not set them looks as it did.
+ * 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.
  *
  * INTERACTION. Four states, all from the focus ring hue (--hsl-ring), so one
  * green or one indigo marks every interactive thing in a theme:
@@ -972,12 +978,14 @@
 [data-theme] {
   --hsl-raised: var(--hsl-card);
   --hsl-raised-2: var(--hsl-card);
-  --well-page: var(--bg-input);
-  --well-card: var(--bg-input);
-  --well-raised: var(--bg-input);
-  --well-raised-2: var(--bg-input);
+  --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: var(--well-page);
-  --field-border: hsl(var(--hsl-border));
+  /* 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. */
+  --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;
@@ -991,8 +999,9 @@
   --ix-hover-bg: hsl(var(--hsl-ring) / 0.08);
 }
 
-/* Light planes need less tint for the same step. Same scope list as the chart
- * light rule below; dark is the default. */
+/* Light planes need less tint for the same step, and take their wells from the
+ * opposite plane. Same scope list as the chart light rule below; dark is the
+ * default. */
 [data-sandbox-theme="vault"]:where(:not(.dark)),
 [data-sandbox-theme="dawn"]:where(:not(.dark)),
 [data-theme="hospitality"]:where(:not(.dark)),
@@ -1002,6 +1011,10 @@
 [data-theme$="-light"] {
   --ix-sel-bg: hsl(var(--hsl-ring) / 0.13);
   --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));
 }
 
 /* Surface context: keyed only on the Card primitive's data-slot, never on app