@halftone-ds/tokens 0.0.0-stage → 1.1.0

package/lib/theme/apply.mjs

@@ -0,0 +1,100 @@
+/**
+ * Commit a theme into a tokens.json object. Only the paths a theme owns are written; everything else
+ * (status ramps, spacing, type sizes, motion, descriptions) is left exactly as it was. The recipe is
+ * recorded under `$extensions["com.halftonedesignsystem.theme"]`, so the docs picker and `halftone-tokens theme show`
+ * can tell which theme is applied, and whether anyone has hand-edited it since (drift).
+ */
+import { generateTheme } from './generate.mjs';
+import { normalizeRecipe } from './recipe.mjs';
+import { flatten } from './refs.mjs';
+
+export const THEME_EXTENSION = 'com.halftonedesignsystem.theme';
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+
+/** The values a theme owns, as { 'path.to.token': $value }. */
+function ownedValues(theme) {
+  const out = {};
+  for (const [group, ramp] of Object.entries(theme.primitives)) {
+    for (const [step, hex] of Object.entries(ramp)) out[`primitive.color.${group}.${step}`] = hex;
+  }
+  for (const [name, value] of Object.entries(theme.semantic.color)) out[`semantic.color.${name}`] = value;
+  out['semantic.radius.base'] = theme.semantic.radius.base;
+  out['semantic.radius.control'] = theme.semantic.radius.control;
+  out['semantic.border.width'] = theme.semantic.border.width;
+  out['semantic.icon.stroke'] = theme.semantic.icon.stroke;
+  for (const [level, value] of Object.entries(theme.semantic.shadow)) out[`semantic.shadow.${level}`] = value;
+  out['semantic.density.scale'] = theme.semantic.density.scale;
+  for (const [size, value] of Object.entries(theme.semantic.density.control)) out[`semantic.density.control.${size}`] = value;
+  out['primitive.font.family.heading'] = theme.fonts.heading;
+  out['primitive.font.family.body'] = theme.fonts.body;
+  out['primitive.font.family.mono'] = theme.fonts.mono;
+  for (const [key, value] of Object.entries(theme.semantic.type)) out[`semantic.type.${key}`] = value;
+  return out;
+}
+
+const TYPES = { radius: 'number', border: 'number', icon: 'number', density: 'number', type: 'number', shadow: 'shadow', font: 'fontFamily', color: 'color' };
+const DESCRIPTIONS = {
+  'semantic.radius.control': 'Corner radius of mobile buttons and chips: rounded-control. 9999 = pills; otherwise the base radius.',
+  'semantic.border.width': 'Width of `border` (px). border-2 and border-hairline stay explicit.',
+  'semantic.icon.stroke': "Lucide stroke width; an icon's own strokeWidth is relative to 2.",
+  'semantic.shadow.1': 'shadow-xs / shadow-sm / shadow: controls and cards.',
+  'semantic.shadow.2': 'shadow-md: raised cards and popovers.',
+  'semantic.shadow.3': 'shadow-lg / shadow-xl: menus, dialogs, floating buttons.',
+  'semantic.density.scale': "Web: multiplies the spacing scale (Tailwind 4 --spacing). Mobile: see density.control.",
+  'semantic.density.control.sm': 'Mobile: small control height (h-control-sm), px.',
+  'semantic.density.control.md': 'Mobile: control height (h-control): buttons, inputs, selects, px.',
+  'semantic.density.control.lg': 'Mobile: large control height (h-control-lg), px.',
+  'semantic.density.control.x': 'Mobile: control horizontal padding (px-control-x), px.',
+  'primitive.font.family.heading': 'Headings (Text h1–h4, titles). Empty = the platform system font.',
+  'primitive.font.family.body': 'Everything else. Empty = the platform system font.',
+  'primitive.font.family.mono': 'Code and figures (font-mono). Menlo = the platform monospace font.',
+  'semantic.type.size': 'Typeset: body text size (px). Every text size (text-xs…4xl) scales by size / 16.',
+  'semantic.type.leading': "Typeset: line height of running text (× size); the text sizes' line heights scale by leading / 1.75.",
+  'semantic.type.flow': 'Typeset: space between blocks of long-form text (Prose), em.',
+  'semantic.type.measure': 'Typeset: the longest line of long-form text (Prose), characters.',
+};
+
+function typeOf(path) {
+  return TYPES[path.split('.')[1]] ?? 'color';
+}
+
+function setPath(root, path, $value) {
+  let node = root;
+  const keys = path.split('.');
+  for (const key of keys.slice(0, -1)) node = node[key] ??= {};
+  const leaf = keys.at(-1);
+  if (node[leaf] && typeof node[leaf] === 'object' && '$value' in node[leaf]) node[leaf].$value = $value;
+  else node[leaf] = { $type: typeOf(path), ...(DESCRIPTIONS[path] ? { $description: DESCRIPTIONS[path] } : {}), $value };
+}
+
+/** → { tokens, theme }. `tokens` is a new object; the input is not touched. */
+export function applyRecipe(tokens, recipe) {
+  const theme = generateTheme(recipe, tokens);
+  const out = clone(tokens);
+  for (const [path, value] of Object.entries(ownedValues(theme))) {
+    setPath(out, path, value);
+  }
+  const { $extensions = {}, ...rest } = out;
+  const record = { version: theme.recipe.v, code: theme.code, recipe: theme.recipe };
+  if (theme.adjustments.length) record.adjustments = theme.adjustments;
+  return { tokens: { ...rest, $extensions: { ...$extensions, [THEME_EXTENSION]: record } }, theme };
+}
+
+/**
+ * What theme a tokens.json carries:
+ *   { applied: false }                               no theme recorded
+ *   { applied: true, code, recipe, drift: [paths] }  drift = owned paths edited since the theme was applied
+ */
+export function themeStatus(tokens) {
+  const record = tokens.$extensions?.[THEME_EXTENSION];
+  if (!record?.recipe) return { applied: false };
+  const expected = ownedValues(generateTheme(record.recipe, tokens));
+  const actual = Object.fromEntries(flatten(tokens).map((t) => [t.path.join('.'), t.$value]));
+  // A path the file doesn't have yet (a newer halftone-tokens owns more) is not an edit; apply adds it.
+  const drift = Object.entries(expected)
+    .filter(([path, value]) => path in actual && JSON.stringify(actual[path]) !== JSON.stringify(value))
+    .map(([path]) => path);
+  // Normalised: a recipe recorded by an older halftone-tokens gets the axes it didn't have (the typeset).
+  return { applied: true, code: record.code, recipe: normalizeRecipe(record.recipe), drift };
+}

