@felloinnovations/brand-kit 0.4.0 → 0.5.0

package/scripts/token-model.mjs

@@ -0,0 +1,552 @@
+/**
+ * The kit's tokens as data, shared by scripts/generate-tokens.mjs (which writes every token file) and
+ * scripts/check-palette.mjs (which checks a palette against the contract). No side effects: it reads the sources.
+ *
+ *   tokens/_source.hubl.css   the kit (HubL interpolation resolved from design-tokens.json)
+ *   tokens/_product.css       the product layer (ws-*)
+ *   tokens/_dark.css          the dark theme: night, and the navy ground on top of it
+ *   tokens/_palettes.css      the built-in palettes, in the same form an app writes its own
+ *   tokens/design-tokens.json metadata, and the palette contract (group "palette")
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+export const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const read = (p) => readFileSync(join(root, p), 'utf8');
+
+export const meta = JSON.parse(read('tokens/design-tokens.json'));
+
+/* The three marketer-tunable brand colours are HubL expressions in the source (`{{ theme.brand.salmon.color }}`):
+   outside HubSpot they resolve to the Figma default the JSON records against the same themePath. */
+const byThemePath = Object.fromEntries(meta.colors.brand.filter((t) => t.themePath).map((t) => [t.themePath, t.value]));
+
+/* Tokens the shared kit owns. Everything else in the source is website page furniture, felix-theme's. */
+const KEEP = [
+  /^--color-/, /^--gradient-/, /^--font-body$/, /^--font-size-/, /^--letter-spacing-overline$/,
+  /^--space-(3xs|xxs|xxs-plus|xs|xs-plus|sm|sm-plus|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/,
+  /^--radius-/, /^--z-/, /^--shadow-/, /^--transition-/, /^--layout-(canvas-max|content-max|margin|col-gap)$/,
+];
+
+const stripComments = (css) => css.replace(/\{#[\s\S]*?#\}/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** The declarations of one block, in order. Values are multi-line (shadow stacks, gradients), so not line-based. */
+export function decls(block, keep, where) {
+  const out = [];
+  for (const m of block.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/gi)) {
+    const name = m[1];
+    if (keep && !keep.some((re) => re.test(name))) continue;
+    const value = m[2]
+      .replace(/\{\{\s*([a-z0-9_.]+)\s*\}\}/gi, (raw, path) => {
+        const hit = byThemePath[path];
+        if (!hit) throw new Error(`No JSON value for HubL path ${path} (token ${name}, ${where})`);
+        return hit;
+      })
+      .replace(/\s+/g, ' ')
+      .trim();
+    out.push([name, value]);
+  }
+  return out;
+}
+
+function parseRoot(css, keep = KEEP) {
+  const body = stripComments(css);
+  // Only the top-level :root block. The trailing @media override is website section rhythm, not shipped.
+  const media = body.indexOf('@media');
+  return decls(body.slice(body.indexOf(':root'), media === -1 ? undefined : media), keep, ':root');
+}
+
+/** The declarations of the block whose selector is exactly `selector`. */
+function parseBlock(css, selector, file) {
+  const body = stripComments(css);
+  const at = body.indexOf(`${selector} {`);
+  if (at === -1) throw new Error(`${file} has no "${selector} {" block`);
+  return decls(body.slice(at + selector.length + 2, body.indexOf('}', at)), null, selector);
+}
+
+/* ---- Springs as CSS (D7): Seth's presets (motion.springs) sampled into linear() curves ----
+   The motion library's own spring (North app.js, KN and N5): from {visualDuration, bounce} a damping ratio of
+   1 - bounce (at least .05) and an undamped frequency of 2 pi / (visualDuration x 1.2); it runs from 0 to 1 until it
+   is within .005 of 1 and slower than .01 a second, checked every 50 ms (El), which is the CSS duration. The curve is
+   that spring sampled evenly, as few points as keep it within SPRING_FIT of the solver everywhere (overshoot kept).
+   generate-tokens re-reads each emitted curve and stops when it strays past SPRING_CHECK. */
+export const SPRING_FIT = 0.005;
+export const SPRING_CHECK = 0.01;
+/** The spring's value at t ms (0 to 1, past 1 on an overshoot) and the ms it takes to settle. */
+export function springSolver({ visualDuration, bounce = 0 }) {
+  const zeta = bounce < 0 ? 1 / Math.max(1 + bounce, 0.05) : Math.max(1 - bounce, 0.05);
+  const w = (2 * Math.PI) / (visualDuration * 1.2) / 1000; // rad per ms
+  let value, speed; // speed in units per ms
+  if (zeta < 1) {
+    const wd = w * Math.sqrt(1 - zeta * zeta), m = zeta * w, A = m / wd;
+    value = (t) => 1 - Math.exp(-m * t) * (A * Math.sin(wd * t) + Math.cos(wd * t));
+    speed = (t) => Math.exp(-m * t) * ((m * A + wd) * Math.sin(wd * t) + (m - A * wd) * Math.cos(wd * t));
+  } else {
+    value = (t) => 1 - Math.exp(-w * t) * (1 + w * t);
+    speed = (t) => Math.exp(-w * t) * w * w * t;
+  }
+  const settled = (t) => Math.abs(speed(t) * 1000) <= 0.01 && Math.abs(1 - value(t)) <= 0.005;
+  let duration = 0;
+  while (!settled(duration) && duration < 20000) duration += 50;
+  return { value, duration };
+}
+/** A linear() curve's value at progress p (0 to 1), its stops evenly spaced. */
+export const linearAt = (stops, p) => {
+  const f = Math.min(Math.max(p, 0), 1) * (stops.length - 1), i = Math.min(Math.floor(f), stops.length - 2);
+  return stops[i] + (stops[i + 1] - stops[i]) * (f - i);
+};
+/** The furthest the stops stray from the spring, sampled every quarter millisecond. */
+export function springError(stops, { value, duration }) {
+  let worst = 0;
+  for (let t = 0; t <= duration; t += 0.25) worst = Math.max(worst, Math.abs(linearAt(stops, t / duration) - value(t)));
+  return worst;
+}
+export function springCurve(preset) {
+  const s = springSolver(preset);
+  const sample = (n) => Array.from({ length: n }, (_, i) => (i === n - 1 ? 1 : Math.round(s.value((i / (n - 1)) * s.duration) * 1e4) / 1e4));
+  let n = 8;
+  while (springError(sample(n), s) > SPRING_FIT) n++;
+  return { duration: s.duration, css: `linear(${sample(n).join(', ')})` };
+}
+export const springs = Object.entries(meta.motion.springs).filter(([k]) => !k.startsWith('$'));
+export const springName = (k) => `--ws-spring-${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+const springTokens = springs.flatMap(([k, preset]) => {
+  const { duration, css } = springCurve(preset);
+  return [[springName(k), css], [`${springName(k)}-duration`, `${duration}ms`]];
+});
+
+export const kit = parseRoot(read('tokens/_source.hubl.css'));
+if (kit.length < 80) throw new Error(`Only parsed ${kit.length} kit tokens, source changed shape`);
+export const product = [...parseRoot(read('tokens/_product.css'), [/^--ws-/]), ...springTokens];
+if (product.length < 100) throw new Error(`Only parsed ${product.length} product tokens, source changed shape`);
+export const tokens = [...kit, ...product];
+const dupes = tokens.map(([n]) => n).filter((n, i, all) => all.indexOf(n) !== i);
+if (dupes.length) throw new Error(`Declared twice: ${dupes.join(', ')}`);
+export const known = new Set(tokens.map(([n]) => n));
+
+const darkCss = read('tokens/_dark.css');
+export const night = parseBlock(darkCss, ':root[data-theme="dark"]', 'tokens/_dark.css');
+export const navy = parseBlock(darkCss, ':root[data-theme="dark"][data-ground="navy"]', 'tokens/_dark.css');
+for (const [n] of [...night, ...navy]) if (!known.has(n)) throw new Error(`tokens/_dark.css sets ${n}, which no light source declares`);
+
+/* ---- The palette contract (design-tokens.json "palette"): the tokens an app may set. Everything else is derived. ---- */
+export const contract = (meta.palette?.tokens ?? []).filter((t) => !t.name.startsWith('$'));
+export const CONTRACT = new Set(contract.map((t) => t.name));
+for (const n of CONTRACT) if (!known.has(n)) throw new Error(`design-tokens.json palette lists ${n}, which is not a token`);
+
+/* ---- Theme maps: the raw values (var(), color-mix()) in light, night and the navy ground ---- */
+export const themeMaps = (over = {}) => {
+  const light = { ...Object.fromEntries(tokens), ...(over.light || {}) };
+  const dark = { ...Object.fromEntries(tokens), ...Object.fromEntries(night), ...(over.dark || {}) };
+  // the navy ground sits on top of whatever dark the palette gives, and wins where it sets a token
+  const navyMap = { ...dark, ...Object.fromEntries(navy) };
+  return { light, dark, navy: navyMap };
+};
+
+/* ---- Colour: parsing, color-mix, WCAG contrast, CIEDE2000 ---- */
+const NAMED = { transparent: [0, 0, 0, 0], white: [255, 255, 255, 1], black: [0, 0, 0, 1] };
+/** A colour as [r, g, b, a] (0..255, alpha 0..1), or null when it is not a plain colour. */
+export function parseColour(c) {
+  c = c.trim().toLowerCase();
+  if (c in NAMED) return NAMED[c];
+  let m = c.match(/^#([0-9a-f]{3,8})$/);
+  if (m) {
+    let h = m[1];
+    if (h.length === 3 || h.length === 4) h = [...h].map((x) => x + x).join('');
+    if (h.length !== 6 && h.length !== 8) return null;
+    const v = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+    return [...v, h.length === 8 ? parseInt(h.slice(6), 16) / 255 : 1];
+  }
+  m = c.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/);
+  if (m) {
+    const a = m[4] === undefined ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
+    return [+m[1], +m[2], +m[3], a];
+  }
+  return null;
+}
+export const hex = ([r, g, b]) => `#${[r, g, b].map((x) => Math.round(x).toString(16).padStart(2, '0')).join('')}`;
+export const formatColour = (c) => (c[3] === 0 && !c[0] && !c[1] && !c[2] ? 'transparent' : c[3] === 1 ? hex(c) : `rgba(${c.slice(0, 3).map(Math.round).join(', ')}, ${+c[3].toFixed(3)})`);
+
+/* color-mix(in srgb, a p%, b): CSS mixes premultiplied, so mixing toward transparent keeps the colour and lowers alpha. */
+export function mix(a, p, b, q = 100 - p) {
+  const [A, B] = [parseColour(a), parseColour(b)];
+  if (!A || !B) throw new Error(`color-mix input ${!A ? a : b} is not a colour`);
+  const total = p + q;
+  const [pa, pb] = [p / total, q / total];
+  const alpha = A[3] * pa + B[3] * pb;
+  if (!alpha) return 'transparent';
+  const ch = [0, 1, 2].map((i) => Math.round((A[i] * A[3] * pa + B[i] * B[3] * pb) / alpha));
+  return formatColour([...ch, alpha * Math.min(1, total / 100)]);
+}
+
+const MIX = /color-mix\(\s*in srgb,\s*(#[0-9a-f]+|transparent|rgba?\([^()]*\))(?:\s+([\d.]+)%)?\s*,\s*(#[0-9a-f]+|transparent|rgba?\([^()]*\))(?:\s+([\d.]+)%)?\s*\)/gi;
+/** Every color-mix() reduced, innermost first, until none is left (a mix may take another mix as its partner). */
+const mixes = (value) => {
+  for (let prev; prev !== value; ) {
+    prev = value;
+    value = value.replace(MIX, (_, a, p, b, q) => {
+      const P = p !== undefined ? +p : q !== undefined ? 100 - +q : 50;
+      const Q = q !== undefined ? +q : 100 - P;
+      return mix(a, P, b, Q);
+    });
+  }
+  return value;
+};
+
+/** A resolver for one theme map: var(), color-mix() and calc() on one unit reduced to what they paint. */
+export function resolverFor(src) {
+  const resolve = (value, seen = []) =>
+    mixes(
+      value.replace(/var\(\s*(--[a-z0-9-]+)\s*(?:,\s*([^()]*))?\)/g, (_, n, fallback) => {
+        if (!(n in src)) {
+          if (fallback !== undefined) return resolve(fallback, seen);
+          throw new Error(`var(${n}) is not a token`);
+        }
+        if (seen.includes(n)) throw new Error(`Alias cycle: ${[...seen, n].join(' -> ')}`);
+        return resolve(src[n], [...seen, n]);
+      })
+    )
+      .replace(/calc\(([^()]*)\)/g, (_, expr) => {
+        const units = new Set(expr.match(/[a-z%]+/gi));
+        if (units.size !== 1) throw new Error(`calc(${expr}) mixes units`);
+        const [unit] = units;
+        const math = expr.replaceAll(unit, '');
+        if (!/^[\d.\s+*/-]+$/.test(math)) throw new Error(`calc(${expr}) is not plain arithmetic`);
+        return `${+Function(`return (${math})`)().toFixed(4)}${unit}`;
+      })
+      .replace(/#[0-9a-f]{3,8}\b/gi, (h) => h.toLowerCase())
+      .replace(/\s+/g, ' ')
+      .trim();
+  return resolve;
+}
+
+/** Every theme of a palette (or the kit, with no palette) resolved: { light, dark, navy } of name -> literal. */
+export function resolved(over) {
+  const maps = themeMaps(over);
+  const out = {};
+  for (const [theme, map] of Object.entries(maps)) {
+    const r = resolverFor(map);
+    out[theme] = Object.fromEntries(
+      Object.entries(map).map(([n, v]) => {
+        try {
+          return [n, r(v)];
+        } catch {
+          return [n, v]; // a value the resolver cannot reduce (a gradient over a mix) stays as written
+        }
+      })
+    );
+  }
+  return out;
+}
+
+/** An opaque colour for contrast: a translucent one is composited over `ground` (the colour it sits on). */
+export function opaque(c, ground = '#ffffff') {
+  const C = parseColour(c);
+  if (!C) throw new Error(`${c} is not a colour`);
+  if (C[3] === 1) return C;
+  const G = opaque(ground);
+  return [0, 1, 2].map((i) => C[i] * C[3] + G[i] * (1 - C[3])).concat(1);
+}
+const lin = (v) => ((v /= 255) <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+const luminance = (c) => {
+  const [r, g, b] = (Array.isArray(c) ? c : opaque(c)).map(lin);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+/** WCAG 2.x contrast of `fg` on `bg` (a translucent fg is composited on bg; a translucent bg on white). */
+export function ratio(fg, bg) {
+  const B = opaque(bg);
+  const F = opaque(fg, hex(B));
+  const [x, y] = [luminance(F), luminance(B)].sort((m, n) => n - m);
+  return (x + 0.05) / (y + 0.05);
+}
+
+/** CIEDE2000 colour difference of two colours (each composited on `ground` if translucent). */
+export function deltaE(a, b, ground = '#ffffff') {
+  const lab = (c) => {
+    const [r, g, bl] = opaque(c, ground).map(lin);
+    const xyz = [
+      (0.4124564 * r + 0.3575761 * g + 0.1804375 * bl) / 0.95047,
+      0.2126729 * r + 0.7151522 * g + 0.072175 * bl,
+      (0.0193339 * r + 0.119192 * g + 0.9503041 * bl) / 1.08883,
+    ].map((t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116));
+    return [116 * xyz[1] - 16, 500 * (xyz[0] - xyz[1]), 200 * (xyz[1] - xyz[2])];
+  };
+  const [L1, a1, b1] = lab(a), [L2, a2, b2] = lab(b);
+  const rad = Math.PI / 180, deg = 180 / Math.PI;
+  const C1 = Math.hypot(a1, b1), C2 = Math.hypot(a2, b2), Cm = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cm ** 7 / (Cm ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * a1, a2p = (1 + G) * a2;
+  const C1p = Math.hypot(a1p, b1), C2p = Math.hypot(a2p, b2);
+  const h = (bb, ap) => (bb === 0 && ap === 0 ? 0 : (Math.atan2(bb, ap) * deg + 360) % 360);
+  const h1p = h(b1, a1p), h2p = h(b2, a2p);
+  const dLp = L2 - L1, dCp = C2p - C1p;
+  let dhp = C1p * C2p === 0 ? 0 : h2p - h1p;
+  if (dhp > 180) dhp -= 360; else if (dhp < -180) dhp += 360;
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * rad);
+  const Lpm = (L1 + L2) / 2, Cpm = (C1p + C2p) / 2;
+  let hpm = h1p + h2p;
+  if (C1p * C2p !== 0) hpm = Math.abs(h1p - h2p) <= 180 ? hpm / 2 : (hpm + (hpm < 360 ? 360 : -360)) / 2;
+  const T = 1 - 0.17 * Math.cos((hpm - 30) * rad) + 0.24 * Math.cos(2 * hpm * rad) + 0.32 * Math.cos((3 * hpm + 6) * rad) - 0.2 * Math.cos((4 * hpm - 63) * rad);
+  const dTheta = 30 * Math.exp(-(((hpm - 275) / 25) ** 2));
+  const Rc = 2 * Math.sqrt(Cpm ** 7 / (Cpm ** 7 + 25 ** 7));
+  const Sl = 1 + (0.015 * (Lpm - 50) ** 2) / Math.sqrt(20 + (Lpm - 50) ** 2), Sc = 1 + 0.045 * Cpm, Sh = 1 + 0.015 * Cpm * T;
+  const Rt = -Math.sin(2 * dTheta * rad) * Rc;
+  return Math.sqrt((dLp / Sl) ** 2 + (dCp / Sc) ** 2 + (dHp / Sh) ** 2 + Rt * (dCp / Sc) * (dHp / Sh));
+}
+
+/* ---- Where words sit (D2, D12): the grounds every word token is gated on, and the pairs on their own tints ---- */
+export const GROUNDS = {
+  '--color-bg-page': 'cream', '--color-surface': 'white', '--ws-surface-sunk': 'plate', '--ws-tray': 'tray', '--ws-raised': 'raised',
+  '--ws-page': 'shell', '--ws-surface-press': 'press', '--ws-well': 'well', '--ws-raised-sunk': 'raised sunk',
+  '--ws-tint-accent': 'accent tint', '--ws-tint-needs': 'needs tint', '--ws-tint-live': 'live tint', '--ws-card-tint-blue': 'blue card',
+  '--ws-card-tint-done': 'done card', '--ws-chart-foot': 'chart foot', '--ws-sidebar-hover': 'sidebar hover', '--ws-menu-hover': 'menu hover',
+  '--color-surface-stripe': 'stripe',
+};
+// Reported, not gated: grounds that carry only their own words (a PAIR below), or a frame under the pointer.
+export const REPORT = { '--ws-tint-needs-work': 'needs-work tint', '--color-feedback-success-bg': 'success', '--ws-well-hover': 'well hover' };
+export const WORDS = [
+  '--color-text-heading', '--color-text-body', '--color-text-muted', '--color-text-interactive',
+  '--color-text-brand-strong', '--color-text-error-strong', '--color-text-success-strong',
+  '--ws-word-needs', '--ws-word-positive', '--ws-word-needs-work', '--ws-word-alert', '--ws-word-past-half', '--ws-word-answer',
+];
+export const PAIRS = [
+  ['--color-text-placeholder', '--ws-field'], ['--ws-field-ink', '--ws-field'], ['--ws-on-act', '--color-text-heading'],
+  ['--ws-word-needs', '--ws-tint-needs'], ['--ws-word-positive', '--ws-tint-live'], ['--ws-word-needs-work', '--ws-tint-needs-work'],
+  ['--color-text-success-strong', '--color-feedback-success-bg'], ['--ws-on-act', '--ws-agent-tally'],
+];
+
+/* ---- A palette file: `[data-palette="name"] { ... }` for light, the same with [data-theme="dark"] for dark ---- */
+/** Parses palette CSS (tokens/_palettes.css, an app's own file, or what `check-palette --emit` writes) into
+ *  { name: { light: {..}, dark: {..} } }. A rule's palette is the [data-palette="..."] in its selector or in the
+ *  @scope around it; it is dark when either names [data-theme="dark"], or [data-theme="system"] inside a
+ *  prefers-color-scheme: dark @media ("system" outside one is light). A rule under the navy ground is the kit's, not
+ *  the palette's. Anything else in the file is returned in `other` so the check can say so. */
+export function parsePalettes(css) {
+  const palettes = {};
+  const other = [];
+  const NAME = /\[data-palette\s*=\s*["']?([\w-]+)["']?\s*\]/g;
+  const walk = (text, ctx) => {
+    for (let i = 0; i < text.length; ) {
+      const open = text.indexOf('{', i);
+      if (open === -1) return;
+      const prelude = text.slice(i, open).replace(/^[\s;]+/, '').trim();
+      let depth = 1, j = open + 1;
+      for (; j < text.length && depth; j++) depth += text[j] === '{' ? 1 : text[j] === '}' ? -1 : 0;
+      const inner = text.slice(open + 1, j - 1);
+      i = j;
+      if (prelude.startsWith('@media')) walk(inner, { ...ctx, darkOs: ctx.darkOs || /prefers-color-scheme:\s*dark/.test(prelude) });
+      else if (prelude.startsWith('@scope')) walk(inner, { ...ctx, scope: `${ctx.scope} ${prelude}` });
+      else if (prelude.startsWith('@')) walk(inner, ctx); // @layer, @supports
+      else {
+        const where = `${ctx.scope} ${prelude}`;
+        const names = [...where.matchAll(NAME)].map(([, n]) => n);
+        if (!names.length) {
+          if (inner.trim()) other.push(prelude);
+          continue;
+        }
+        if (/data-ground/.test(where)) continue;
+        const dark = /\[data-theme\s*=\s*["']?dark["']?\s*\]/.test(where) || (ctx.darkOs && /\[data-theme\s*=\s*["']?system["']?\s*\]/.test(where));
+        for (const name of new Set(names)) {
+          const p = (palettes[name] ??= { light: {}, dark: {} });
+          for (const [n, v] of decls(inner, null, prelude)) (dark ? p.dark : p.light)[n] = v;
+        }
+      }
+    }
+  };
+  walk(stripComments(css), { darkOs: false, scope: '' });
+  return { palettes, other };
+}
+
+export const builtIns = () => parsePalettes(read('tokens/_palettes.css')).palettes;
+
+/* ---- The token stylesheet: every theme and palette on any element (D12, D15) ------------------------------------
+   A custom property's var() resolves on the element that declares it, so a token derived from another (a hover from
+   the page, an edge from the heading) would keep the :root result inside a container that sets its own palette or
+   theme. So every derived token is declared again on each element that can change the context: [data-palette],
+   [data-theme] and .fello (the carriers). The contract tokens (the palette's inputs) are never declared again there,
+   so a palette set on a container reaches everything inside it.
+
+   The theme is nearest-wins on any element: a theme root ([data-theme="dark"], "system" on a dark OS, "light", and
+   the navy ground beside dark) sets its theme's values on itself, and its derived tokens on the carriers inside it
+   through @scope, whose proximity picks the nearest root, so light inside dark and dark inside light both work.
+   A palette and a theme set on different elements meet the same way: a palette inside a theme takes the palette's
+   values for that theme, and a theme inside a palette takes that theme's palette values. The navy ground wins over a
+   palette where it sets a token (it is a brand ground). Browsers without @scope get the theme on the element that
+   carries it (the common case: <html data-theme>) and lose only the nesting.
+
+   Load order never matters (D15): the kit's own contract values sit at no specificity (:where(:root), and every
+   [data-palette] element's reset), a palette's rules weigh one attribute or more, and where two rules weigh the same
+   @scope proximity decides. So an app's palette, written by `check-palette --emit` in the built-ins' form, nests
+   exactly like a built-in in either build, before or after the kit. */
+const LIGHT = Object.fromEntries(tokens);
+const NIGHT = Object.fromEntries(night);
+const NAVY = Object.fromEntries(navy);
+const isExpr = (v) => typeof v === 'string' && /var\(/.test(v);
+/** Whether a token's value (in light, night or navy) reads, through any chain of var(), a contract token or a token a
+ *  theme changes: only those can differ inside a container, so only those are declared again there. */
+const VARIES = new Set([...CONTRACT, ...Object.keys(NIGHT), ...Object.keys(NAVY)]);
+const memo = new Map();
+const varies = (n, seen = new Set()) => {
+  if (memo.has(n)) return memo.get(n);
+  if (seen.has(n)) return false;
+  seen.add(n);
+  const out = [LIGHT[n], NIGHT[n], NAVY[n]].some((v) => [...(v || '').matchAll(/var\(\s*(--[a-z0-9-]+)/g)].some(([, r]) => VARIES.has(r) || varies(r, seen)));
+  memo.set(n, out);
+  return out;
+};
+/** Non-contract tokens derived in light from something that can change: re-declared on every carrier. */
+const DERIVED = tokens.filter(([n, v]) => !CONTRACT.has(n) && isExpr(v) && varies(n)).map(([n]) => n);
+/** Non-contract tokens a theme sets that a carrier must re-declare under it: the ones every carrier re-declares in
+ *  light, and the ones the theme derives from something that can change. */
+const readsVarying = (v = '') => [...v.matchAll(/var\(\s*(--[a-z0-9-]+)/g)].some(([, r]) => VARIES.has(r) || varies(r));
+const themeDerived = (block, below = {}) =>
+  Object.keys(block).filter((n) => !CONTRACT.has(n) && (DERIVED.includes(n) || readsVarying(below[n]) || readsVarying(block[n])));
+const TD_DARK = themeDerived(NIGHT);
+const TD_NAVY = themeDerived(NAVY, NIGHT);
+const TD_LIGHT = [...new Set([...TD_DARK, ...TD_NAVY])];
+/** Contract tokens the kit derives (var()): a theme root states them again, so they follow its theme. */
+const contractDerived = (map) => [...CONTRACT].filter((n) => isExpr(map[n]));
+
+const pick = (names, map) => names.map((n) => [n, map[n]]);
+const decl = (pairs, pad) => pairs.map(([n, v]) => `${pad}${n}: ${v};`).join('\n');
+const rule = (sel, pairs, pad = '', extra = '') => `${pad}${sel} {\n${extra ? `${pad}  ${extra}\n` : ''}${decl(pairs, `${pad}  `)}\n${pad}}`;
+const darkOs = (css) => `@media (prefers-color-scheme: dark) {\n${css.replace(/^/gm, '  ')}\n}`;
+const list = (s) => s.split(/,\s*/);
+
+/** The contract tokens a palette sets, in light or dark. */
+export const ownNames = (p) => [...CONTRACT].filter((n) => n in p.light || n in p.dark);
+
+/** A palette's values for `names`: what it says, else the kit's own expression in that theme, so a dark value it
+ *  leaves out is the kit's dark one (derived from its dark inputs), never its light one (D15). `fellBack` lists those. */
+export function paletteValues(p, names = ownNames(p)) {
+  const fellBack = Object.keys(p.light).filter((n) => !(n in p.dark));
+  return {
+    light: names.map((n) => [n, p.light[n] ?? LIGHT[n]]),
+    dark: names.map((n) => [n, p.dark[n] ?? NIGHT[n] ?? LIGHT[n]]),
+    fellBack,
+  };
+}
+
+/** The kit's own values where a palette may meet them: a contract token at no specificity (`zero`), so any palette
+ *  beats it whichever loads first; every other token as it was (`sel`), so a host's element selector cannot reach it. */
+export const splitRule = (sel, zero, pairs, pad = '', extra = '') => {
+  const own = pairs.filter(([n]) => !CONTRACT.has(n)), input = pairs.filter(([n]) => CONTRACT.has(n));
+  return [own.length || extra ? rule(sel, own, pad, extra) : '', input.length ? rule(zero, input, pad) : ''].filter(Boolean).join('\n');
+};
+
+/** The selectors of one build. Root: tokens.root.css, tokens.css, fello.css. Scoped: fello.scoped.css, where every rule
+ *  stays inside a .fello island and the theme may come from the host. Both weigh the same (.fello sits in :where()), so
+ *  a palette, an app's own or a built-in, meets the kit's rules on specificity and proximity alone, in either build. */
+function selectors(mode) {
+  const scoped = mode === 'scoped';
+  return {
+    scoped,
+    ROOT: scoped ? '.fello:not(:where(.fello) *)' : ':root',
+    ROOT0: scoped ? ':where(.fello):not(:where(.fello) *)' : ':where(:root)',
+    // an element in the island, outside @scope (a descendant selector), and inside one (the subject itself anchored: a
+    // scoped selector is relative to its root, so a .fello between the two could not be asked for)
+    at: (sels) => list(sels).flatMap((s) => (scoped ? [`:where(.fello)${s}`, `:where(.fello) ${s}`] : [s])).join(', '),
+    inner: (sels) => list(sels).map((s) => (scoped ? `${s}:where(.fello, .fello *)` : s)).join(', '),
+    CARRIERS: scoped ? '[data-palette]:where(.fello *), .fello' : '[data-palette], .fello',
+    SELF: scoped ? ':scope:where(.fello, .fello *)' : ':scope',
+    RESET: scoped ? ':where([data-palette]):where(.fello, .fello *)' : ':where([data-palette])',
+  };
+}
+const ROOTS = { light: '[data-theme="light"], [data-theme="system"]', dark: '[data-theme="dark"]', navy: '[data-theme="dark"][data-ground="navy"]' };
+const SYSTEM = { dark: '[data-theme="system"]', navy: '[data-theme="system"][data-ground="navy"]' };
+
+/* The navy ground over a palette: a brand ground, so where it sets a contract token it wins over a palette's dark value,
+   on the same element (three attributes) and inside it (the palette attribute counted twice), whichever loads first,
+   down to the next theme root inside it. The kit writes it once for every palette; an app's shipped palette carries
+   its own copy, since in fello.css the kit's sits in a layer an unlayered palette always beats. */
+function navyOverCss(P, mode) {
+  const { at, inner } = selectors(mode);
+  const set = pick([...CONTRACT].filter((n) => n in NAVY), NAVY);
+  const over = (roots) =>
+    [rule(list(roots).map((r) => at(`${P}${r}`)).join(', '), set), `@scope (${roots}) to ([data-theme]) {\n${rule(inner(`${P}[data-palette]`), set, '  ')}\n}`].join('\n');
+  return [over(ROOTS.navy), darkOs(over(SYSTEM.navy))].join('\n');
+}
+
+/** One palette's rules: its light values on itself, and each theme's values wherever that theme meets it (on the same
+ *  element, a theme around it, a theme inside it); the nearest wins. The form the built-ins ship in, and what
+ *  `check-palette --emit` writes for an app's own palette (with `navy`, its own copy of the navy ground's override),
+ *  so both nest the same way in either build. */
+export function paletteCss(id, p, mode = 'root', { navy: withNavy = false } = {}) {
+  const S = selectors(mode);
+  const P = `[data-palette="${id}"]`;
+  const v = paletteValues(p);
+  if (!v.light.length) return `/* ${id}: sets no contract token */`;
+  const forTheme = (vals, roots) =>
+    [
+      rule(list(roots).map((r) => S.at(`${P}${r}`)).join(', '), vals),
+      `@scope (${roots}) {\n${rule(S.inner(P), vals, '  ')}\n}`,
+      `@scope (${P}) {\n${rule(S.inner(roots), vals, '  ')}\n}`,
+    ].join('\n');
+  return [`/* ${id} */`, rule(S.at(P), v.light), forTheme(v.light, ROOTS.light), forTheme(v.dark, ROOTS.dark), darkOs(forTheme(v.dark, SYSTEM.dark)), ...(withNavy ? [navyOverCss(P, mode)] : [])].join('\n');
+}
+
+/** The token stylesheet after the :root block: `mode` "root" (tokens.root.css, tokens.css, fello.css) or "scoped"
+ *  (fello.scoped.css, where every rule stays inside a .fello island and a theme or palette may come from the host). */
+export function contextCss(mode, palettes) {
+  const { scoped, ROOT, ROOT0, at, CARRIERS, SELF, RESET } = selectors(mode);
+  const T = {
+    // a light root inside a dark one: the derived tokens come back through @scope (:scope below), the rest here
+    light: pick([...new Set([...Object.keys(NIGHT), ...Object.keys(NAVY), ...contractDerived(LIGHT)])].filter((n) => !TD_LIGHT.includes(n)), LIGHT),
+    dark: [...night, ...pick(contractDerived(LIGHT).filter((n) => !(n in NIGHT)), LIGHT)],
+    navy,
+  };
+  const TD = { light: pick(TD_LIGHT, LIGHT), dark: pick(TD_DARK, NIGHT), navy: pick(TD_NAVY, NAVY) };
+  const scheme = { light: 'color-scheme: light;', dark: 'color-scheme: dark;', navy: '' };
+
+  /** One theme: its roots (on or in the island), the host's root reaching the island (scoped), the carriers inside. */
+  const theme = (name, roots) => {
+    const out = [rule(at(roots), T[name], '', scheme[name])];
+    if (scoped) out.push(`@scope (${roots}) {\n${splitRule(ROOT, ROOT0, T[name], '  ', scheme[name])}\n}`);
+    out.push(`@scope (${roots}) {\n${rule(`${SELF}, ${CARRIERS}`, TD[name], '  ')}\n}`);
+    return out.join('\n');
+  };
+  /* The reset: an element that sets a palette starts from the kit's own contract values for the theme it is in, at no
+     specificity. A palette then states only what it changes and still resolves whole inside another palette, and a
+     contract token the kit derives (the focus ring from the heading, growth from the past-half tone) recomputes from
+     that palette's inputs unless the palette sets it. A palette's own rules always beat it. */
+  // a theme's reset holds only what that theme changes: the light one under it already restates the rest
+  const THEMED = { light: [...CONTRACT].filter((n) => n in NIGHT || n in NAVY), dark: [...CONTRACT].filter((n) => n in NIGHT) };
+  const reset = (name, roots) => `@scope (${roots}) {\n${rule(RESET, pick(THEMED[name], name === 'light' ? LIGHT : NIGHT), '  ')}\n}`;
+
+  return [
+    `/* Derived tokens again on every carrier, so a palette or theme set on any element reaches what derives from it. */`,
+    // scoped: the island's own root too when it carries a palette or theme (its block below holds the root literals)
+    rule(scoped ? `:where(.fello) [data-palette], :where(.fello)[data-palette], :where(.fello) [data-theme], :where(.fello)[data-theme], :where(.fello) .fello` : '[data-palette], [data-theme], .fello', pick(DERIVED, LIGHT)),
+    `/* Every palette element starts from the kit's contract values (light here, each theme's below), at no specificity. */`,
+    rule(RESET, pick([...CONTRACT], LIGHT)),
+    `/* Light: data-theme="light" (and "system" on a light OS) inside a dark element. */`,
+    theme('light', ROOTS.light),
+    reset('light', ROOTS.light),
+    `/* Night: data-theme="dark", and "system" on a dark OS. */`,
+    theme('dark', ROOTS.dark),
+    reset('dark', ROOTS.dark),
+    darkOs([theme('dark', SYSTEM.dark), reset('dark', SYSTEM.dark)].join('\n')),
+    `/* The palettes (tokens/_palettes.css): ${Object.keys(palettes).join(', ')}. */`,
+    ...Object.entries(palettes).map(([id, p]) => paletteCss(id, p, mode)),
+    `/* The navy ground, beside data-theme="dark" (or "system" on a dark OS): over night, and over a palette. */`,
+    theme('navy', ROOTS.navy),
+    darkOs(theme('navy', SYSTEM.navy)),
+    navyOverCss('[data-palette]', mode),
+    '',
+  ].join('\n');
+}
+
+/* The chart fades, tints and empty cell are declared on the root as the literal they resolve to in light (the
+   designer's value), and derive everywhere a palette or theme opens (the carriers): charts draw them as gradient stops
+   (SVG gradients, a ring's conic gradient written in the markup), and Chromium blends a gradient whose stop is a
+   computed colour (color-mix) in Oklab unless the gradient says "in srgb", which SVG cannot, so the default would move
+   a level or four. A palette moves them as it moves everything else. */
+export const ROOT_LITERAL = new Set([
+  '--ws-chart-empty', '--ws-chart-navy-fade', '--ws-chart-salmon-fade', '--ws-chart-purple-fade', '--ws-chart-teal-fade',
+  '--ws-chart-finished-tint', '--ws-chart-past-half-tint', '--ws-chart-under-half-tint',
+]);
+/** The token list as a root block declares it (tokens.css, tokens.root.css, the scoped island). */
+export function rootList() {
+  const light = resolved().light;
+  return tokens.map(([n, v]) => [n, ROOT_LITERAL.has(n) ? light[n] : v]);
+}