@halftone-ds/tokens 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hendri van Niekerk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @halftone-ds/tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The token build behind [Halftone](https://github.com/itsHendri/halftone). One `tokens.json` in the
+[W3C design-token format](https://www.designtokens.org/tr/2025.10/format/) becomes everything an app reads,
+and the build refuses any palette that falls below WCAG AA.
+
+```bash
+npm install -D @halftone-ds/tokens
+npx halftone-tokens build      # write every output in tokens/tokens.config.json
+npx halftone-tokens check      # write nothing; exit 1 if an output is stale (CI)
+npx halftone-tokens figma      # mirror the tokens into Figma Variables
+```
+
+## Inputs
+
+- `tokens/tokens.json`: `primitive` ramps and scales, and `semantic.color.<name>` with a `{ light, dark }`
+  value per colour, using the shadcn names (`background`, `primary`, `primary-foreground`, `muted`, …) plus
+  `success`, `warning` and `info`. `semantic.radius.base` sets `--radius`.
+- `tokens/tokens.config.json`: which targets to write, and where (paths relative to the app root):
+
+```json
+{
+  "source": "tokens/tokens.json",
+  "scan": ["app", "components"],
+  "targets": {
+    "nativewind3": { "css": "global.css", "tailwind": "tokens/generated/tailwind.theme.js" },
+    "ts-theme": { "out": "lib/theme.ts", "navTheme": "expo-router/react-navigation" },
+    "shadcn-web": { "out": "app/tokens.css" },
+    "design-md": { "out": "DESIGN.md", "name": "My Kit" }
+  }
+}
+```
+
+`scan` (optional) lists source folders for the text-on-tint check below.
+
+## Targets
+
+| Target | Writes |
+|---|---|
+| `nativewind3` | NativeWind 4 / Tailwind 3 CSS variables (HSL, `:root` + `.dark:root`) and the Tailwind colour + radius map |
+| `shadcn-web` | Tailwind 4 / shadcn v4 CSS: oklch variables in `:root` + `.dark`, `@theme inline`, base layer |
+| `ts-theme` | `THEME` (hex per scheme), `TOKENS` (space, radius, type, motion) and an optional React Navigation theme |
+| `registry-theme` | the theme as shadcn registry `cssVars`, native and web |
+| `design-md` | a [DESIGN.md](https://github.com/google-labs-code/design.md) (spec alpha) |
+| `llms` | a tokens section for `llms.txt` |
+| `figma` | the input `halftone-tokens figma` pushes to Figma Variables |
+
+## Guarantees
+
+- **Contrast gate.** Every `X` / `X-foreground` pairing, body and muted text on every surface, each status
+  colour used as text, and each status icon on its own tint must clear WCAG AA in both themes, or the build
+  fails, names the pairing, prints the ratio, and writes nothing.
+- **Text on tints.** A status colour as text on its own tint (`text-success` on `bg-success/15`) loses
+  contrast fast: 4.09:1 with a typical green. The build works out, per colour, the strongest tint that
+  still clears AA in both themes, and writes it into `DESIGN.md` and the `llms` section
+  (`primary up to /5, …, destructive never`). With `scan` set, `build` and `check` also read every class
+  string in those folders and fail on a tone's text over a tint stronger than that, naming the file and line.
+  An element that holds only an icon (3:1) is exempt with a `halftone-tokens-ignore tint-text` comment. A class
+  string has to contain both classes, so React Native's `View` > `Text` nesting is out of its reach;
+  `DESIGN.md` states the rule for that case.
+- **No drift between platforms.** Every oklch value must render back to the same 8-bit hex as the source,
+  so the web theme and the native theme are the same colours.
+- **Radius scale.** `rounded-*` classes are offsets from `radius.lg`, so with the default base each class
+  equals its primitive and moving `semantic.radius.base` shifts the whole scale.
+
+MIT licence.

package/cli.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * halftone-tokens — turns tokens/tokens.json into everything an app reads.
+ *
+ *   halftone-tokens build    resolve, run the contrast gate, write every target in tokens.config.json
+ *   halftone-tokens check    same, but write nothing; exit 1 if any generated file is stale (CI)
+ *   halftone-tokens figma    mirror the tokens into Figma Variables (see push-figma.mjs)
+ *   halftone-tokens theme    apply, show or list themes (see lib/theme-cli.mjs)
+ *   halftone-tokens --version
+ *
+ *   --root <dir>        app root (default: cwd); every path in the config is relative to it
+ *   --config <file>     default: tokens/tokens.config.json
+ *
+ * tokens.config.json: { "source": "tokens/tokens.json", "targets": { "<target>": { …options } } }
+ * Targets live in ./targets/<name>.mjs and return [{ path, contents }]. All outputs are GENERATED —
+ * never hand-edit them.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { checkContrast, AA, describeTintLimits, textOnTintLimits } from './lib/contrast.mjs';
+import { scanTintText } from './lib/scan.mjs';
+import { loadTokens } from './lib/resolve.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Flags that take a value; every other --flag is a boolean. */
+const VALUE_FLAGS = new Set(['root', 'config']);
+
+function parseArgs(argv) {
+  const [command = 'build', ...rest] = argv;
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (!rest[i].startsWith('--')) positional.push(rest[i]);
+    else if (VALUE_FLAGS.has(rest[i].slice(2))) flags[rest[i].slice(2)] = rest[++i];
+    else flags[rest[i].slice(2)] = true;
+  }
+  return { command, flags, positional };
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const { command, flags, positional } = parseArgs(argv);
+  if (command === '--version' || command === '-v') {
+    console.log(JSON.parse(readFileSync(join(here, 'package.json'), 'utf8')).version);
+    return;
+  }
+  const root = resolve(flags.root ?? process.cwd());
+
+  if (command === 'figma') {
+    process.env.KIT_TOKENS_ROOT = root;
+    await import(pathToFileURL(join(here, 'push-figma.mjs')).href);
+    return;
+  }
+  if (command !== 'build' && command !== 'check' && command !== 'theme') {
+    console.error(`halftone-tokens: unknown command "${command}". Use build, check, theme or figma.`);
+    process.exit(2);
+  }
+
+  const configPath = join(root, flags.config ?? 'tokens/tokens.config.json');
+  if (!existsSync(configPath)) {
+    console.error(`halftone-tokens: no config at ${configPath}`);
+    process.exit(2);
+  }
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  const source = config.source ?? 'tokens/tokens.json';
+
+  if (command === 'theme') {
+    const { themeCommand } = await import('./lib/theme-cli.mjs');
+    const rebuild = ['build', '--root', root, ...(flags.config ? ['--config', flags.config] : [])];
+    return themeCommand({ positional, flags, root, sourcePath: join(root, source), config, build: () => run(rebuild) });
+  }
+  const ctx = await loadTokens(join(root, source));
+  ctx.root = root;
+  ctx.header = `GENERATED by \`npm run tokens:build\` from ${source} — do not edit by hand.`;
+
+  const failures = checkContrast(ctx.colors, { strict: true });
+  if (failures.length) {
+    console.error(
+      `\ntokens:build FAILED — ${failures.length} colour pairing(s) below WCAG AA (${AA}:1):\n\n${failures.join('\n')}\n\n` +
+        'Darken the fill, or flip its -foreground between neutral.0 and neutral.950.\n' +
+        'A brightened accent (usually the dark theme) needs dark text, not white.\n' +
+        'Or let the theme generator fix it: `halftone-tokens theme apply <code|preset>` keeps the hue and adjusts the lightness.\n'
+    );
+    process.exit(1);
+  }
+
+  // The palette passes; now the source: a tone's text on its own tint, beyond what this palette allows.
+  if (config.scan?.length) {
+    const limits = textOnTintLimits(ctx.colors);
+    const problems = scanTintText(root, config.scan, limits);
+    if (problems.length) {
+      console.error(
+        `\nhalftone-tokens: ${problems.length} class string(s) put a tone's text on its own tint below WCAG AA (${AA}:1):\n\n${problems.join('\n')}\n\n` +
+          `This palette allows: ${describeTintLimits(limits)}.\n` +
+          'Use text-foreground on the tint (let the tint, an icon or a dot carry the colour), or a lighter tint.\n' +
+          'An element that holds only an icon may keep its tone: add a `halftone-tokens-ignore tint-text` comment.\n'
+      );
+      process.exit(1);
+    }
+  }
+
+  const files = [];
+  for (const [name, options] of Object.entries(config.targets ?? {})) {
+    const { default: target } = await import(pathToFileURL(join(here, 'targets', `${name}.mjs`)).href);
+    files.push(...(await target(ctx, options ?? {})));
+  }
+
+  if (command === 'check') {
+    const stale = files.filter((f) => {
+      const path = join(root, f.path);
+      return !existsSync(path) || readFileSync(path, 'utf8') !== f.contents;
+    });
+    if (stale.length) {
+      console.error(`halftone-tokens check: ${stale.length} generated file(s) out of date — run \`npm run tokens:build\`:\n${stale.map((f) => `  ${f.path}`).join('\n')}`);
+      process.exit(1);
+    }
+    console.log(`halftone-tokens check: ${files.length} files up to date · contrast AA ✓`);
+    return;
+  }
+
+  for (const f of files) {
+    const path = join(root, f.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, f.contents);
+  }
+  console.log(`tokens:build → ${files.map((f) => f.path).join(', ')} · contrast AA ✓`);
+}
+
+// npm runs bins through a symlink in node_modules/.bin, so compare real paths.
+const isMain = () => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+if (process.argv[1] && isMain()) await run();

package/lib/color.mjs

@@ -0,0 +1,114 @@
+/**
+ * Colour maths for the token build. Hex in, every format the targets need out:
+ *   hexToHslTriplet  NativeWind 4 / shadcn v3 CSS variables (`221.2 83.2% 53.3%`)
+ *   hexToOklch       Tailwind 4 / shadcn web CSS variables (`oklch(0.546 0.2152 262.88)`)
+ *   contrast         WCAG 2.1 ratio, for the gate in contrast.mjs
+ */
+
+function parseHex(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(String(hex).trim());
+  if (!m) throw new Error(`Expected a 6-digit hex colour, got "${hex}"`);
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+const toHex = (rgb) => '#' + rgb.map((c) => c.toString(16).padStart(2, '0')).join('');
+
+export function hexToHslTriplet(hex) {
+  const [r, g, b] = parseHex(hex).map((c) => c / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    else if (max === g) h = ((b - r) / d + 2) / 6;
+    else h = ((r - g) / d + 4) / 6;
+  }
+  const round = (x) => Math.round(x * 10) / 10;
+  return `${round(h * 360)} ${round(s * 100)}% ${round(l * 100)}%`;
+}
+
+// ---------- OKLCH (Björn Ottosson's OKLab, sRGB D65) -----------------------------
+
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const fromLinear = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+/** Hex → [L 0–1, C, H degrees], unrounded. */
+export function hexToOklchParts(hex) {
+  const [r, g, b] = parseHex(hex).map((c) => toLinear(c / 255));
+  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);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const C = Math.hypot(A, B);
+  const H = C < 1e-4 ? 0 : ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;
+  return [L, C < 1e-4 ? 0 : C, H];
+}
+
+function oklchToLinearRgb([L, C, H]) {
+  const hr = (H * Math.PI) / 180;
+  const A = C * Math.cos(hr);
+  const B = C * Math.sin(hr);
+  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;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+/** [L, C, H] → 8-bit sRGB hex (clamped). */
+export function oklchPartsToHex(parts) {
+  return toHex(oklchToLinearRgb(parts).map((c) => Math.round(Math.min(1, Math.max(0, fromLinear(c))) * 255)));
+}
+
+/** Whether [L, C, H] lies inside sRGB (no channel clipped). */
+export function inGamut(parts, epsilon = 1e-4) {
+  return oklchToLinearRgb(parts).every((c) => c >= -epsilon && c <= 1 + epsilon);
+}
+
+const fixed = (x, d) => Number(x.toFixed(d));
+
+/**
+ * Hex → `oklch(L C H)` rounded for CSS: 4 decimals for L and C, 2 for H, more only when a saturated
+ * colour needs it to come back as the same 8-bit value. Throws if no precision does, so the web theme
+ * can never drift from the native one.
+ */
+export function hexToOklch(hex) {
+  const [L, C, H] = hexToOklchParts(hex);
+  const target = toHex(parseHex(hex));
+  for (const d of [4, 5, 6]) {
+    const parts = [fixed(L, d), fixed(C, d), fixed(H, d - 2)];
+    if (oklchPartsToHex(parts) === target) return `oklch(${parts.join(' ')})`;
+  }
+  throw new Error(`oklch round-trip drifted for ${hex}`);
+}
+
+// ---------- WCAG ----------------------------------------------------------------
+
+export function relativeLuminance(hex) {
+  const [r, g, b] = parseHex(hex).map((c) => {
+    const v = c / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrast(a, b) {
+  const [hi, lo] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Composite `hex` at `alpha` over `base`, the way a /NN tint renders. */
+export function blend(hex, base, alpha) {
+  const [f, b] = [parseHex(hex), parseHex(base)];
+  return toHex(f.map((c, i) => Math.round(alpha * c + (1 - alpha) * b[i])));
+}

package/lib/contrast.mjs

@@ -0,0 +1,105 @@
+/**
+ * Contrast gate. Re-branding tokens.json is the documented workflow, and a pleasant-looking brand
+ * colour will happily fail WCAG without anyone noticing. Every pairing the kit actually renders is
+ * checked here, and a failure stops the build.
+ */
+import { blend, contrast } from './color.mjs';
+
+export const AA = 4.5; // WCAG 2.1 AA, normal text. Kit labels are 16px — not "large text".
+export const AA_NON_TEXT = 3; // WCAG 1.4.11, icons and other meaningful non-text.
+
+/** The alpha values the kit actually tints with (bg-<tone>/10 etc). */
+const TINTS = [0.1, 0.15, 0.2];
+/** Tones that get used as ink — text-<tone> and coloured icons — not just as fills. */
+export const TONES = ['primary', 'success', 'warning', 'info', 'destructive'];
+
+/**
+ * Every way the kit puts one token against another:
+ *   1. a fill and its own -foreground label
+ *   2. body and muted text on each surface
+ *   3. a tone used as INK — text-<tone> and coloured icons — on the page and on a card
+ *   4. a tone's icon sitting on that same tone's tint, as Alert and IconCircle do
+ *
+ * 3 and 4 are the ones that matter most for a re-brand: a colour can be a perfectly good
+ * fill and still be unreadable as text, which is exactly how an amber warning gets in.
+ *
+ * `hex` is { name: '#rrggbb' } for one mode. `strict` adds tones as ink on the `muted` and `accent`
+ * surfaces too (a link in a muted panel). The build and the theme generator both check strict.
+ */
+export function contrastPairs(hex, mode, { strict = false, fg: only } = {}) {
+  const out = [];
+  // `fg`: only the pairings that token takes part in as the foreground (the theme fixer's inner loop).
+  const add = (label, fgName, bgName, fg, bg, threshold) => {
+    if (!only || fgName === only) out.push({ mode, label, fgName, bgName, fg, bg, threshold, ratio: contrast(fg, bg) });
+  };
+
+  for (const name of ['primary', 'secondary', 'destructive', 'success', 'warning', 'info', 'accent', 'card', 'popover', 'muted', 'sidebar', 'sidebar-primary', 'sidebar-accent']) {
+    const fg = `${name}-foreground`;
+    if (hex[name] && hex[fg]) add(`${fg} on ${name}`, fg, name, hex[fg], hex[name], AA);
+  }
+  for (const surface of ['background', 'card', 'muted']) {
+    if (hex['muted-foreground'] && hex[surface]) add(`muted-foreground on ${surface}`, 'muted-foreground', surface, hex['muted-foreground'], hex[surface], AA);
+    if (hex.foreground && hex[surface]) add(`foreground on ${surface}`, 'foreground', surface, hex.foreground, hex[surface], AA);
+  }
+
+  // A tone used as ink rather than as a fill.
+  for (const tone of TONES) {
+    if (!hex[tone]) continue;
+    for (const surface of strict ? ['background', 'card', 'muted', 'accent'] : ['background', 'card']) {
+      if (hex[surface]) add(`text-${tone} on ${surface}`, tone, surface, hex[tone], hex[surface], AA);
+    }
+  }
+
+  // A tone's icon on that tone's own tint — Alert, IconCircle, SwipeToConfirm.
+  for (const tone of TONES) {
+    if (!hex[tone] || !hex.background) continue;
+    for (const alpha of TINTS) {
+      add(`${tone} icon on ${tone}/${alpha * 100}`, tone, `${tone}/${alpha * 100}`, hex[tone], blend(hex[tone], hex.background, alpha), AA_NON_TEXT);
+    }
+  }
+  return out;
+}
+
+/** The failing pairings as report lines. */
+export function contrastFailures(hex, mode, options) {
+  return contrastPairs(hex, mode, options)
+    .filter((r) => r.ratio < r.threshold)
+    .map((r) => `  ${mode.padEnd(5)} ${r.label.padEnd(36)} ${r.ratio.toFixed(2)} / ${r.threshold}  (${r.fg} on ${r.bg})`);
+}
+
+/** Tint strengths a class can ask for (`bg-<tone>/5` … `/20`), for the text-on-tint limits below. */
+export const TEXT_TINTS = [0.05, 0.1, 0.15, 0.2];
+
+/**
+ * How strong a tint of each tone can be with that same tone's TEXT on it (`text-success` on
+ * `bg-success/15`) and still clear AA in both themes: `{ primary: 0.05, destructive: 0, … }`, where 0
+ * means never. A different pairing from 3 above (the tone on the page) and 4 (an icon, 3:1): a colour
+ * that reads fine on white loses contrast fast on its own tint. Not a gate on the palette, because the
+ * kit can always put `text-foreground` on a tint; `halftone-tokens check` holds the source to these limits.
+ */
+export function textOnTintLimits(colors) {
+  const modes = ['light', 'dark'].map((mode) => Object.fromEntries(colors.map((c) => [c.name, c[mode]])));
+  const limits = {};
+  for (const tone of TONES) {
+    let max = 0;
+    for (const alpha of TEXT_TINTS) {
+      const ok = modes.every((hex) => hex[tone] && hex.background && contrast(hex[tone], blend(hex[tone], hex.background, alpha)) >= AA);
+      if (!ok) break;
+      max = alpha;
+    }
+    limits[tone] = max;
+  }
+  return limits;
+}
+
+/** `{ primary: 0.05, destructive: 0 }` → "primary up to /5, destructive never". */
+export const describeTintLimits = (limits) =>
+  Object.entries(limits)
+    .map(([tone, max]) => `${tone} ${max ? `up to /${Math.round(max * 100)}` : 'never'}`)
+    .join(', ');
+
+/** Run the gate over both modes of the resolved colours; returns the failure lines. */
+export function checkContrast(colors, options) {
+  const of = (mode) => Object.fromEntries(colors.map((c) => [c.name, c[mode]]));
+  return [...contrastFailures(of('light'), 'light', options), ...contrastFailures(of('dark'), 'dark', options)];
+}

package/lib/resolve.mjs

@@ -0,0 +1,108 @@
+/**
+ * Load tokens.json and resolve it once per mode. Style Dictionary resolves {references}; this file
+ * handles the light/dark split (a semantic colour's $value is { light, dark }) and hands every
+ * target the same context object.
+ */
+import StyleDictionary from 'style-dictionary';
+import { readFileSync } from 'node:fs';
+import { DENSITY, DEPTH, shadowCss, TYPE, typeScale } from './theme/recipe.mjs';
+
+export const MODES = ['light', 'dark'];
+
+function isModed(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) && MODES.every((m) => m in value);
+}
+
+/** Return a copy of the token tree with every { light, dark } value collapsed to one mode. */
+function forMode(node, mode) {
+  if (Array.isArray(node) || node === null || typeof node !== 'object') return node;
+  if ('$value' in node) return { ...node, $value: isModed(node.$value) ? node.$value[mode] : node.$value };
+  return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, forMode(v, mode)]));
+}
+
+async function resolveMode(source, mode) {
+  const sd = new StyleDictionary({
+    tokens: forMode(source, mode),
+    usesDtcg: true,
+    log: { verbosity: 'silent' },
+    platforms: { kit: { transforms: [] } },
+  });
+  await sd.hasInitialized;
+  const { allTokens } = await sd.getPlatformTokens('kit');
+  return allTokens;
+}
+
+export const camel = (s) => s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+export const isColor = (t) => t.$type === 'color';
+
+/** CSS variable name for a semantic token: semantic.color.card-foreground → card-foreground, semantic.radius.base → radius */
+export function cssName(token) {
+  const parts = token.path.slice(1).filter((p) => p !== 'color');
+  if (parts.at(-1) === 'base') parts.pop();
+  return parts.join('-');
+}
+
+/**
+ * Tailwind radius classes as multiples of primitive.radius.lg. With the default base every class equals
+ * its primitive (rounded-xl = radius.xl); moving semantic.radius.base scales the whole set, so a base
+ * of 0 makes every rounded-* square.
+ */
+function radiusScales(prim) {
+  const steps = prim.filter((t) => t.path[1] === 'radius' && t.path.length === 3 && t.path[2] !== 'full');
+  const anchor = steps.find((t) => t.path[2] === 'lg').$value;
+  return steps.map((t) => ({ name: t.path[2], scale: Number((t.$value / anchor).toFixed(4)) }));
+}
+
+export function radiusCalc(scale) {
+  return scale === 1 ? 'var(--radius)' : `calc(var(--radius) * ${scale})`;
+}
+
+/**
+ * Everything a target needs:
+ *   semLight / semDark   semantic tokens per mode (colours + radius), in tokens.json order
+ *   prim                 primitive tokens (mode-independent)
+ *   colors               [{ name, light, dark }] semantic colours as hex
+ *   radius               { base: px, steps: [{ name, scale }] }
+ *   shape                { control: px, borderWidth: px, stroke, shadows: { light: { 1: css }, dark },
+ *                          density: { scale, sm, md, lg, x } }
+ *                        (a token file from before themes gets the kit's defaults)
+ *   type                 { size, scale, leading, leadingFactor, flow, measure } (semantic.type; defaults
+ *                          for a token file from before the typeset)
+ */
+export async function loadTokens(sourcePath) {
+  const source = JSON.parse(readFileSync(sourcePath, 'utf8'));
+  const [light, dark] = await Promise.all(MODES.map((m) => resolveMode(source, m)));
+  const semLight = light.filter((t) => t.path[0] === 'semantic');
+  const semDark = dark.filter((t) => t.path[0] === 'semantic');
+  const prim = light.filter((t) => t.path[0] === 'primitive');
+  const darkHex = Object.fromEntries(semDark.filter(isColor).map((t) => [cssName(t), t.$value.toLowerCase()]));
+  const colors = semLight
+    .filter(isColor)
+    .map((t) => ({ name: cssName(t), light: t.$value.toLowerCase(), dark: darkHex[cssName(t)] }));
+  const radius = {
+    base: semLight.find((t) => cssName(t) === 'radius').$value,
+    steps: radiusScales(prim),
+  };
+  const find = (list, name) => list.find((t) => cssName(t) === name)?.$value;
+  const shadows = (list, mode) =>
+    Object.fromEntries(['1', '2', '3'].map((level) => [level, shadowCss(find(list, `shadow-${level}`) ?? DEPTH.soft[level][mode])]));
+  const shape = {
+    control: find(semLight, 'radius-control') ?? 9999,
+    borderWidth: find(semLight, 'border-width') ?? 1,
+    stroke: find(semLight, 'icon-stroke') ?? 2,
+    shadows: { light: shadows(semLight, 'light'), dark: shadows(semDark, 'dark') },
+    density: {
+      scale: find(semLight, 'density-scale') ?? DENSITY.comfortable.scale,
+      ...Object.fromEntries(['sm', 'md', 'lg', 'x'].map((s) => [s, find(semLight, `density-control-${s}`) ?? DENSITY.comfortable[s]])),
+    },
+  };
+  const type = typeScale(Object.fromEntries(Object.entries(TYPE).map(([key, value]) => [key, find(semLight, `type-${key}`) ?? value])));
+  return { source, semLight, semDark, prim, colors, radius, shape, type };
+}
+
+/** Primitive tokens under a path prefix, e.g. group(prim, ['font', 'size']) → [{ key: 'xs', value: 12 }, …]. */
+export function group(prim, prefix) {
+  return prim
+    .filter((t) => t.path.slice(1, 1 + prefix.length).join('.') === prefix.join('.'))
+    .map((t) => ({ key: t.path.slice(1 + prefix.length).join('-'), value: t.$value, type: t.$type }));
+}

package/lib/scan.mjs

@@ -0,0 +1,66 @@
+/**
+ * Source scan: a tone's text on that tone's own tint, beyond what the palette allows.
+ *
+ * The contrast gate proves the palette's pairings; it cannot see how components combine classes.
+ * `bg-success/15 text-success` looks deliberate and fails AA (4.09:1 with the default palette), so this
+ * reads every class string in the configured folders and flags that combination wherever the tint is
+ * stronger than `textOnTintLimits` allows. Only unprefixed classes count (`hover:bg-…` is another state).
+ *
+ * An element that holds only an icon may keep its tone (icons need 3:1, which the gate checks): put
+ * `halftone-tokens-ignore tint-text` in a comment on that line or the line above.
+ *
+ * Limits: a class string has to contain both classes. Text inside a tinted parent (React Native's
+ * View > Text) is not seen; DESIGN.md states the rule for those.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const TONES = ['primary', 'success', 'warning', 'info', 'destructive'];
+const EXTENSIONS = /\.(m?[jt]sx?)$/;
+const SKIP = new Set(['node_modules', '.next', '.expo', 'dist', 'out', 'generated', 'ios', 'android']);
+const PRAGMA = 'halftone-tokens-ignore tint-text';
+
+function files(dir) {
+  let out = [];
+  for (const name of readdirSync(dir)) {
+    if (SKIP.has(name) || name.startsWith('.')) continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) out = out.concat(files(full));
+    else if (EXTENSIONS.test(name)) out.push(full);
+  }
+  return out;
+}
+
+/** Returns one line per offending class string: `components/x.tsx:12  text-success on bg-success/15 (allowed: up to /5)`. */
+export function scanTintText(root, paths, limits) {
+  const problems = [];
+  for (const path of paths) {
+    let list;
+    try {
+      list = files(join(root, path));
+    } catch {
+      continue; // a configured folder that does not exist (yet) is not an error
+    }
+    for (const file of list) {
+      const source = readFileSync(file, 'utf8');
+      const lines = source.split('\n');
+      for (const m of source.matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.)*)\1/g)) {
+        const classes = m[2].split(/\s+/).filter((c) => c && !c.includes(':'));
+        const texts = new Set(classes.map((c) => /^text-([a-z]+)$/.exec(c)?.[1]).filter((t) => TONES.includes(t)));
+        if (!texts.size) continue;
+        for (const c of classes) {
+          const tint = /^bg-([a-z]+)\/(\d+)$/.exec(c);
+          if (!tint || !texts.has(tint[1])) continue;
+          const [, tone, pct] = tint;
+          const alpha = Number(pct) / 100;
+          if (alpha <= limits[tone]) continue;
+          const lineNo = source.slice(0, m.index).split('\n').length;
+          if (`${lines[lineNo - 1]}\n${lines[lineNo - 2] ?? ''}`.includes(PRAGMA)) continue;
+          const allowed = limits[tone] ? `up to /${Math.round(limits[tone] * 100)}` : 'never';
+          problems.push(`  ${relative(root, file)}:${lineNo}  text-${tone} on bg-${tone}/${pct} (allowed: ${allowed})`);
+        }
+      }
+    }
+  }
+  return problems;
+}