package/lib/theme/codec.mjs

@@ -0,0 +1,122 @@
+/**
+ * Theme codes: a recipe packed into bits and written in Crockford base32 after a prefix. Short enough to
+ * read out, paste into a terminal or a URL.
+ *
+ *   ht1-  12 characters, 60 bits: a theme with the default typeset (every code made before the typeset)
+ *   ht2-  16 characters, 80 bits: any theme
+ *
+ *   bits  field                                   ht1   ht2
+ *          recipe version (RECIPE_VERSION)          4     4
+ *          brand hex                               24    24
+ *          neutral, radius, controls            3+3+1 3+3+1   (option indexes, recipe.mjs)
+ *          heading, body (, mono)                 5+5 6+6+6   (indexes into FONTS, fonts.mjs)
+ *          stroke, depth, density, border     2+2+2+2 2+2+2+2
+ *          size, leading, flow, measure             –  3+3+3+3
+ *          checksum (payload mod 127)               7     7   a typo is caught instead of making another theme
+ *
+ * encodeRecipe writes ht1 whenever it can, so a theme that doesn't touch the typeset keeps the code it
+ * always had (and older halftone-tokens can read it). The preset name is not in the code: a code is the theme,
+ * whichever preset it started from.
+ */
+import { FONTS } from './fonts.mjs';
+import { defaultTypeset, normalizeRecipe, OPTIONS, RECIPE_VERSION } from './recipe.mjs';
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const LAYOUT = [
+  ['neutral', 3],
+  ['radius', 3],
+  ['controls', 1],
+];
+const TAIL = [
+  ['stroke', 2],
+  ['depth', 2],
+  ['density', 2],
+  ['border', 2],
+];
+const TYPESET = [
+  ['size', 3],
+  ['leading', 3],
+  ['flow', 3],
+  ['measure', 3],
+];
+/** Per format: prefix, characters, font width, whether the typeset is in it. */
+const FORMATS = {
+  ht1: { prefix: 'ht1-', chars: 12, font: 5, typeset: false },
+  ht2: { prefix: 'ht2-', chars: 16, font: 6, typeset: true },
+};
+
+const fontIndex = (id) => FONTS.findIndex((f) => f.id === id);
+
+export function encodeRecipe(input) {
+  const r = normalizeRecipe(input);
+  const ht1 = defaultTypeset(r) && fontIndex(r.font.heading) < 32 && fontIndex(r.font.body) < 32;
+  const format = ht1 ? FORMATS.ht1 : FORMATS.ht2;
+  let bits = BigInt(r.v);
+  const push = (value, width) => {
+    if (value < 0 || value >= 2 ** width) throw new Error(`encodeRecipe: ${value} does not fit in ${width} bits`);
+    bits = (bits << BigInt(width)) | BigInt(value);
+  };
+  push(parseInt(r.brand.slice(1), 16), 24);
+  for (const [key, width] of LAYOUT) push(OPTIONS[key].indexOf(r[key]), width);
+  push(fontIndex(r.font.heading), format.font);
+  push(fontIndex(r.font.body), format.font);
+  if (format.typeset) push(fontIndex(r.font.mono), format.font);
+  for (const [key, width] of TAIL) push(OPTIONS[key].indexOf(r[key]), width);
+  if (format.typeset) for (const [key, width] of TYPESET) push(OPTIONS[key].indexOf(r[key]), width);
+  bits = (bits << 7n) | (bits % 127n);
+
+  let out = '';
+  for (let i = 0; i < format.chars; i++) {
+    out = ALPHABET[Number(bits & 31n)] + out;
+    bits >>= 5n;
+  }
+  return format.prefix + out;
+}
+
+/** Code → recipe. Throws on a malformed code, a bad checksum or an unknown version. */
+export function decodeRecipe(code) {
+  const clean = String(code).trim().toUpperCase();
+  const format = /^HT2/.test(clean) ? FORMATS.ht2 : FORMATS.ht1;
+  const raw = clean.replace(/^HT[12]-?/, '').replace(/[IL]/g, '1').replace(/O/g, '0').replace(/-/g, '');
+  if (!/^HT[12]/.test(clean) && /^HT\d/.test(clean)) {
+    throw new Error(`"${code}" is a newer theme code than this halftone-tokens reads. Update @halftone-ds/tokens.`);
+  }
+  if (!new RegExp(`^[0-9A-HJKMNP-TV-Z]{${format.chars}}$`).test(raw)) {
+    throw new Error(`"${code}" is not a theme code (expected ht1- and 12 characters, or ht2- and 16)`);
+  }
+  let bits = 0n;
+  for (const ch of raw) bits = (bits << 5n) | BigInt(ALPHABET.indexOf(ch));
+  const checksum = bits & 127n;
+  bits >>= 7n;
+  if (bits % 127n !== checksum) throw new Error(`"${code}" has a typo (checksum mismatch)`);
+
+  const pull = (width) => {
+    const value = Number(bits & ((1n << BigInt(width)) - 1n));
+    bits >>= BigInt(width);
+    return value;
+  };
+  const opt = (key, width) => {
+    const value = OPTIONS[key][pull(width)];
+    if (value === undefined) throw new Error(`"${code}" has an unknown ${key}`);
+    return value;
+  };
+  const font = (width) => {
+    const f = FONTS[pull(width)];
+    if (!f) throw new Error(`"${code}" has an unknown font`);
+    return f.id;
+  };
+  const fields = (list) => Object.fromEntries([...list].reverse().map(([key, width]) => [key, opt(key, width)]));
+  // Read back to front.
+  const typeset = format.typeset ? fields(TYPESET) : {};
+  const tail = fields(TAIL);
+  const mono = format.typeset ? font(format.font) : undefined;
+  const body = font(format.font);
+  const heading = font(format.font);
+  const head = fields(LAYOUT);
+  const brand = '#' + pull(24).toString(16).padStart(6, '0');
+  const v = Number(bits);
+  if (v !== RECIPE_VERSION) throw new Error(`"${code}" is a version ${v} theme; this halftone-tokens reads version ${RECIPE_VERSION}. Update @halftone-ds/tokens.`);
+  return normalizeRecipe({ v, brand, ...head, font: { heading, body, ...(mono ? { mono } : {}) }, ...tail, ...typeset });
+}
+
+export const isThemeCode = (value) => /^(ht1-?[0-9a-z]{12}|ht2-?[0-9a-z]{16})$/i.test(String(value).trim());

