@crewlethq/tokens 0.2.0 → 0.4.0

package/dist/themes.js

@@ -0,0 +1,274 @@
+/* Generated by style-dictionary. Do not edit. */
+/**
+ * The two palettes, for JavaScript that cannot read a custom property: the
+ * tool chrome around a preview, a chart library that wants a series' colour
+ * as a string, a canvas that paints its own pixels.
+ *
+ * PREFER THE CUSTOM PROPERTY wherever CSS can reach: a value read here is a
+ * value taken at build time, so it does not follow a theme the reader
+ * changes. This is for the places where there is no element to read from.
+ */
+export const themes = {
+    "light": {
+        "color": {
+            "surface": {
+                "background": "#ffffff",
+                "subtle": "#f4f4f5",
+                "muted": "#f4f4f5",
+                "elevated": "#ebebee",
+                "topbar": "#ffffff",
+                "topbarLift": "#f4f4f5",
+                "topbarActive": "#ebebee",
+                "hover": "rgba(9, 9, 11, 0.04)",
+                "pressed": "rgba(9, 9, 11, 0.07)",
+                "inset": "rgba(9, 9, 11, 0.05)",
+                "glass": "rgba(244, 244, 245, 0.90)",
+                "scrim": "rgba(0, 0, 0, 0.6)",
+                "veil": "rgba(255, 255, 255, 0.72)",
+                "inverse": "#09090b"
+            },
+            "text": {
+                "primary": "#09090b",
+                "secondary": "#52525b",
+                "tertiary": "#5b5b64",
+                "muted": "#8f8f95",
+                "onBrand": "#ffffff",
+                "onAccent": "#ffffff",
+                "inverse": "#fafafa"
+            },
+            "brand": {
+                "primary": "#000000",
+                "primaryHover": "rgba(0, 0, 0, 0.85)",
+                "primaryActive": "rgba(0, 0, 0, 0.7)",
+                "accentInk": "#3e50b8",
+                "accentSoft": "rgba(84, 105, 212, 0.14)"
+            },
+            "border": {
+                "default": "#e4e4e7",
+                "hover": "#d4d4d8",
+                "strong": "#d4d4d8",
+                "strongHover": "#a1a1aa",
+                "control": "#71717a"
+            },
+            "focus": "#5469d4",
+            "feedback": {
+                "success": "#0f766e",
+                "successInk": "#115e59",
+                "warning": "#b45309",
+                "warningInk": "#92400e",
+                "danger": "#991b1b",
+                "dangerHover": "#7f1d1d",
+                "dangerInk": "#991b1b",
+                "info": "#075985",
+                "infoInk": "#075985",
+                "successSoft": "rgba(15, 118, 110, 0.12)",
+                "successLine": "rgba(15, 118, 110, 0.3)",
+                "warningSoft": "rgba(180, 83, 9, 0.12)",
+                "warningLine": "rgba(180, 83, 9, 0.3)",
+                "dangerSoft": "rgba(153, 27, 27, 0.12)",
+                "dangerLine": "rgba(153, 27, 27, 0.3)",
+                "infoSoft": "rgba(7, 89, 133, 0.12)",
+                "infoLine": "rgba(7, 89, 133, 0.3)"
+            },
+            "phase": {
+                "onboarding": "#980099",
+                "onboardingInk": "#8e0090",
+                "execute": "#5b37da",
+                "executeInk": "#552dd1",
+                "review": "#078543",
+                "reviewInk": "#006121",
+                "onboardingSoft": "rgba(152, 0, 153, 0.12)",
+                "executeSoft": "rgba(91, 55, 218, 0.12)",
+                "reviewSoft": "rgba(7, 133, 67, 0.12)"
+            },
+            "data": {
+                "1": "#3730a3",
+                "2": "#a16207",
+                "3": "#075985",
+                "4": "#1c9002",
+                "5": "#db2777",
+                "other": "#71717a"
+            },
+            "node": {
+                "purple": "#7150b3",
+                "purpleInk": "#573394",
+                "cyan": "#166b80",
+                "cyanInk": "#004f62",
+                "green": "#2c7046",
+                "greenInk": "#05532b",
+                "amber": "#865a28",
+                "amberInk": "#683e03",
+                "rose": "#984a55",
+                "roseInk": "#7a2f3c",
+                "blue": "#4062a7",
+                "blueInk": "#264588",
+                "purpleFill": "rgba(113, 80, 179, 0.12)",
+                "purpleLine": "rgba(113, 80, 179, 0.38)",
+                "purpleHalo": "rgba(113, 80, 179, 0.16)",
+                "cyanFill": "rgba(22, 107, 128, 0.12)",
+                "cyanLine": "rgba(22, 107, 128, 0.38)",
+                "cyanHalo": "rgba(22, 107, 128, 0.16)",
+                "greenFill": "rgba(44, 112, 70, 0.12)",
+                "greenLine": "rgba(44, 112, 70, 0.38)",
+                "greenHalo": "rgba(44, 112, 70, 0.16)",
+                "amberFill": "rgba(134, 90, 40, 0.12)",
+                "amberLine": "rgba(134, 90, 40, 0.38)",
+                "amberHalo": "rgba(134, 90, 40, 0.16)",
+                "roseFill": "rgba(152, 74, 85, 0.12)",
+                "roseLine": "rgba(152, 74, 85, 0.38)",
+                "roseHalo": "rgba(152, 74, 85, 0.16)",
+                "blueFill": "rgba(64, 98, 167, 0.12)",
+                "blueLine": "rgba(64, 98, 167, 0.38)",
+                "blueHalo": "rgba(64, 98, 167, 0.16)"
+            },
+            "scrollbar": "rgba(9, 9, 11, 0.2)",
+            "scrollbarHover": "rgba(9, 9, 11, 0.32)"
+        },
+        "shadow": {
+            "xs": "0 1px 2px rgba(9, 9, 11, 0.06)",
+            "sm": "0 2px 8px rgba(9, 9, 11, 0.07)",
+            "md": "0 4px 12px rgba(9, 9, 11, 0.08), 0 1px 3px rgba(9, 9, 11, 0.06)",
+            "lg": "0 8px 24px rgba(9, 9, 11, 0.12)",
+            "xl": "0 16px 40px rgba(9, 9, 11, 0.16), 0 2px 8px rgba(9, 9, 11, 0.08)",
+            "sheet": "-16px 0 40px rgba(9, 9, 11, 0.16), -2px 0 8px rgba(9, 9, 11, 0.08)",
+            "2xl": "0 16px 64px rgba(9, 9, 11, 0.20)",
+            "card": "0 8px 24px rgba(9, 9, 11, 0.07)",
+            "rimLit": "0 4px 24px rgba(9, 9, 11, 0.10), inset 0 1px 0 rgba(255, 255, 255, 0.6)",
+            "hairline": "none",
+            "focus": "0 0 0 2px var(--color-surface-background), 0 0 0 4px var(--color-focus)",
+            "selection": "inset 0 0 0 2px var(--color-brand-accent)",
+            "glow": "0 4px 24px rgba(84, 105, 212, 0.22)"
+        }
+    },
+    "dark": {
+        "color": {
+            "surface": {
+                "background": "#15171c",
+                "subtle": "#1c1e24",
+                "muted": "#1c1e24",
+                "elevated": "#22252b",
+                "topbar": "#15171c",
+                "topbarLift": "#1c1e24",
+                "topbarActive": "#22252b",
+                "hover": "rgba(255, 255, 255, 0.05)",
+                "pressed": "rgba(255, 255, 255, 0.08)",
+                "inset": "rgba(255, 255, 255, 0.05)",
+                "glass": "rgba(28, 30, 36, 0.90)",
+                "scrim": "rgba(0, 0, 0, 0.6)",
+                "veil": "rgba(21, 23, 28, 0.72)",
+                "inverse": "#ffffff"
+            },
+            "text": {
+                "primary": "#fafafa",
+                "secondary": "#c9ced8",
+                "tertiary": "#95a2b6",
+                "muted": "#686b70",
+                "onBrand": "#000000",
+                "onAccent": "#ffffff",
+                "inverse": "#09090b"
+            },
+            "brand": {
+                "primary": "#ffffff",
+                "primaryHover": "rgba(255, 255, 255, 0.9)",
+                "primaryActive": "rgba(255, 255, 255, 0.82)",
+                "accentInk": "#8b9ff5",
+                "accentSoft": "rgba(84, 105, 212, 0.18)"
+            },
+            "border": {
+                "default": "#3f4145",
+                "hover": "#4a4d52",
+                "strong": "#4a4d52",
+                "strongHover": "#5a5e65",
+                "control": "#7f848e"
+            },
+            "focus": "#8b9ff5",
+            "feedback": {
+                "success": "#14b8a6",
+                "successInk": "#5eead4",
+                "warning": "#f59e0b",
+                "warningInk": "#fde68a",
+                "danger": "#dc2626",
+                "dangerHover": "#b91c1c",
+                "dangerInk": "#fca5a5",
+                "info": "#38bdf8",
+                "infoInk": "#7dd3fc",
+                "successSoft": "rgba(20, 184, 166, 0.12)",
+                "successLine": "rgba(20, 184, 166, 0.3)",
+                "warningSoft": "rgba(245, 158, 11, 0.12)",
+                "warningLine": "rgba(245, 158, 11, 0.3)",
+                "dangerSoft": "rgba(220, 38, 38, 0.12)",
+                "dangerLine": "rgba(220, 38, 38, 0.3)",
+                "infoSoft": "rgba(56, 189, 248, 0.12)",
+                "infoLine": "rgba(56, 189, 248, 0.3)"
+            },
+            "phase": {
+                "onboarding": "#f77ae9",
+                "onboardingInk": "#ff82f1",
+                "execute": "#ac6bff",
+                "executeInk": "#d697ff",
+                "review": "#00a24f",
+                "reviewInk": "#46c872",
+                "onboardingSoft": "rgba(247, 122, 233, 0.12)",
+                "executeSoft": "rgba(172, 107, 255, 0.12)",
+                "reviewSoft": "rgba(0, 162, 79, 0.12)"
+            },
+            "data": {
+                "1": "#a5b4fc",
+                "2": "#facc15",
+                "3": "#38bdf8",
+                "4": "#86efac",
+                "5": "#ec4899",
+                "other": "#71717a"
+            },
+            "node": {
+                "purple": "#8e6ed4",
+                "purpleInk": "#cabae0",
+                "cyan": "#5ca8be",
+                "cyanInk": "#b3d7e0",
+                "green": "#62a578",
+                "greenInk": "#b8d8c0",
+                "amber": "#c89866",
+                "amberInk": "#e0c89e",
+                "rose": "#c8757f",
+                "roseInk": "#e0bfc4",
+                "blue": "#5b7fc7",
+                "blueInk": "#b9c5e0",
+                "purpleFill": "rgba(142, 110, 212, 0.12)",
+                "purpleLine": "rgba(142, 110, 212, 0.38)",
+                "purpleHalo": "rgba(142, 110, 212, 0.16)",
+                "cyanFill": "rgba(92, 168, 190, 0.12)",
+                "cyanLine": "rgba(92, 168, 190, 0.38)",
+                "cyanHalo": "rgba(92, 168, 190, 0.16)",
+                "greenFill": "rgba(98, 165, 120, 0.12)",
+                "greenLine": "rgba(98, 165, 120, 0.38)",
+                "greenHalo": "rgba(98, 165, 120, 0.16)",
+                "amberFill": "rgba(200, 152, 102, 0.12)",
+                "amberLine": "rgba(200, 152, 102, 0.38)",
+                "amberHalo": "rgba(200, 152, 102, 0.16)",
+                "roseFill": "rgba(200, 117, 127, 0.12)",
+                "roseLine": "rgba(200, 117, 127, 0.38)",
+                "roseHalo": "rgba(200, 117, 127, 0.16)",
+                "blueFill": "rgba(91, 127, 199, 0.12)",
+                "blueLine": "rgba(91, 127, 199, 0.38)",
+                "blueHalo": "rgba(91, 127, 199, 0.16)"
+            },
+            "scrollbar": "rgba(255, 255, 255, 0.16)",
+            "scrollbarHover": "rgba(255, 255, 255, 0.26)"
+        },
+        "shadow": {
+            "xs": "0 1px 2px rgba(0, 0, 0, 0.2)",
+            "sm": "0 2px 8px rgba(0, 0, 0, 0.15)",
+            "md": "0 4px 12px rgba(0, 0, 0, 0.25)",
+            "lg": "0 8px 24px rgba(0, 0, 0, 0.3)",
+            "xl": "0 12px 32px rgba(0, 0, 0, 0.4)",
+            "sheet": "-8px 0 32px rgba(0, 0, 0, 0.4)",
+            "2xl": "0 16px 64px rgba(0, 0, 0, 0.6)",
+            "card": "0 8px 24px rgba(0, 0, 0, 0.1)",
+            "rimLit": "0 4px 24px rgba(0, 0, 0, 0.3), inset 0 1px 0 rgba(255, 255, 255, 0.04)",
+            "hairline": "inset 0 1px 0 rgba(255, 255, 255, 0.04)",
+            "focus": "0 0 0 2px var(--color-surface-background), 0 0 0 4px var(--color-focus)",
+            "selection": "inset 0 0 0 2px var(--color-brand-accent)",
+            "glow": "0 4px 24px rgba(84, 105, 212, 0.3)"
+        }
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewlethq/tokens",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Crewlet design tokens. Single JSON source compiled to CSS variables and typed JS modules.",
   "license": "MIT AND OFL-1.1",
   "repository": {
@@ -25,22 +25,34 @@
       "import": "./dist/index.js"
     },
     "./css": "./dist/css/tokens.css",
+    "./css/base": "./dist/css/base.css",
+    "./css/breakpoint": "./dist/css/breakpoint.css",
+    "./css/density": "./dist/css/density.css",
     "./css/fonts": "./dist/css/fonts.css",
     "./css/legacy": "./dist/css/legacy.css",
     "./css/material-symbols": "./dist/css/material-symbols.css",
     "./css/themes": "./dist/css/themes.css",
-    "./fonts/*": "./fonts/*"
+    "./fonts/*": "./fonts/*",
+    "./test/palette": {
+      "types": "./test/palette.d.mts",
+      "import": "./test/palette.mjs"
+    }
   },
   "files": [
     "dist",
-    "fonts"
+    "fonts",
+    "test/color.mjs",
+    "test/palette.mjs",
+    "test/palette.d.mts",
+    "test/palette.test.mjs"
   ],
   "scripts": {
     "build": "node scripts/build.mjs && tsc -p tsconfig.json",
     "dev": "node scripts/build.mjs --watch",
-    "lint": "eslint scripts",
+    "lint": "eslint scripts test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist src/index.ts"
+    "test": "node --test \"test/*.test.mjs\"",
+    "clean": "rm -rf dist src/index.ts src/themes.ts"
   },
   "devDependencies": {
     "style-dictionary": "^5.5.3"

package/test/color.mjs

@@ -0,0 +1,262 @@
+/**
+ * Colour maths for the palette suite: sRGB, WCAG, OKLab and dichromat
+ * simulation, with no dependencies.
+ *
+ * This exists because the token files make promises that cannot be checked by
+ * reading them: that every text step clears contrast on the WORST surface it
+ * can land on (not the panel it was designed against), that a fill step is
+ * never used where a text step belongs, and that the categorical hues stay
+ * separable, including for red-green colour vision. Measured once by hand and
+ * written into a comment, those numbers rot silently. Here they are computed
+ * from the stylesheets that actually ship.
+ *
+ * It is published as part of `@crewlethq/tokens/test/palette`, so a consumer
+ * runs the same maths over the version it installed.
+ */
+
+/** @typedef {{ r: number, g: number, b: number }} RGB */
+
+// ---------------------------------------------------------------------------
+// Stylesheet parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Every custom-property block in a stylesheet, in source order, as
+ * `{ atRule, selector, declarations }`.
+ *
+ * A real (if small) parser rather than a regex over `([^{}]+)\{([^{}]*)\}`:
+ * the theme sheet nests its dark block inside `@media`, and a flat regex can
+ * only reach that block by failing to match the at-rule and picking the inner
+ * one up on a later pass. That works until an at-rule holds two blocks, or a
+ * selector repeats inside and outside one, and then it mis-reports rather than
+ * failing. `atRule` is the enclosing at-rule prelude, or null at the top level.
+ */
+export function parseBlocks(css) {
+  const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const blocks = [];
+  const stack = [];
+  let start = 0;
+  for (let i = 0; i < clean.length; i += 1) {
+    const ch = clean[i];
+    if (ch === '{') {
+      stack.push(clean.slice(start, i).trim());
+      start = i + 1;
+    } else if (ch === '}') {
+      const prelude = stack.pop();
+      if (prelude === undefined) throw new Error('unbalanced "}" in stylesheet');
+      const body = clean.slice(start, i);
+      // A block that holds another block is a wrapper (an at-rule); only the
+      // innermost blocks carry declarations.
+      if (!body.includes('{')) {
+        const enclosing = stack.at(-1);
+        for (const selector of prelude.split(',')) {
+          blocks.push({
+            atRule: enclosing === undefined ? null : enclosing,
+            selector: selector.trim(),
+            declarations: parseDeclarations(body),
+          });
+        }
+      }
+      start = i + 1;
+    }
+  }
+  if (stack.length > 0) throw new Error('unbalanced "{" in stylesheet');
+  return blocks;
+}
+
+/** The custom properties in one block body, as a Map in source order. */
+export function parseDeclarations(body) {
+  const declarations = new Map();
+  for (const line of body.split(';')) {
+    const index = line.indexOf(':');
+    if (index < 0) continue;
+    const name = line.slice(0, index).trim();
+    if (!name.startsWith('--')) continue;
+    declarations.set(name, line.slice(index + 1).trim());
+  }
+  return declarations;
+}
+
+/**
+ * Merge every block that matches, in cascade order, into one token map.
+ * `sources` are `{ name, css }` in IMPORT order, because these files share
+ * the `:root` selector and the later import is what a browser paints.
+ */
+export function cascade(sources, matches) {
+  const out = new Map();
+  for (const source of sources) {
+    for (const block of parseBlocks(source.css)) {
+      if (!matches(block)) continue;
+      for (const [name, value] of block.declarations) out.set(name, value);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Colour values
+// ---------------------------------------------------------------------------
+
+export function parseHex(hex) {
+  const match = /^#([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!match) return null;
+  const n = parseInt(match[1], 16);
+  return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+
+export function parseRgba(value) {
+  const match = /^rgba?\(([^)]+)\)$/i.exec(value.trim());
+  if (!match) return null;
+  const parts = match[1]
+    .split(/[,/\s]+/)
+    .filter(Boolean)
+    .map(Number);
+  const [r, g, b, a] = parts;
+  if (r === undefined || g === undefined || b === undefined) return null;
+  if ([r, g, b].some(Number.isNaN)) return null;
+  return { rgb: { r, g, b }, a: a === undefined ? 1 : a };
+}
+
+/** Composite a possibly translucent value over an opaque backdrop. */
+export function flatten(value, backdrop) {
+  const hex = parseHex(value);
+  if (hex) return hex;
+  const rgba = parseRgba(value);
+  if (!rgba) return null;
+  const { rgb, a } = rgba;
+  return {
+    r: rgb.r * a + backdrop.r * (1 - a),
+    g: rgb.g * a + backdrop.g * (1 - a),
+    b: rgb.b * a + backdrop.b * (1 - a),
+  };
+}
+
+/** The same colour at a new alpha, as the CSS value the build emits. */
+export function withAlpha(value, alpha) {
+  const rgb = parseHex(value) ?? parseRgba(value)?.rgb;
+  if (!rgb) throw new Error(`cannot re-alpha "${value}"`);
+  return `rgba(${Math.round(rgb.r)}, ${Math.round(rgb.g)}, ${Math.round(rgb.b)}, ${alpha})`;
+}
+
+// ---------------------------------------------------------------------------
+// WCAG
+// ---------------------------------------------------------------------------
+
+function channel(v) {
+  const c = v / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+export function luminance({ r, g, b }) {
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+export function contrast(a, b) {
+  const la = luminance(a);
+  const lb = luminance(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// ---------------------------------------------------------------------------
+// OKLab. Perceptual distance is what "these two hues are separable" means.
+// RGB distance says magenta and red are far apart and says the same of two
+// greens a reader cannot tell apart at 11px.
+// ---------------------------------------------------------------------------
+
+export function toOklab({ r, g, b }) {
+  const lr = channel(r);
+  const lg = channel(g);
+  const lb = channel(b);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+/** Perceptual distance, scaled to roughly CIE dE units so floors read familiar. */
+export function deltaE(x, y) {
+  const a = toOklab(x);
+  const b = toOklab(y);
+  return Math.hypot(a.L - b.L, a.a - b.a, a.b - b.b) * 100;
+}
+
+export function chroma(c) {
+  const { a, b } = toOklab(c);
+  return Math.hypot(a, b) * 100;
+}
+
+function fromLinear(v) {
+  const c = v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
+  return Math.min(255, Math.max(0, c * 255));
+}
+
+/** OKLab to sRGB, clipped. Used to search for the nearest passing value. */
+export function fromOklab({ L, a, b }) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ ** 3;
+  const m = m_ ** 3;
+  const s = s_ ** 3;
+  return {
+    r: Math.round(fromLinear(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s)),
+    g: Math.round(fromLinear(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s)),
+    b: Math.round(fromLinear(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)),
+  };
+}
+
+export const hex = ({ r, g, b }) =>
+  `#${[r, g, b].map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
+
+/**
+ * Move a colour along OKLab lightness only, keeping hue and chroma, until
+ * `ok` holds. A failing token moves MINIMALLY and inside its own hue family;
+ * that is what keeps a contrast fix from becoming a repaint.
+ */
+export function nudge(value, direction, ok, step = 0.002) {
+  const lab = toOklab(parseHex(value));
+  for (let i = 0; i <= 500; i += 1) {
+    const candidate = fromOklab({ L: lab.L + direction * step * i, a: lab.a, b: lab.b });
+    if (ok(candidate)) return { value: hex(candidate), dL: +(direction * step * i * 100).toFixed(1) };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Dichromat simulation (a Brettel/Vienot-style linear approximation)
+// ---------------------------------------------------------------------------
+
+/** Simulate protanopia or deuteranopia. Enough to answer "do these collide?". */
+export function simulate(c, kind) {
+  const r = channel(c.r);
+  const g = channel(c.g);
+  const b = channel(c.b);
+  const L = 0.31399022 * r + 0.63951294 * g + 0.04649755 * b;
+  const M = 0.15537241 * r + 0.75789446 * g + 0.08670142 * b;
+  const S = 0.01775239 * r + 0.10944209 * g + 0.87256922 * b;
+  let L2 = L;
+  let M2 = M;
+  const S2 = S;
+  if (kind === 'protan') L2 = 1.05118294 * M - 0.05116099 * S;
+  else M2 = 0.9513092 * L + 0.04866992 * S;
+  return {
+    r: fromLinear(5.47221206 * L2 - 4.6419601 * M2 + 0.16963708 * S2),
+    g: fromLinear(-1.1252419 * L2 + 2.29317094 * M2 - 0.1678952 * S2),
+    b: fromLinear(0.02980165 * L2 - 0.19318073 * M2 + 1.16364789 * S2),
+  };
+}
+
+/** The three visions every separation rule is measured under. */
+export const VISIONS = ['normal', 'protan', 'deutan'];
+
+/** One pair's separation under each vision, in VISIONS order. */
+export function separation(a, b) {
+  return VISIONS.map((vision) =>
+    vision === 'normal' ? deltaE(a, b) : deltaE(simulate(a, vision), simulate(b, vision)),
+  );
+}

package/test/palette.d.mts

@@ -0,0 +1,77 @@
+/**
+ * Types for the published palette suite.
+ *
+ * The implementation is plain JavaScript on purpose: it runs under `node
+ * --test` from a packed tarball, with no build step between the source and the
+ * gate. But it is a PUBLIC export, and both consumers of it are TypeScript,
+ * so the shape is declared here rather than inferred as `any` at each of them.
+ *
+ * Only the entry points are declared. The colour maths underneath is re-
+ * exported for a caller that wants to measure something of its own, and is
+ * typed loosely for that reason.
+ */
+
+/** One measured rule, over one state of the cascade. */
+export interface PaletteCheck {
+  /** Which set of values: 'base', 'light', 'dark (media)', 'dark (attribute)'. */
+  state: string;
+  /** The rule being kept, as a sentence. */
+  rule: string;
+  ok: boolean;
+  /** What was measured: a token name, or a pair of them. */
+  subject: string;
+  /** The measured number, or null for a structural rule that has none. */
+  value: number | null;
+  /** The measurement and its floor, ready to print. */
+  detail: string;
+}
+
+export interface PaletteSources {
+  /** The text of the built tokens.css. */
+  tokens: string;
+  /** The text of the built themes.css. */
+  themes: string;
+}
+
+export interface PaletteResult {
+  /** The resolved values in each state of the cascade. */
+  states: Record<string, Map<string, string>>;
+  checks: PaletteCheck[];
+  failures: PaletteCheck[];
+}
+
+/** Measure the whole rule table over one built pair of stylesheets. */
+export function runPalette(sources: PaletteSources): PaletteResult;
+
+/** The four sets of values a browser can end up with. */
+export function paletteStates(sources: PaletteSources): Record<string, Map<string, string>>;
+
+/** One line per failing check, for an assertion message. */
+export function describeFailure(check: PaletteCheck): string;
+
+/** The tightest measured value under each rule, for a report or a story. */
+export function tightest(checks: readonly PaletteCheck[]): PaletteCheck[];
+
+export interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export function contrast(a: Rgb, b: Rgb): number;
+export function deltaE(a: Rgb, b: Rgb): number;
+export function chroma(colour: Rgb): number;
+export function flatten(value: string, backdrop: Rgb): Rgb;
+export function parseHex(hex: string): Rgb | null;
+export function simulate(colour: Rgb, kind: string): Rgb;
+export function separation(a: Rgb, b: Rgb): number[];
+export const VISIONS: readonly string[];
+
+/** The token name of the modal veil. */
+export const VEIL: string;
+
+/** The band the veiled page has to stay inside, as [floor, ceiling]. */
+export const VEIL_BAND: readonly number[];
+
+/** The alpha the veil draws its own root's ground at. */
+export const VEIL_ALPHA: number;