@tangle-network/brand 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.3.0
+
+### Minor Changes
+
+- f3c5262: Add the missing `tangle-dark` named theme. The named set shipped `tangle-light` with no dark sibling, so `data-theme="tangle-dark"` matched no rule and silently fell through to whatever the element inherited — the light spine's values, inside a light-named wrapper. `tangle-dark` now selects the canonical dark spine by name: same indigo family as `tangle-light`, held to the dark contrast discipline, and self-sufficient inside a light-named wrapper (foregrounds and destructive included, so nothing leaks the light values).
+
+## 1.2.0
+
+### Minor Changes
+
+- 2088fb9: Retune the token spine to a neutral-grey surface ladder with indigo as trim rather than as field, in both themes. Surfaces separate by their own fill so a card, a nested panel and an overlay each read as a distinct plane, and the canvas sits off pure black so long reading sessions land away from the glare end of the range.
+
+  Faint text in `Input`, `Textarea`, `StatCard` and `TerminalLine` now takes a dedicated `--text-dim` token instead of a faded stronger one. A translucent foreground renders as its colour composited over the plane behind it, so those hints, subtitles and timestamps measured differently on a card than on the canvas and fell under the 4.5:1 floor on both.
+
+  **Worth a look after upgrading:** in dark mode `--sidebar-background` is now one step BELOW the canvas rather than above it, so the nav reads as chrome the content sits in front of instead of as another raised card. Apps that composited their own surfaces on top of the sidebar assuming it was the lighter plane should give that area a visual pass. Light mode is unchanged — the sidebar is still paper on a grey canvas.
+
+## 1.1.0
+
+### Minor Changes
+
+- 15402db: Ship the indigo surface ladder as the canonical Tangle palette.
+
+  The `:root` spine was a flat, desaturated neutral. Every product app overrode it with its own hand-written palette, so brand's own colors were rendered almost nowhere — and the apps that did inherit them read as grey and washed out, because a flat ladder forces surface separation onto borders instead of fills.
+
+  Both themes now ship the ladder the products actually converged on: an indigo-cast dark scale stepped in even ~4-5% lightness increments, and a light scale of white paper on a tinted canvas rather than white-on-white. Surfaces, depth scale, sidebar and `--bg-root` all move together so the ladder stays coherent.
+
+  Visual change for every consumer. Apps that were overriding the spine should delete those overrides; apps that were inheriting it get the branded look with no code change.
+
+  Also adds a dark-only `intelligence` named theme — a violet surface ramp — and exports the named-theme stylesheet as `./styles/named-themes.css`, so named themes can be imported at all (they shipped, but no export reached them). The name is deliberately not `themes.css`: one letter from the existing `./styles/theme.css` (the Tailwind `@theme` map) is a typo that resolves successfully to the wrong stylesheet. No published version ever exported `./styles/themes.css` — 1.0.0's export map is `./styles/{index,tokens,globals,theme}.css` — so this adds an export rather than renaming a public one, and nothing downstream can break. A named theme re-skins surfaces only; the Tangle accent stays put.
+
 ## 1.0.0
 
 ### Major Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/brand",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Tangle brand system — design tokens, logo, Tailwind v4 theme. Single source of truth for every Tangle app.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
     "./styles/index.css": "./src/styles/index.css",
     "./styles/tokens.css": "./src/styles/tokens.css",
     "./styles/globals.css": "./src/styles/globals.css",
-    "./styles/theme.css": "./src/styles/theme.css"
+    "./styles/theme.css": "./src/styles/theme.css",
+    "./styles/named-themes.css": "./src/styles/named-themes.css"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -46,9 +47,9 @@
     }
   },
   "devDependencies": {
-    "@storybook/react": "^8.6.18",
+    "@storybook/react": "^10.5.5",
     "@types/react": "^19.0.0",
-    "react": "^19.0.0",
+    "react": "^19.2.8",
     "tsup": "^8.3.5",
     "typescript": "^5.6.0"
   },

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

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

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