package/lib/theme/fix.mjs

@@ -0,0 +1,99 @@
+/**
+ * Contrast auto-fix. A theme from the picker must never fail the build, so instead of rejecting a brand
+ * colour that doesn't read, the fixer keeps its hue and nudges its lightness the least it can, per mode:
+ *
+ *   1. a label on its fill (`primary-foreground on primary`): flip the label between neutral.0 and
+ *      neutral.950; if neither reads, move the fill away from the better one
+ *   2. a tone as ink or an icon on its tint (`text-primary on muted`): move the tone away from the page
+ *      (darker in light mode, lighter in dark), then re-check its label
+ *   3. body or muted text on a surface: move the text away from the surface
+ *
+ * It checks the STRICT set (tones on muted/accent too). A moved token becomes a literal hex for that
+ * mode, and every move is reported as { token, mode, from, to } so the picker can show it.
+ */
+import { contrast, hexToOklchParts } from '../color.mjs';
+import { contrastPairs } from '../contrast.mjs';
+import { toGamutHex } from './ramp.mjs';
+import { BRAND_LINKED, FOREGROUND_CHOICES } from './semantic.mjs';
+
+const MAX_PASSES = 24;
+const STEP = 0.004;
+
+const failing = (pairs) => pairs.filter((r) => r.ratio < r.threshold);
+
+/** Move `hex` in lightness (dir -1 darker, +1 lighter) until ok(candidate); null if it never is. */
+function nudge(hex, dir, ok) {
+  const [L, C, H] = hexToOklchParts(hex);
+  for (let i = 1; i * STEP <= 1; i++) {
+    const next = Math.min(1, Math.max(0, L + dir * i * STEP));
+    const candidate = toGamutHex([next, C, H]);
+    if (ok(candidate)) return candidate;
+    if (next === 0 || next === 1) break;
+  }
+  return null;
+}
+
+/**
+ * semantic: { name: { light, dark } } of references or hex; lookup: (value) → hex.
+ * Returns { semantic, adjustments } — a new map, the input is not touched.
+ */
+export function fixContrast(semantic, lookup) {
+  const out = Object.fromEntries(Object.entries(semantic).map(([k, v]) => [k, { ...v }]));
+  const adjustments = [];
+
+  for (const mode of ['light', 'dark']) {
+    const original = Object.fromEntries(Object.entries(out).map(([k, v]) => [k, lookup(v[mode])]));
+    const away = mode === 'light' ? -1 : 1; // the direction that moves ink away from the page
+    const hexNow = () => Object.fromEntries(Object.entries(out).map(([k, v]) => [k, lookup(v[mode])]));
+    const set = (name, value) => {
+      out[name][mode] = value;
+    };
+
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+      const hex = hexNow();
+      const [f] = failing(contrastPairs(hex, mode, { strict: true }));
+      if (!f) break;
+
+      if (f.fgName === `${f.bgName}-foreground`) {
+        // 1. A label on its own fill.
+        const [best] = FOREGROUND_CHOICES.map((ref) => ({ ref, ratio: contrast(lookup(ref), hex[f.bgName]) })).sort((a, b) => b.ratio - a.ratio);
+        if (best.ratio >= f.threshold && out[f.fgName][mode] !== best.ref) {
+          set(f.fgName, best.ref);
+          continue;
+        }
+        const label = lookup(best.ref);
+        // A light label (it reads on black) needs a darker fill; a dark label a lighter one.
+        const dir = contrast(label, '#000000') > contrast(label, '#ffffff') ? -1 : 1;
+        const moved = nudge(hex[f.bgName], dir, (c) => contrast(label, c) >= f.threshold);
+        if (!moved) throw new Error(`fixContrast: cannot fix ${f.label} (${mode})`);
+        set(f.fgName, best.ref);
+        moveFill(f.bgName, moved);
+        continue;
+      }
+
+      // 2 and 3: move the ink until every pairing it takes part in as ink passes.
+      const ink = f.fgName;
+      const asInk = (candidate) => failing(contrastPairs({ ...hex, [ink]: candidate }, mode, { strict: true, fg: ink })).length === 0;
+      const moved = nudge(hex[ink], away, asInk);
+      if (!moved) throw new Error(`fixContrast: cannot fix ${f.label} (${mode})`);
+      moveFill(ink, moved);
+    }
+
+    const left = failing(contrastPairs(hexNow(), mode, { strict: true }));
+    if (left.length) throw new Error(`fixContrast: ${left[0].label} still fails in ${mode} after ${MAX_PASSES} passes`);
+
+    for (const [name, before] of Object.entries(original)) {
+      const after = lookup(out[name][mode]);
+      if (after !== before && out[name][mode].startsWith('#')) adjustments.push({ token: name, mode, from: before, to: after });
+    }
+
+    function moveFill(name, hex) {
+      const was = lookup(out[name][mode]);
+      set(name, hex);
+      if (name === 'primary') {
+        for (const linked of BRAND_LINKED) if (lookup(out[linked][mode]) === was) set(linked, hex);
+      }
+    }
+  }
+  return { semantic: out, adjustments };
+}

package/lib/theme/fonts.mjs

@@ -0,0 +1,58 @@
+/**
+ * The curated font list for theme recipes. Every family is on Google Fonts (for the docs preview and
+ * next/font) and has an @expo-google-fonts package (for native), with 400–700 available: the kits' live
+ * preview asks Google Fonts for exactly those weights, and a family without one fails the whole request.
+ *
+ * APPEND-ONLY: a theme code stores a font's index in this list. Never reorder or remove an entry;
+ * retire one by marking it `hidden: true` (old codes still resolve, the picker stops offering it).
+ *
+ *   id          stable id, also the @expo-google-fonts package suffix
+ *   family      the Google Fonts family name
+ *   category    sans | serif | display | mono — for grouping in the picker; mono fonts are the mono role's
+ *               choices (code, figures), and can be a heading or body font too
+ *   system      the platform's own font for its role: nothing to load
+ *   weights     the static weights we load (400–700); a class asking for another snaps to the nearest
+ *   expoPrefix  the export prefix of the @expo-google-fonts package (Inter_600SemiBold → 'Inter')
+ */
+export const FONTS = [
+  { id: 'system', family: 'System', category: 'sans', weights: [400, 500, 600, 700, 800], system: true },
+  { id: 'inter', family: 'Inter', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'Inter' },
+  { id: 'geist', family: 'Geist', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'Geist' },
+  { id: 'dm-sans', family: 'DM Sans', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'DMSans' },
+  { id: 'manrope', family: 'Manrope', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'Manrope' },
+  { id: 'plus-jakarta-sans', family: 'Plus Jakarta Sans', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'PlusJakartaSans' },
+  { id: 'outfit', family: 'Outfit', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'Outfit' },
+  { id: 'space-grotesk', family: 'Space Grotesk', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'SpaceGrotesk' },
+  { id: 'ibm-plex-sans', family: 'IBM Plex Sans', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'IBMPlexSans' },
+  { id: 'nunito', family: 'Nunito', category: 'sans', weights: [400, 500, 600, 700], expoPrefix: 'Nunito' },
+  { id: 'bricolage-grotesque', family: 'Bricolage Grotesque', category: 'display', weights: [400, 500, 600, 700], expoPrefix: 'BricolageGrotesque' },
+  { id: 'fraunces', family: 'Fraunces', category: 'serif', weights: [400, 500, 600, 700], expoPrefix: 'Fraunces' },
+  { id: 'playfair-display', family: 'Playfair Display', category: 'serif', weights: [400, 500, 600, 700], expoPrefix: 'PlayfairDisplay' },
+  { id: 'lora', family: 'Lora', category: 'serif', weights: [400, 500, 600, 700], expoPrefix: 'Lora' },
+  { id: 'source-serif-4', family: 'Source Serif 4', category: 'serif', weights: [400, 500, 600, 700], expoPrefix: 'SourceSerif4' },
+  // Mono (the typeset's mono role). system-mono is the platform's monospace font; Menlo is what tokens.json
+  // has always said for it.
+  { id: 'system-mono', family: 'Menlo', category: 'mono', weights: [400, 500, 600, 700], system: true },
+  { id: 'jetbrains-mono', family: 'JetBrains Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'JetBrainsMono' },
+  { id: 'geist-mono', family: 'Geist Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'GeistMono' },
+  { id: 'ibm-plex-mono', family: 'IBM Plex Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'IBMPlexMono' },
+  { id: 'roboto-mono', family: 'Roboto Mono', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'RobotoMono' },
+  { id: 'fira-code', family: 'Fira Code', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'FiraCode' },
+  { id: 'source-code-pro', family: 'Source Code Pro', category: 'mono', weights: [400, 500, 600, 700], expoPrefix: 'SourceCodePro' },
+];
+
+export const fontById = (id) => FONTS.find((f) => f.id === id);
+
+/** The nearest loaded weight of a font to the one a class asks for. */
+export function nearestWeight(font, weight) {
+  return font.weights.reduce((best, w) => (Math.abs(w - weight) < Math.abs(best - weight) ? w : best), font.weights[0]);
+}
+
+/** Google Fonts CSS for a set of families (docs preview and embeds; the kits bundle their fonts). */
+export function googleFontsHref(ids) {
+  const families = [...new Set(ids)]
+    .map(fontById)
+    .filter((f) => f && !f.system)
+    .map((f) => `family=${f.family.replace(/ /g, '+')}:wght@${f.weights.join(';')}`);
+  return families.length ? `https://fonts.googleapis.com/css2?${families.join('&')}&display=swap` : null;
+}

package/lib/theme/generate.mjs

@@ -0,0 +1,83 @@
+/**
+ * generateTheme — a recipe expanded into a theme. Pure ESM, no Node APIs: the docs site runs it in
+ * the browser for the live picker, the CLI runs it to commit a theme into tokens.json.
+ *
+ *   generateTheme(recipe, base)  base = the app's tokens.json (status ramps, radius steps come from it)
+ *     → { recipe, code, primitives, semantic, resolved, radius, type, adjustments }
+ *
+ * Status colours (success, warning, danger, info) are not themed in v1; they come from `base`.
+ */
+import { fixContrast } from './fix.mjs';
+import { encodeRecipe } from './codec.mjs';
+import { fontById } from './fonts.mjs';
+import { BORDER, DENSITY, DEPTH, FLOW, LEADING, normalizeRecipe, RADIUS, STROKE, typeScale } from './recipe.mjs';
+import { anchorStep, brandRamp, neutralRamp } from './ramp.mjs';
+import { resolvedMap } from './refs.mjs';
+import { semanticColors } from './semantic.mjs';
+
+
+const ramp = (values) => Object.fromEntries(Object.entries(values).map(([step, $value]) => [step, { $type: 'color', $value }]));
+
+/** The theme for a recipe, on top of `base` (a tokens.json object). `fix: false` skips the contrast fixer. */
+export function generateTheme(input, base, { fix = true } = {}) {
+  const recipe = normalizeRecipe(input);
+  const brand = brandRamp(recipe.brand);
+  const neutral = neutralRamp(recipe.neutral, recipe.brand);
+
+  // Primitive lookup: the base primitives with this theme's ramps swapped in.
+  const primitive = { ...base.primitive, color: { ...base.primitive.color, brand: ramp(brand), neutral: ramp(neutral) } };
+  const prim = resolvedMap({ primitive }, 'light');
+  const lookup = (value) => {
+    if (typeof value !== 'string' || !value.startsWith('{')) return value;
+    const hex = prim[value.slice(1, -1)];
+    if (hex === undefined) throw new Error(`generateTheme: ${value} is not in the base tokens`);
+    return hex;
+  };
+
+  let colors = semanticColors(anchorStep(recipe.brand));
+  let adjustments = [];
+  if (fix) ({ semantic: colors, adjustments } = fixContrast(colors, lookup));
+
+  const radiusRef = RADIUS[recipe.radius];
+  const radiusValue = typeof radiusRef === 'string' ? `{primitive.radius.${radiusRef}}` : radiusRef;
+  const resolved = Object.fromEntries(
+    ['light', 'dark'].map((mode) => [mode, Object.fromEntries(Object.entries(colors).map(([name, v]) => [name, lookup(v[mode])]))])
+  );
+
+  const radius = lookup(radiusValue);
+  const controlRadius = recipe.controls === 'pill' ? 9999 : radiusValue;
+  // Heading and body: '' is the platform font. Mono: system-mono is Menlo, what tokens.json always had.
+  const font = (id) => (id === 'system' ? '' : fontById(id).family);
+  const density = DENSITY[recipe.density];
+  const size = Number(recipe.size);
+  const type = {
+    size,
+    leading: LEADING[recipe.leading],
+    flow: FLOW[recipe.flow],
+    measure: Number(recipe.measure),
+  };
+
+  return {
+    recipe,
+    code: encodeRecipe(recipe),
+    primitives: { brand, neutral },
+    fonts: { heading: font(recipe.font.heading), body: font(recipe.font.body), mono: font(recipe.font.mono) },
+    semantic: {
+      color: colors,
+      radius: { base: radiusValue, control: controlRadius },
+      border: { width: BORDER[recipe.border] },
+      icon: { stroke: STROKE[recipe.stroke] },
+      shadow: DEPTH[recipe.depth],
+      density: { scale: density.scale, control: { sm: density.sm, md: density.md, lg: density.lg, x: density.x } },
+      type,
+    },
+    density,
+    type: typeScale(type),
+    resolved,
+    radius,
+    radiusControl: lookup(controlRadius),
+    borderWidth: BORDER[recipe.border],
+    stroke: STROKE[recipe.stroke],
+    adjustments,
+  };
+}

package/lib/theme/index.d.mts

@@ -0,0 +1,102 @@
+/** Types for @halftone-ds/tokens/theme (index.mjs). */
+
+export type Neutral = 'zinc' | 'neutral' | 'slate' | 'stone' | 'gray' | 'brand';
+export type Radius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type Controls = 'pill' | 'match';
+export type Stroke = 'regular' | 'thin' | 'bold';
+export type Depth = 'soft' | 'flat' | 'raised' | 'hard';
+export type Density = 'comfortable' | 'compact' | 'spacious';
+export type Border = 'regular' | 'hairline' | 'heavy';
+export type Size = '16' | '14' | '15' | '18';
+export type Leading = 'normal' | 'tight' | 'relaxed';
+export type Flow = 'normal' | 'tight' | 'loose';
+export type Measure = '70' | '60' | '80' | '90';
+export type Mode = 'light' | 'dark';
+
+export type Recipe = {
+  v: number;
+  brand: string;
+  neutral: Neutral;
+  radius: Radius;
+  controls: Controls;
+  font: { heading: string; body: string; mono: string };
+  stroke: Stroke;
+  depth: Depth;
+  density: Density;
+  border: Border;
+  size: Size;
+  leading: Leading;
+  flow: Flow;
+  measure: Measure;
+  preset?: string;
+};
+export type RecipeInput = Partial<Omit<Recipe, 'font'>> & { font?: Partial<Recipe['font']> };
+
+export type Adjustment = { token: string; mode: Mode; from: string; to: string };
+
+export type Theme = {
+  recipe: Recipe;
+  code: string;
+  primitives: { brand: Record<string, string>; neutral: Record<string, string> };
+  semantic: Record<string, unknown>;
+  /** Semantic colours as hex per mode, kebab-case names (`primary-foreground`). */
+  resolved: Record<Mode, Record<string, string>>;
+  /** Base radius in px. */
+  radius: number;
+  adjustments: Adjustment[];
+  /** Font families by role ('' = system; mono 'Menlo' = the platform monospace). */
+  fonts: { heading: string; body: string; mono: string };
+  /** The typeset: size (px), scale (size / 16), leading, leadingFactor (leading / 1.75), flow (em), measure (ch). */
+  type: TypeScale;
+  radiusControl: number;
+  borderWidth: number;
+  stroke: number;
+  density: { sm: number; md: number; lg: number; x: number; scale: number };
+  [key: string]: unknown;
+};
+
+export type TypeScale = { size: number; scale: number; leading: number; leadingFactor: number; flow: number; measure: number };
+export type Font = { id: string; family: string; category: 'sans' | 'serif' | 'display' | 'mono'; weights: number[]; expoPrefix?: string; hidden?: boolean; system?: boolean };
+export type Preset = { id: string; name: string; description: string; recipe: RecipeInput };
+export type ThemeStatus = { applied: false } | { applied: true; code: string; recipe: Recipe; drift: string[] };
+export type TokensJson = Record<string, unknown> & { primitive: Record<string, unknown>; semantic: Record<string, unknown> };
+
+export const RECIPE_VERSION: number;
+export const DEFAULT_RECIPE: Readonly<Recipe>;
+export const OPTIONS: {
+  neutral: Neutral[];
+  radius: Radius[];
+  controls: Controls[];
+  stroke: Stroke[];
+  depth: Depth[];
+  density: Density[];
+  border: Border[];
+  size: Size[];
+  leading: Leading[];
+  flow: Flow[];
+  measure: Measure[];
+};
+export const TYPESET_KEYS: ['size', 'leading', 'flow', 'measure'];
+export const LEADING: Record<Leading, number>;
+export const FLOW: Record<Flow, number>;
+export const FONTS: Font[];
+export const PRESETS: Preset[];
+export const BRAND_RAMPS: Record<string, Record<string, string>>;
+export const THEME_EXTENSION: string;
+
+export function normalizeRecipe(input?: RecipeInput): Recipe;
+export function sameRecipe(a: RecipeInput, b: RecipeInput): boolean;
+export function generateTheme(recipe: RecipeInput, base: TokensJson, options?: { fix?: boolean }): Theme;
+export function encodeRecipe(recipe: RecipeInput): string;
+export function decodeRecipe(code: string): Recipe;
+export function isThemeCode(value: unknown): boolean;
+export function fontById(id: string): Font | undefined;
+export function googleFontsHref(ids: string[]): string | null;
+export function presetById(id: string): Preset | undefined;
+export function defaultTypeset(recipe: Recipe): boolean;
+export function typeVars(type: TypeScale): Record<string, string>;
+export function themeVars(theme: Theme, format: 'hsl' | 'oklch'): Record<Mode, Record<string, string>>;
+export function themeHex(theme: Theme): Record<Mode, Record<string, string>>;
+export function themeCss(theme: Theme, options?: { format?: 'hsl' | 'oklch'; light?: string; dark?: string }): string;
+export function applyRecipe(tokens: TokensJson, recipe: RecipeInput): { tokens: TokensJson; theme: Theme };
+export function themeStatus(tokens: TokensJson): ThemeStatus;

package/lib/theme/index.mjs

@@ -0,0 +1,14 @@
+/**
+ * @halftone-ds/tokens/theme — theme recipes, the generator, codes, presets and CSS output. Pure ESM
+ * with no Node APIs: the docs site runs it in the browser for the live picker, and the CLI runs it to
+ * commit a theme into tokens.json (`halftone-tokens theme apply`).
+ */
+export { generateTheme } from './generate.mjs';
+export { encodeRecipe, decodeRecipe, isThemeCode } from './codec.mjs';
+export { DEFAULT_RECIPE, defaultTypeset, FLOW, LEADING, OPTIONS, normalizeRecipe, sameRecipe, RECIPE_VERSION, TYPESET_KEYS } from './recipe.mjs';
+export { FONTS, fontById, googleFontsHref } from './fonts.mjs';
+export { PRESETS, presetById } from './presets.mjs';
+export { themeVars, themeCss, themeHex, typeVars } from './vars.mjs';
+export { applyRecipe, themeStatus, THEME_EXTENSION } from './apply.mjs';
+export { BRAND_RAMPS } from './palettes.mjs';
+

package/lib/theme/palettes.mjs

@@ -0,0 +1,37 @@
+/**
+ * Curated colour ramps (Tailwind CSS v3, MIT). A brand seed that equals one of these ramps' 600 step
+ * uses the ramp as-is, so the swatches in the picker give exactly the colours designers know; any
+ * other seed is generated (ramp.mjs). Neutrals are always curated, except the brand-tinted one.
+ *
+ * APPEND-ONLY in spirit: theme codes store the seed hex, not a name, so renaming is safe, but changing
+ * a value changes what an existing code produces.
+ */
+export const STEPS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'];
+
+export const BRAND_RAMPS = {
+  red: { 50: '#fef2f2', 100: '#fee2e2', 200: '#fecaca', 300: '#fca5a5', 400: '#f87171', 500: '#ef4444', 600: '#dc2626', 700: '#b91c1c', 800: '#991b1b', 900: '#7f1d1d', 950: '#450a0a' },
+  orange: { 50: '#fff7ed', 100: '#ffedd5', 200: '#fed7aa', 300: '#fdba74', 400: '#fb923c', 500: '#f97316', 600: '#ea580c', 700: '#c2410c', 800: '#9a3412', 900: '#7c2d12', 950: '#431407' },
+  amber: { 50: '#fffbeb', 100: '#fef3c7', 200: '#fde68a', 300: '#fcd34d', 400: '#fbbf24', 500: '#f59e0b', 600: '#d97706', 700: '#b45309', 800: '#92400e', 900: '#78350f', 950: '#451a03' },
+  yellow: { 50: '#fefce8', 100: '#fef9c3', 200: '#fef08a', 300: '#fde047', 400: '#facc15', 500: '#eab308', 600: '#ca8a04', 700: '#a16207', 800: '#854d0e', 900: '#713f12', 950: '#422006' },
+  lime: { 50: '#f7fee7', 100: '#ecfccb', 200: '#d9f99d', 300: '#bef264', 400: '#a3e635', 500: '#84cc16', 600: '#65a30d', 700: '#4d7c0f', 800: '#3f6212', 900: '#365314', 950: '#1a2e05' },
+  green: { 50: '#f0fdf4', 100: '#dcfce7', 200: '#bbf7d0', 300: '#86efac', 400: '#4ade80', 500: '#22c55e', 600: '#16a34a', 700: '#15803d', 800: '#166534', 900: '#14532d', 950: '#052e16' },
+  emerald: { 50: '#ecfdf5', 100: '#d1fae5', 200: '#a7f3d0', 300: '#6ee7b7', 400: '#34d399', 500: '#10b981', 600: '#059669', 700: '#047857', 800: '#065f46', 900: '#064e3b', 950: '#022c22' },
+  teal: { 50: '#f0fdfa', 100: '#ccfbf1', 200: '#99f6e4', 300: '#5eead4', 400: '#2dd4bf', 500: '#14b8a6', 600: '#0d9488', 700: '#0f766e', 800: '#115e59', 900: '#134e4a', 950: '#042f2e' },
+  cyan: { 50: '#ecfeff', 100: '#cffafe', 200: '#a5f3fc', 300: '#67e8f9', 400: '#22d3ee', 500: '#06b6d4', 600: '#0891b2', 700: '#0e7490', 800: '#155e75', 900: '#164e63', 950: '#083344' },
+  sky: { 50: '#f0f9ff', 100: '#e0f2fe', 200: '#bae6fd', 300: '#7dd3fc', 400: '#38bdf8', 500: '#0ea5e9', 600: '#0284c7', 700: '#0369a1', 800: '#075985', 900: '#0c4a6e', 950: '#082f49' },
+  blue: { 50: '#eff6ff', 100: '#dbeafe', 200: '#bfdbfe', 300: '#93c5fd', 400: '#60a5fa', 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8', 800: '#1e40af', 900: '#1e3a8a', 950: '#172554' },
+  indigo: { 50: '#eef2ff', 100: '#e0e7ff', 200: '#c7d2fe', 300: '#a5b4fc', 400: '#818cf8', 500: '#6366f1', 600: '#4f46e5', 700: '#4338ca', 800: '#3730a3', 900: '#312e81', 950: '#1e1b4b' },
+  violet: { 50: '#f5f3ff', 100: '#ede9fe', 200: '#ddd6fe', 300: '#c4b5fd', 400: '#a78bfa', 500: '#8b5cf6', 600: '#7c3aed', 700: '#6d28d9', 800: '#5b21b6', 900: '#4c1d95', 950: '#2e1065' },
+  purple: { 50: '#faf5ff', 100: '#f3e8ff', 200: '#e9d5ff', 300: '#d8b4fe', 400: '#c084fc', 500: '#a855f7', 600: '#9333ea', 700: '#7e22ce', 800: '#6b21a8', 900: '#581c87', 950: '#3b0764' },
+  fuchsia: { 50: '#fdf4ff', 100: '#fae8ff', 200: '#f5d0fe', 300: '#f0abfc', 400: '#e879f9', 500: '#d946ef', 600: '#c026d3', 700: '#a21caf', 800: '#86198f', 900: '#701a75', 950: '#4a044e' },
+  pink: { 50: '#fdf2f8', 100: '#fce7f3', 200: '#fbcfe8', 300: '#f9a8d4', 400: '#f472b6', 500: '#ec4899', 600: '#db2777', 700: '#be185d', 800: '#9d174d', 900: '#831843', 950: '#500724' },
+  rose: { 50: '#fff1f2', 100: '#ffe4e6', 200: '#fecdd3', 300: '#fda4af', 400: '#fb7185', 500: '#f43f5e', 600: '#e11d48', 700: '#be123c', 800: '#9f1239', 900: '#881337', 950: '#4c0519' },
+};
+
+export const NEUTRAL_RAMPS = {
+  zinc: { 50: '#fafafa', 100: '#f4f4f5', 200: '#e4e4e7', 300: '#d4d4d8', 400: '#a1a1aa', 500: '#71717a', 600: '#52525b', 700: '#3f3f46', 800: '#27272a', 900: '#18181b', 950: '#09090b' },
+  neutral: { 50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 300: '#d4d4d4', 400: '#a3a3a3', 500: '#737373', 600: '#525252', 700: '#404040', 800: '#262626', 900: '#171717', 950: '#0a0a0a' },
+  slate: { 50: '#f8fafc', 100: '#f1f5f9', 200: '#e2e8f0', 300: '#cbd5e1', 400: '#94a3b8', 500: '#64748b', 600: '#475569', 700: '#334155', 800: '#1e293b', 900: '#0f172a', 950: '#020617' },
+  gray: { 50: '#f9fafb', 100: '#f3f4f6', 200: '#e5e7eb', 300: '#d1d5db', 400: '#9ca3af', 500: '#6b7280', 600: '#4b5563', 700: '#374151', 800: '#1f2937', 900: '#111827', 950: '#030712' },
+  stone: { 50: '#fafaf9', 100: '#f5f5f4', 200: '#e7e5e4', 300: '#d6d3d1', 400: '#a8a29e', 500: '#78716c', 600: '#57534e', 700: '#44403c', 800: '#292524', 900: '#1c1917', 950: '#0c0a09' },
+};