@@ -0,0 +1,186 @@
+/**
+ * Helpers for asserting on the stylesheets as source text.
+ *
+ * Deliberately NOT a `.test.ts` file: importing one test file from another makes
+ * Vitest register the imported file's top-level suites a second time, in the
+ * importing file's context.
+ */
+
+/** Escape every regex metacharacter, so a selector is matched literally. */
+function escapeRegex(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Strip CSS comments, so a selector named in prose is never mistaken for a rule. */
+function rulesOnly(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Extract a rule's body by selector, tolerant of formatting and of nesting. */
+export function blockIn(source: string, selector: string): string {
+  const blocks = blocksIn(source, selector);
+  if (blocks.length === 0) throw new Error(`missing theme block: ${selector}`);
+  return blocks[0];
+}
+
+/**
+ * Every rule body whose selector list ENDS in `selector`, in source order — the
+ * match requires the selector immediately before the `{`, so a selector earlier
+ * in a comma-separated group (`selector, .other {`) is not returned.
+ *
+ * One selector can head MORE than one rule — `[data-theme="tangle-light"]` names
+ * both the shared light-status override group and the theme's own block — so a
+ * first-match read can silently slice the wrong region. Return them all and let
+ * the caller pick (e.g. the one that declares `--hsl-background`).
+ */
+export function blocksIn(source: string, selector: string): string[] {
+  // Comments first: a block's own doc-comment routinely spells its selector out,
+  // and anchoring on that prose would slice the wrong region — silently, since
+  // the result still looks like CSS.
+  const css = rulesOnly(source);
+  // Tolerate any whitespace between selector and brace — a formatter that closes
+  // the gap must not turn a passing suite into a "missing block" error.
+  const pattern = new RegExp(`${escapeRegex(selector)}\\s*\\{`, "g");
+
+  const blocks: string[] = [];
+  for (const open of css.matchAll(pattern)) {
+    const start = open.index;
+
+    // Walk braces to find THIS block's close. Matching the first `}` would end the
+    // block at the first nested rule's close instead (an `@media`, a nested
+    // selector) — and the slice would still look like CSS, so assertions would run
+    // against a truncated region rather than failing. Depth-counting is exact, and
+    // an unterminated block throws instead of returning something plausible.
+    let depth = 0;
+    let closed = false;
+    for (let i = css.indexOf("{", start); i < css.length; i++) {
+      if (css[i] === "{") depth += 1;
+      else if (css[i] === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          blocks.push(css.slice(start, i));
+          closed = true;
+          break;
+        }
+      }
+    }
+    if (!closed) throw new Error(`unterminated theme block: ${selector}`);
+  }
+  return blocks;
+}
+
+/** Read a token's raw declaration value, whitespace-normalized. */
+export function declIn(css: string, token: string): string {
+  const m = css.match(new RegExp(`--${token}:\\s*([^;]+)`));
+  if (!m) throw new Error(`missing token --${token}`);
+  return m[1].trim().replace(/\s+/g, " ");
+}
+
+/** Read an `H S% L%` channel triple. */
+export function hslIn(
+  css: string,
+  token: string,
+): { h: number; s: number; l: number } {
+  const m = css.match(
+    new RegExp(
+      `--${token}:\\s*(\\d+(?:\\.\\d+)?)\\s+(\\d+(?:\\.\\d+)?)%\\s+(\\d+(?:\\.\\d+)?)%`,
+    ),
+  );
+  if (!m) throw new Error(`missing HSL slot --${token}`);
+  return { h: Number(m[1]), s: Number(m[2]), l: Number(m[3]) };
+}
+
+type Rgb = [number, number, number];
+
+/**
+ * Read a hex surface token as RGB 0-255.
+ *
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` (alpha is dropped — compositing is a
+ * 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();
+  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}")`);
+  }
+
+  const digits = hex[1];
+  // #rgb is shorthand for #rrggbb; #rrggbbaa carries an alpha byte we drop.
+  const pairs =
+    digits.length === 3
+      ? [...digits].map((d) => d + d)
+      : [digits.slice(0, 2), digits.slice(2, 4), digits.slice(4, 6)];
+  return pairs.map((p) => Number.parseInt(p, 16)) as Rgb;
+}
+
+/** `H S% L%` → RGB 0-255. */
+export function hslToRgb({
+  h,
+  s,
+  l,
+}: {
+  h: number;
+  s: number;
+  l: number;
+}): Rgb {
+  const sat = s / 100;
+  const lit = l / 100;
+  const c = (1 - Math.abs(2 * lit - 1)) * sat;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = lit - c / 2;
+  const [r, g, b] =
+    h < 60
+      ? [c, x, 0]
+      : h < 120
+        ? [x, c, 0]
+        : h < 180
+          ? [0, c, x]
+          : h < 240
+            ? [0, x, c]
+            : h < 300
+              ? [x, 0, c]
+              : [c, 0, x];
+  return [(r + m) * 255, (g + m) * 255, (b + m) * 255];
+}
+
+function relativeLuminance([r, g, b]: Rgb): number {
+  const lin = (c: number) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/**
+ * What a translucent foreground actually becomes once the surface behind it shows
+ * through. A `/70` utility does not render the token's color — it renders this.
+ */
+export function compositeOver(fg: Rgb, bg: Rgb, alpha: number): Rgb {
+  return fg.map((c, i) => alpha * c + (1 - alpha) * bg[i]) as Rgb;
+}
+
+/** WCAG contrast ratio between two opaque colors. */
+export function contrastRatio(a: Rgb, b: Rgb): number {
+  const [hi, lo] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => y - x,
+  );
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Read a hex surface token as WCAG relative luminance (0-1).
+ *
+ * Relative luminance, not HSL lightness: the ladder varies hue and saturation as
+ * it rises, and HSL L is not perceptually uniform — two steps can share an L and
+ * still read as different brightnesses, so an "is each plane brighter than the one
+ * below" assertion made on HSL L would be measuring the wrong thing. Hex parsing
+ * (and its error reporting) is `hexIn`'s.
+ */
+export function hexRelativeLuminanceIn(css: string, token: string): number {
+  return relativeLuminance(hexIn(css, token));
+}

package/src/styles/index.css

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

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

@@ -2,7 +2,8 @@
  * components re-skin automatically because they reference the semantic tokens
  * (bg-card / border-border / surface-container, mapped in theme.css). Apply with
  * data-theme="<name>" on a wrapper (or <html>). The default :root / .dark spine
- * is the neutral "tangle" theme; "<name>-light" scopes are the light variants. */
+ * is the neutral "tangle" theme — also selectable by name as "tangle-dark";
+ * "<name>-light" scopes are the light variants. */
 
 /* Bridge — the actual re-skin mechanism. Tailwind utilities read the --color-*
  * layer (theme.css @theme: `bg-card` → var(--color-card) = hsl(var(--card))).
@@ -166,8 +167,42 @@
   --text-primary: #06231a; --text-secondary: #285048; --text-muted: #5f8472; --text-dim: #82a699;
 }
 
-/* ───────────────────────── Tangle (neutral) — light variant alias ─────────── */
-/* dark = default :root spine; this is its light mode for the showcase. */
+/* ───────────────────────── Tangle (neutral) — the canonical pair ──────────── */
+/* tangle-dark names the default :root/.dark spine explicitly — the values mirror
+ * tokens.css exactly (pinned in named-themes.test.ts). The named scope matters the
+ * moment the attribute would NOT resolve to :root: a dark island inside a
+ * light-named wrapper inherits the light --hsl-* without it, and a theme picker
+ * switching between named themes needs a `tangle-dark` that actually selects. Same
+ * indigo hue family as tangle-light (~239-246), held to the dark discipline —
+ * graphite-indigo neutrals, elevation by lightening, the fill indigo that carries
+ * white (7.4:1) with the bright indigo reserved for accent text. The foreground
+ * and destructive redeclares equal :root standalone, but the block must be
+ * self-sufficient: in the island nesting an omitted token inherits the WRAPPER's
+ * light value (near-black secondary text on the dark secondary measured ~1.5:1).
+ * Status tokens are deliberately not redeclared: the :root dark status palette is
+ * already dark-tuned, same as aubergine/arena. */
+[data-theme="tangle-dark"] {
+  --hsl-background: 240 24% 11%;  --hsl-foreground: 225 22% 91%;
+  --hsl-card: 238 20% 22%;        --hsl-card-foreground: 225 22% 91%;
+  --hsl-popover: 240 22% 27%;     --hsl-popover-foreground: 225 22% 91%;
+  --hsl-primary: 246 54% 51%;     --hsl-primary-foreground: 0 0% 100%;
+  --hsl-secondary: 240 22% 27%;   --hsl-secondary-foreground: 225 22% 91%;
+  --hsl-muted: 240 22% 27%;       --hsl-muted-foreground: 223 14% 69%;
+  --hsl-accent: 240 22% 27%;      --hsl-accent-foreground: 225 22% 91%;
+  --hsl-destructive: 348 74% 48%; --hsl-destructive-foreground: 0 0% 100%;
+  --hsl-border: 236 20% 35%;      --hsl-input: 240 24% 15%;
+  --hsl-ring: 233 100% 87%;
+  --depth-1: #151523; --depth-2: #2d2e43; --depth-3: #363654; --depth-4: #434365;
+  --bg-root: #151523; --bg-card: var(--depth-2); --bg-input: hsl(var(--hsl-input));
+  --md3-surface-container-lowest: #0f0f1a; --md3-surface-container-low: #222235;
+  --md3-surface-container: #2d2e43; --md3-surface-container-high: #363654;
+  --md3-surface-container-highest: #434365; --md3-outline-variant: #474a6b;
+  --border-subtle: rgba(165, 180, 252, 0.10); --border-default: rgba(165, 180, 252, 0.16);
+  --border-hover: rgba(165, 180, 252, 0.28); --accent-text: #A5B4FC;
+  --brand-primary: #7C6CF6; --brand-glow: #A5AAFC;
+  --text-primary: #e3e6ed; --text-secondary: #bec3d0; --text-muted: #a5abbb; --text-dim: #9299ab;
+}
+/* Its light mode. */
 [data-theme="tangle-light"] {
   --hsl-background: 240 33% 98%;  --hsl-foreground: 245 32% 14%;
   --hsl-card: 0 0% 100%;          --hsl-card-foreground: 245 32% 14%;
@@ -187,3 +222,58 @@
   --brand-primary: #6366f1; --brand-glow: #818cf8;
   --text-primary: #15131f; --text-secondary: #3f3a52; --text-muted: #6a6680; --text-dim: #9490a6;
 }
+
+/* ───────────────────── Intelligence — violet surface ramp ────────────────────
+ * A violet retint of the surface ladder (hue ~260-265, saturation tapering as
+ * lightness rises). The brand indigo primary / ring / accent-text are
+ * deliberately NOT overridden: the accent stays Tangle, only the surfaces carry
+ * the product's identity.
+ *
+ * Apply `data-theme="intelligence"` on <html> alongside the `.dark` class.
+ * The selector REQUIRES `.dark` rather than trusting the consumer to swap the
+ * attribute on every mode change: a violet dark ramp left standing over a light
+ * page would repaint every surface. Dark-only is the contract, so the selector —
+ * not the caller — enforces it. There is deliberately no `-light` variant;
+ * light falls through to brand's canonical light spine. */
+.dark[data-theme="intelligence"] {
+  --md3-surface: #0d0a10;
+  --md3-surface-dim: #0a080d;
+  --md3-surface-bright: #2e2936;
+  --md3-surface-container-lowest: #070509;
+  --md3-surface-container-low: #100d15;
+  --md3-surface-container: #14111a;
+  --md3-surface-container-high: #1b1821;
+  --md3-surface-container-highest: #24202b;
+  --md3-surface-variant: #24202b;
+  --md3-on-surface-variant: #aaa6bb;
+
+  --hsl-background: 262 24% 5%;
+  --hsl-card: 262 19% 11%;
+  --hsl-popover: 260 16% 13%;
+  --hsl-secondary: 262 15% 18%;
+  --hsl-muted: 262 17% 15%;
+  --hsl-muted-foreground: 255 12% 62%;
+  --hsl-accent: 262 15% 20%;
+  --hsl-border: 262 12% 28%;
+  --hsl-input: 260 14% 16%;
+
+  /* seated a touch deeper than the canvas so the panel reads as a base plane */
+  --sidebar-background: 264 26% 4%;
+  --sidebar-accent: 262 16% 16%;
+  --sidebar-border: 262 12% 13%;
+
+  --depth-1: #0e0b13;
+  --depth-2: #16131c;
+  --depth-3: #201c28;
+  --depth-4: #2a2533;
+  --bg-elevated: hsl(262 17% 15%);
+  --bg-section: hsl(262 22% 7%);
+  --bg-root:
+    radial-gradient(ellipse 70% 50% at 20% 0%, rgba(129, 99, 241, 0.08), transparent),
+    radial-gradient(ellipse 50% 40% at 80% 10%, rgba(129, 140, 248, 0.06), transparent),
+    linear-gradient(180deg, var(--depth-1), #0d0a12 100%);
+
+  --border-subtle: rgba(120, 108, 158, 0.1);
+  --border-default: rgba(120, 108, 158, 0.18);
+  --border-hover: rgba(120, 108, 158, 0.28);
+}