@halftone-ds/tokens 0.0.0-stage → 1.0.0

package/lib/theme/presets.mjs

@@ -0,0 +1,56 @@
+/**
+ * Starting points by personality. Each is a full recipe, typeset included; the picker starts from one and tweaks.
+ * Drafts — review them in the docs studio (/themes) and adjust here. Order is the gallery order.
+ */
+export const PRESETS = [
+  {
+    id: 'default',
+    name: 'Default',
+    description: 'The kit as it ships: system type, blue, soft cards.',
+    recipe: { brand: '#2563eb', neutral: 'zinc', radius: 'lg', controls: 'pill', font: { heading: 'system', body: 'system', mono: 'system-mono' }, stroke: 'regular', depth: 'soft', density: 'comfortable', border: 'regular', size: '16', leading: 'normal', flow: 'normal', measure: '70' },
+  },
+  {
+    id: 'editorial',
+    name: 'Editorial',
+    description: 'Serif headlines, rust ink, hairlines and almost no rounding.',
+    recipe: { brand: '#9a3412', neutral: 'stone', radius: 'sm', controls: 'match', font: { heading: 'fraunces', body: 'inter', mono: 'ibm-plex-mono' }, stroke: 'thin', depth: 'flat', density: 'comfortable', border: 'hairline', size: '18', leading: 'relaxed', flow: 'normal', measure: '70' },
+  },
+  {
+    id: 'soft',
+    name: 'Soft',
+    description: 'Lavender, generous radius, brand-tinted greys and room to breathe.',
+    recipe: { brand: '#8b5cf6', neutral: 'brand', radius: '2xl', controls: 'pill', font: { heading: 'plus-jakarta-sans', body: 'plus-jakarta-sans', mono: 'geist-mono' }, stroke: 'regular', depth: 'soft', density: 'spacious', border: 'hairline', size: '16', leading: 'relaxed', flow: 'loose', measure: '60' },
+  },
+  {
+    id: 'playful',
+    name: 'Playful',
+    description: 'Pink, chunky icons, round display type and lifted cards.',
+    recipe: { brand: '#db2777', neutral: 'neutral', radius: 'xl', controls: 'pill', font: { heading: 'bricolage-grotesque', body: 'nunito', mono: 'fira-code' }, stroke: 'bold', depth: 'raised', density: 'comfortable', border: 'regular', size: '16', leading: 'relaxed', flow: 'normal', measure: '60' },
+  },
+  {
+    id: 'brutalist',
+    name: 'Brutalist',
+    description: 'Square corners, heavy borders, hard offset shadows, grotesk type.',
+    recipe: { brand: '#e11d48', neutral: 'neutral', radius: 'none', controls: 'match', font: { heading: 'space-grotesk', body: 'space-grotesk', mono: 'jetbrains-mono' }, stroke: 'bold', depth: 'hard', density: 'comfortable', border: 'heavy', size: '15', leading: 'tight', flow: 'tight', measure: '80' },
+  },
+  {
+    id: 'mono',
+    name: 'Mono',
+    description: 'Black and white, Geist, flat and compact: a tool, not a toy.',
+    recipe: { brand: '#18181b', neutral: 'zinc', radius: 'md', controls: 'match', font: { heading: 'geist', body: 'geist', mono: 'geist-mono' }, stroke: 'regular', depth: 'flat', density: 'compact', border: 'regular', size: '14', leading: 'tight', flow: 'tight', measure: '80' },
+  },
+  {
+    id: 'bold',
+    name: 'Bold',
+    description: 'Electric violet, heavy icons, big controls and raised surfaces.',
+    recipe: { brand: '#7c3aed', neutral: 'slate', radius: 'xl', controls: 'pill', font: { heading: 'outfit', body: 'inter', mono: 'jetbrains-mono' }, stroke: 'bold', depth: 'raised', density: 'spacious', border: 'regular', size: '18', leading: 'normal', flow: 'normal', measure: '60' },
+  },
+  {
+    id: 'calm',
+    name: 'Calm',
+    description: 'Teal on warm greys, a book serif for headings, thin lines, no shadows.',
+    recipe: { brand: '#0d9488', neutral: 'stone', radius: 'xl', controls: 'match', font: { heading: 'lora', body: 'manrope', mono: 'source-code-pro' }, stroke: 'thin', depth: 'flat', density: 'spacious', border: 'hairline', size: '16', leading: 'relaxed', flow: 'loose', measure: '70' },
+  },
+];
+
+export const presetById = (id) => PRESETS.find((p) => p.id === id);

package/lib/theme/ramp.mjs

@@ -0,0 +1,82 @@
+/**
+ * Colour ramps from a seed. A seed that is a curated ramp's 600 step returns that ramp untouched;
+ * anything else is generated in OKLCH:
+ *   - lightness per step follows the average of Tailwind's chromatic ramps (LIGHTNESS below)
+ *   - the seed lands EXACTLY on the step nearest its lightness (the anchor), and the steps around it
+ *     bend smoothly towards it, so the ramp stays monotonic
+ *   - chroma follows Tailwind's relative chroma profile, scaled so the anchor keeps the seed's chroma
+ *   - hue stays the seed's; a step outside sRGB loses chroma until it fits (never clipped)
+ */
+import { hexToOklchParts, inGamut, oklchPartsToHex } from '../color.mjs';
+import { BRAND_RAMPS, NEUTRAL_RAMPS, STEPS } from './palettes.mjs';
+
+const LIGHTNESS = { 50: 0.977, 100: 0.95, 200: 0.906, 300: 0.84, 400: 0.761, 500: 0.683, 600: 0.598, 700: 0.515, 800: 0.446, 900: 0.395, 950: 0.278 };
+const CHROMA = { 50: 0.094, 100: 0.222, 200: 0.418, 300: 0.653, 400: 0.855, 500: 0.952, 600: 0.934, 700: 0.83, 800: 0.696, 900: 0.58, 950: 0.418 };
+
+/** Map an OKLCH colour into sRGB by lowering chroma. */
+export function toGamutHex([L, C, H]) {
+  let lo = 0;
+  let hi = C;
+  if (inGamut([L, C, H])) return oklchPartsToHex([L, C, H]);
+  for (let i = 0; i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    if (inGamut([L, mid, H])) lo = mid;
+    else hi = mid;
+  }
+  return oklchPartsToHex([L, lo, H]);
+}
+
+/** The curated ramp whose 600 step is this seed, if any. */
+export function curatedRamp(seed) {
+  const hex = seed.toLowerCase();
+  return Object.entries(BRAND_RAMPS).find(([, ramp]) => ramp[600] === hex)?.[0] ?? null;
+}
+
+/** The step a seed sits on: its curated 600, or the generated step nearest its lightness. */
+export function anchorStep(seed) {
+  if (curatedRamp(seed)) return '600';
+  const [L] = hexToOklchParts(seed);
+  return STEPS.reduce((best, s) => (Math.abs(LIGHTNESS[s] - L) < Math.abs(LIGHTNESS[best] - L) ? s : best), '600');
+}
+
+/** { 50: '#…', …, 950: '#…' } for a brand seed. */
+export function brandRamp(seed) {
+  const curated = curatedRamp(seed);
+  if (curated) return { ...BRAND_RAMPS[curated] };
+
+  const [Ls, Cs, Hs] = hexToOklchParts(seed);
+  const anchor = anchorStep(seed);
+  const ai = STEPS.indexOf(anchor);
+  const dL = Ls - LIGHTNESS[anchor];
+  const chromaScale = Cs / CHROMA[anchor];
+  const ramp = {};
+  STEPS.forEach((s, i) => {
+    if (s === anchor) {
+      ramp[s] = seed.toLowerCase();
+      return;
+    }
+    // The seed's offset from the target lightness fades out over three steps either side, which keeps
+    // neighbours in order (|dL| is at most half the gap to the next step).
+    const fade = Math.max(0, 1 - Math.abs(i - ai) / 3);
+    const L = LIGHTNESS[s] + dL * fade;
+    ramp[s] = toGamutHex([L, CHROMA[s] * chromaScale, Hs]);
+  });
+  return ramp;
+}
+
+const TINT_CHROMA = { 50: 0.003, 100: 0.005, 200: 0.008, 300: 0.012, 400: 0.02, 500: 0.024, 600: 0.022, 700: 0.02, 800: 0.016, 900: 0.014, 950: 0.012 };
+
+/** The 13-step neutral: 0 (white), the 11 steps, 1000 (black). */
+export function neutralRamp(kind, seed) {
+  if (kind !== 'brand') return { 0: '#ffffff', ...NEUTRAL_RAMPS[kind], 1000: '#000000' };
+  // Brand-tinted: zinc's lightness, a whisper of the brand hue (more in the mid steps, as slate does).
+  const [, Cs, Hs] = hexToOklchParts(seed);
+  const strength = Math.min(1, Cs / 0.12);
+  const ramp = { 0: '#ffffff' };
+  for (const s of STEPS) {
+    const [L] = hexToOklchParts(NEUTRAL_RAMPS.zinc[s]);
+    ramp[s] = toGamutHex([L, TINT_CHROMA[s] * strength, Hs]);
+  }
+  ramp[1000] = '#000000';
+  return ramp;
+}

package/lib/theme/recipe.mjs

@@ -0,0 +1,187 @@
+/**
+ * A theme RECIPE: the handful of choices a theme is made from. The generator (index.mjs) expands it
+ * into primitives, semantic tokens and CSS variables; the codec (codec.mjs) packs it into a short code.
+ *
+ * Every option list is APPEND-ONLY: codes store an option's index. Add new options at the end.
+ *
+ * The typeset (font.mono, size, leading, flow, measure) came later. A recipe without it gets the defaults,
+ * which are what the kits always had, and a theme with the default typeset still encodes as a ht1 code.
+ */
+import { FONTS } from './fonts.mjs';
+
+export const RECIPE_VERSION = 1;
+
+export const OPTIONS = {
+  /** The neutral ramp: four curated greys plus one tinted with the brand hue. */
+  neutral: ['zinc', 'neutral', 'slate', 'stone', 'gray', 'brand'],
+  /** Base corner radius (px). Tailwind's rounded-sm…2xl are offsets from it. */
+  radius: ['none', 'sm', 'md', 'lg', 'xl', '2xl'],
+  /** Controls (buttons, inputs, chips) follow the radius, or are pills. */
+  controls: ['pill', 'match'],
+  /** Lucide stroke width. */
+  stroke: ['regular', 'thin', 'bold'],
+  /** Elevation of cards, sheets and menus. */
+  depth: ['soft', 'flat', 'raised', 'hard'],
+  /** Control heights and padding. */
+  density: ['comfortable', 'compact', 'spacious'],
+  /** Border width of cards, inputs and outlines. */
+  border: ['regular', 'hairline', 'heavy'],
+  /** Typeset: the body text size (px). Every text size scales with it (text-xs…4xl). */
+  size: ['16', '14', '15', '18'],
+  /** Typeset: line height of running text; the text sizes' own line heights scale with it. */
+  leading: ['normal', 'tight', 'relaxed'],
+  /** Typeset: the space between blocks of long-form text (Prose). */
+  flow: ['normal', 'tight', 'loose'],
+  /** Typeset: the longest line of long-form text (Prose), in characters. */
+  measure: ['70', '60', '80', '90'],
+};
+
+/** The recipe keys that make up the typeset, besides font.mono. */
+export const TYPESET_KEYS = ['size', 'leading', 'flow', 'measure'];
+
+/** Base radius per option: a primitive radius step (a reference) or 0. */
+export const RADIUS = { none: 0, sm: 'sm', md: 'md', lg: 'lg', xl: 'xl', '2xl': '2xl' };
+export const STROKE = { thin: 1.5, regular: 2, bold: 2.5 };
+/** px; hairline renders as one device pixel on a 2x screen. */
+export const BORDER = { hairline: 0.5, regular: 1, heavy: 2 };
+/** Line height of running text (× size). 1.75 = leading-7 at 16px, what the kits' paragraphs always had. */
+export const LEADING = { tight: 1.6, normal: 1.75, relaxed: 1.9 };
+/** Space between blocks of long-form text, in em. */
+export const FLOW = { tight: 1, normal: 1.25, loose: 2 };
+/**
+ * Line height (px) of each text size at 16px: Tailwind's defaults (3 and 4 agree). The typeset scales both;
+ * text-5xl and up keep Tailwind's (line height 1).
+ */
+export const TEXT_LINE_HEIGHT = { xs: 16, sm: 20, base: 24, lg: 28, xl: 28, '2xl': 32, '3xl': 36, '4xl': 40 };
+
+/** The default typeset as tokens (semantic.type), for a token file from before the typeset. */
+export const TYPE = { size: 16, leading: LEADING.normal, flow: FLOW.normal, measure: 70 };
+
+/**
+ * The typeset as the numbers the targets use: every text size scales by size / 16, every text size's line
+ * height by leading / 1.75 (so the default typeset is exactly Tailwind's scale), and long-form text (Prose)
+ * gets the leading, flow (em) and measure (ch) as they are.
+ */
+export const typeScale = ({ size, leading, flow, measure }) => ({
+  size,
+  scale: Number((size / 16).toFixed(4)),
+  leading,
+  leadingFactor: Number((leading / 1.75).toFixed(4)),
+  flow,
+  measure,
+});
+
+
+const s = (x, y, blur, spread, color) => ({ offsetX: x, offsetY: y, blur, spread, color });
+/**
+ * Three elevation levels per depth (DTCG shadow values, light and dark): 1 for controls and cards,
+ * 2 for raised cards and popovers, 3 for menus, dialogs and floating buttons. An empty list is no shadow.
+ * Flat keeps a faint level 3 so a menu still separates from the page.
+ */
+export const DEPTH = {
+  flat: {
+    1: { light: [], dark: [] },
+    2: { light: [], dark: [] },
+    3: { light: [s(0, 4, 12, 0, '#0000001a')], dark: [s(0, 4, 12, 0, '#00000066')] },
+  },
+  soft: {
+    1: { light: [s(0, 1, 2, 0, '#0000000d')], dark: [s(0, 1, 2, 0, '#0000004d')] },
+    2: { light: [s(0, 4, 12, -2, '#00000014')], dark: [s(0, 4, 12, -2, '#00000066')] },
+    3: { light: [s(0, 12, 24, -6, '#0000001f')], dark: [s(0, 12, 24, -6, '#00000080')] },
+  },
+  raised: {
+    1: { light: [s(0, 2, 8, -2, '#0000001f')], dark: [s(0, 2, 8, -2, '#00000066')] },
+    2: { light: [s(0, 8, 20, -6, '#0000002e')], dark: [s(0, 8, 20, -6, '#00000080')] },
+    3: { light: [s(0, 20, 40, -10, '#00000040')], dark: [s(0, 20, 40, -10, '#00000099')] },
+  },
+  hard: {
+    1: { light: [s(2, 2, 0, 0, '#09090b')], dark: [s(2, 2, 0, 0, '#fafafa')] },
+    2: { light: [s(3, 3, 0, 0, '#09090b')], dark: [s(3, 3, 0, 0, '#fafafa')] },
+    3: { light: [s(5, 5, 0, 0, '#09090b')], dark: [s(5, 5, 0, 0, '#fafafa')] },
+  },
+};
+
+/** A DTCG shadow list as CSS. */
+export const shadowCss = (list) =>
+  list.length ? list.map((x) => `${x.offsetX}px ${x.offsetY}px ${x.blur}px ${x.spread}px ${hexAlphaToRgba(x.color)}`).join(', ') : '0 0 #0000';
+
+function hexAlphaToRgba(hex) {
+  const n = parseInt(hex.slice(1, 7), 16);
+  const a = hex.length === 9 ? parseInt(hex.slice(7), 16) / 255 : 1;
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${Number(a.toFixed(3))})`;
+}
+
+/**
+ * Density: control heights (sm / md / lg) and horizontal padding on mobile, and a scale for the web kit's
+ * whole spacing scale (Tailwind 4's --spacing, the way Radix Themes' `scaling` works).
+ */
+export const DENSITY = {
+  compact: { sm: 36, md: 44, lg: 52, x: 16, scale: 0.875 },
+  comfortable: { sm: 40, md: 48, lg: 56, x: 20, scale: 1 },
+  spacious: { sm: 44, md: 52, lg: 60, x: 24, scale: 1.125 },
+};
+
+export const DEFAULT_RECIPE = Object.freeze({
+  v: RECIPE_VERSION,
+  brand: '#2563eb',
+  neutral: 'zinc',
+  radius: 'lg',
+  controls: 'pill',
+  font: Object.freeze({ heading: 'system', body: 'system', mono: 'system-mono' }),
+  stroke: 'regular',
+  depth: 'soft',
+  density: 'comfortable',
+  border: 'regular',
+  size: '16',
+  leading: 'normal',
+  flow: 'normal',
+  measure: '70',
+});
+
+const HEX = /^#[0-9a-f]{6}$/;
+
+/** Does the recipe use the default typeset (what every ht1 code means)? */
+export const defaultTypeset = (r) => r.font.mono === DEFAULT_RECIPE.font.mono && TYPESET_KEYS.every((k) => r[k] === DEFAULT_RECIPE[k]);
+
+/** Fill in defaults, normalise, and throw on anything invalid. Returns a new, plain recipe. */
+export function normalizeRecipe(input = {}) {
+  const r = { ...DEFAULT_RECIPE, ...input, font: { ...DEFAULT_RECIPE.font, ...input.font } };
+  r.v = RECIPE_VERSION;
+  r.brand = String(r.brand).toLowerCase();
+  if (!HEX.test(r.brand)) throw new Error(`Recipe brand must be a 6-digit hex colour, got "${input.brand}"`);
+  for (const [key, list] of Object.entries(OPTIONS)) {
+    if (typeof r[key] === 'number') r[key] = String(r[key]);
+    if (!list.includes(r[key])) throw new Error(`Recipe ${key} must be one of ${list.join(', ')}; got "${r[key]}"`);
+  }
+  for (const role of ['heading', 'body', 'mono']) {
+    const font = FONTS.find((f) => f.id === r.font[role]);
+    if (!font) throw new Error(`Unknown ${role} font "${r.font[role]}"`);
+    // The system fonts belong to their role: System for heading and body, System mono for mono.
+    if (font.system && (font.category === 'mono') !== (role === 'mono')) throw new Error(`"${font.id}" can't be the ${role} font`);
+    if (role === 'mono' && font.category !== 'mono') throw new Error(`The mono font must be a mono font; "${font.id}" is ${font.category}`);
+  }
+  const out = {
+    v: r.v,
+    brand: r.brand,
+    neutral: r.neutral,
+    radius: r.radius,
+    controls: r.controls,
+    font: { heading: r.font.heading, body: r.font.body, mono: r.font.mono },
+    stroke: r.stroke,
+    depth: r.depth,
+    density: r.density,
+    border: r.border,
+    size: r.size,
+    leading: r.leading,
+    flow: r.flow,
+    measure: r.measure,
+  };
+  if (input.preset) out.preset = String(input.preset);
+  return out;
+}
+
+/** Same theme? (ignores the preset label) */
+export function sameRecipe(a, b) {
+  const strip = ({ preset, ...rest }) => rest;
+  return JSON.stringify(strip(normalizeRecipe(a))) === JSON.stringify(strip(normalizeRecipe(b)));
+}

package/lib/theme/refs.mjs

@@ -0,0 +1,45 @@
+/**
+ * A small DTCG reference resolver that runs anywhere (browser included). The build resolves with Style
+ * Dictionary (lib/resolve.mjs, Node only); the theme generator and the docs site's live picker use this
+ * one, and a test holds the two to the same answer on the real tokens.json.
+ *
+ * resolveTree(source, mode) → [{ path: ['semantic','color','primary'], $type, $value }] in source order,
+ * with every { light, dark } value collapsed to `mode` and every "{a.b.c}" reference followed.
+ */
+export const MODES = ['light', 'dark'];
+
+export const isModed = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) && MODES.every((m) => m in value);
+
+const REF = /^\{([^{}]+)\}$/;
+
+/** Flatten a token tree: [{ path, $type, $value }] for every node with a $value, in order. */
+export function flatten(node, path = []) {
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) return [];
+  if ('$value' in node) return [{ path, $type: node.$type, $value: node.$value }];
+  return Object.entries(node)
+    .filter(([key]) => !key.startsWith('$'))
+    .flatMap(([key, child]) => flatten(child, [...path, key]));
+}
+
+export function resolveTree(source, mode) {
+  const tokens = flatten(source);
+  const byPath = new Map(tokens.map((t) => [t.path.join('.'), t]));
+  const value = (t) => (isModed(t.$value) ? t.$value[mode] : t.$value);
+
+  const resolve = (raw, seen) => {
+    const m = typeof raw === 'string' ? REF.exec(raw) : null;
+    if (!m) return raw;
+    const target = byPath.get(m[1]);
+    if (!target) throw new Error(`Unresolved reference ${raw}`);
+    if (seen.has(m[1])) throw new Error(`Circular reference ${[...seen, m[1]].join(' → ')}`);
+    return resolve(value(target), new Set([...seen, m[1]]));
+  };
+
+  return tokens.map((t) => ({ ...t, $value: resolve(value(t), new Set([t.path.join('.')])) }));
+}
+
+/** { 'semantic.color.primary': '#2563eb', … } for one mode. */
+export function resolvedMap(source, mode) {
+  return Object.fromEntries(resolveTree(source, mode).map((t) => [t.path.join('.'), t.$value]));
+}

package/lib/theme/semantic.mjs

@@ -0,0 +1,64 @@
+/**
+ * The semantic colour map a theme writes: shadcn names (plus success/warning/info) → primitive
+ * references per mode. With a curated seed this is exactly the kit's original map; a generated seed
+ * moves the brand steps to wherever the seed landed (its anchor).
+ */
+const n = (step) => `{primitive.color.neutral.${step}}`;
+const b = (step) => `{primitive.color.brand.${step}}`;
+const p = (ramp, step) => `{primitive.color.${ramp}.${step}}`;
+
+/** The brand step for dark mode: light seeds stay, darker ones lift so they read on a dark page. */
+const DARK_STEP = { 600: '500', 700: '400', 800: '300', 900: '200', 950: '100' };
+export const darkStep = (anchor) => DARK_STEP[anchor] ?? anchor;
+
+/** { name: { light: ref, dark: ref } } in the order the kit's tokens.json lists them. */
+export function semanticColors(anchor = '600') {
+  const brand = { light: b(anchor), dark: b(darkStep(anchor)) };
+  const onDark = { light: n(0), dark: n(950) };
+  return {
+    background: { light: n(0), dark: n(950) },
+    foreground: { light: n(950), dark: n(50) },
+    card: { light: n(0), dark: n(900) },
+    'card-foreground': { light: n(950), dark: n(50) },
+    popover: { light: n(0), dark: n(900) },
+    'popover-foreground': { light: n(950), dark: n(50) },
+    primary: brand,
+    'primary-foreground': onDark,
+    secondary: { light: n(100), dark: n(800) },
+    'secondary-foreground': { light: n(900), dark: n(50) },
+    muted: { light: n(100), dark: n(800) },
+    'muted-foreground': { light: n(600), dark: n(400) },
+    accent: { light: n(100), dark: n(800) },
+    'accent-foreground': { light: n(900), dark: n(50) },
+    destructive: { light: p('danger', 600), dark: p('danger', 500) },
+    'destructive-foreground': onDark,
+    success: { light: p('success', 700), dark: p('success', 500) },
+    'success-foreground': onDark,
+    warning: { light: p('warning', 700), dark: p('warning', 400) },
+    'warning-foreground': onDark,
+    info: { light: p('info', 700), dark: p('info', 500) },
+    'info-foreground': onDark,
+    border: { light: n(200), dark: n(800) },
+    input: { light: n(200), dark: n(800) },
+    ring: brand,
+    sidebar: { light: n(50), dark: n(900) },
+    'sidebar-foreground': { light: n(950), dark: n(50) },
+    'sidebar-primary': brand,
+    'sidebar-primary-foreground': onDark,
+    'sidebar-accent': { light: n(100), dark: n(800) },
+    'sidebar-accent-foreground': { light: n(900), dark: n(50) },
+    'sidebar-border': { light: n(200), dark: n(800) },
+    'sidebar-ring': brand,
+    'chart-1': { light: b(500), dark: b(400) },
+    'chart-2': { light: p('success', 500), dark: p('success', 400) },
+    'chart-3': { light: p('warning', 500), dark: p('warning', 400) },
+    'chart-4': { light: p('danger', 500), dark: p('danger', 400) },
+    'chart-5': { light: p('info', 500), dark: p('info', 400) },
+  };
+}
+
+/** Tokens that share the brand step; when the fixer moves `primary`, these move with it. */
+export const BRAND_LINKED = ['ring', 'sidebar-primary', 'sidebar-ring'];
+
+/** The neutral steps a foreground can flip between. */
+export const FOREGROUND_CHOICES = [n(0), n(950)];

package/lib/theme/vars.mjs

@@ -0,0 +1,54 @@
+/**
+ * A generated theme as CSS variables, in the format each app's build writes them, so a live override
+ * matches what `tokens:build` would produce:
+ *   'hsl'    NativeWind 4 / shadcn v3 triplets (`221.2 83.2% 53.3%`) — the mobile kit
+ *   'oklch'  Tailwind 4 / shadcn web (`oklch(0.546 0.2152 262.88)`) — the web kit and the docs site
+ */
+import { hexToHslTriplet, hexToOklch } from '../color.mjs';
+import { shadowCss } from './recipe.mjs';
+
+export const rem = (px) => (px >= 9999 ? '9999px' : `${px / 16}rem`);
+
+const camel = (s) => s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+
+/** The typeset's variables (both formats): text sizes and line heights scale with the first two. */
+export const typeVars = (type) => ({
+  '--type-scale': String(type.scale),
+  '--leading-factor': String(type.leadingFactor),
+  '--typeset-leading': String(type.leading),
+  '--typeset-flow': `${type.flow}em`,
+  '--typeset-measure': `${type.measure}ch`,
+});
+
+/** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } */
+export function themeVars(theme, format) {
+  const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
+  const mode = (m) => {
+    const vars = Object.fromEntries(Object.entries(theme.resolved[m]).map(([name, hex]) => [`--${name}`, convert(hex)]));
+    if (m === 'light') {
+      vars['--radius'] = rem(theme.radius);
+      vars['--radius-control'] = rem(theme.radiusControl);
+      vars['--border-width'] = `${theme.borderWidth}px`;
+      vars['--icon-stroke'] = String(theme.stroke);
+      vars['--density'] = String(theme.density.scale);
+      for (const size of ['sm', 'md', 'lg', 'x']) vars[`--control-${size}`] = `${theme.density[size]}px`;
+      Object.assign(vars, typeVars(theme.type));
+    }
+    for (const [level, value] of Object.entries(theme.semantic.shadow)) vars[`--shadow-${level}`] = shadowCss(value[m]);
+    return vars;
+  };
+  return { light: mode('light'), dark: mode('dark') };
+}
+
+/** { light: { primary: '#…', primaryForeground: '#…' }, dark: { … } } — the shape of the kit's THEME. */
+export function themeHex(theme) {
+  const mode = (m) => Object.fromEntries(Object.entries(theme.resolved[m]).map(([name, hex]) => [camel(name), hex]));
+  return { light: mode('light'), dark: mode('dark') };
+}
+
+/** A stylesheet that applies the theme: `:root { … } <dark> { … }`. */
+export function themeCss(theme, { format = 'oklch', light = ':root', dark = '.dark' } = {}) {
+  const vars = themeVars(theme, format);
+  const block = (selector, map) => `${selector} {\n${Object.entries(map).map(([k, v]) => `  ${k}: ${v};`).join('\n')}\n}`;
+  return `${block(light, vars.light)}\n${block(dark, vars.dark)}\n`;
+}

package/lib/theme-cli.mjs

@@ -0,0 +1,148 @@
+/**
+ * `halftone-tokens theme …` — commit a theme from the docs picker into tokens.json.
+ *
+ *   theme apply <code|preset|recipe.json> [--dry-run] [--force]
+ *        write the theme into tokens.json (only the paths a theme owns) and rebuild
+ *   theme show [--check]   the applied theme, its code and any hand edits since (drift)
+ *                          --check: exit 1 if the recorded theme no longer reproduces (CI)
+ *   theme presets          list the presets and their codes
+ *   theme encode <recipe.json>   print the code for a recipe file
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { FONTS } from './theme/fonts.mjs';
+
+import {
+  applyRecipe,
+  decodeRecipe,
+  encodeRecipe,
+  fontById,
+  isThemeCode,
+  normalizeRecipe,
+  presetById,
+  PRESETS,
+  themeStatus,
+} from './theme/index.mjs';
+
+const fail = (message, code = 1) => {
+  console.error(`halftone-tokens theme: ${message}`);
+  process.exit(code);
+};
+
+function readRecipe(arg, root) {
+  if (!arg) fail('say which theme: a code (ht1-… or ht2-…), a preset name or a recipe .json', 2);
+  if (isThemeCode(arg)) {
+    try {
+      return decodeRecipe(arg);
+    } catch (error) {
+      fail(error.message);
+    }
+  }
+  const preset = presetById(arg.toLowerCase());
+  if (preset) return normalizeRecipe({ ...preset.recipe, preset: preset.id });
+  const file = join(root, arg);
+  if (arg.endsWith('.json') && existsSync(file)) return normalizeRecipe(JSON.parse(readFileSync(file, 'utf8')));
+  fail(`"${arg}" is not a theme code, a preset (${PRESETS.map((p) => p.id).join(', ')}) or a recipe file`, 2);
+}
+
+const describe = (input) => {
+  // A recipe recorded by an older halftone-tokens has no typeset: it gets the defaults.
+  const recipe = normalizeRecipe(input);
+  const font = (id) => {
+    const f = fontById(id);
+    return f?.system ? (f.category === 'mono' ? 'system mono' : 'system') : (f?.family ?? id);
+  };
+  return [
+    `brand ${recipe.brand} · neutral ${recipe.neutral} · radius ${recipe.radius} · controls ${recipe.controls}`,
+    `type ${font(recipe.font.heading)} / ${font(recipe.font.body)} · stroke ${recipe.stroke} · depth ${recipe.depth} · density ${recipe.density} · border ${recipe.border}`,
+    `typeset ${recipe.size}px · leading ${recipe.leading} · flow ${recipe.flow} · measure ${recipe.measure}ch · mono ${font(recipe.font.mono)}`,
+  ].join('\n  ');
+};
+
+/** positional: [subcommand, arg]; flags: { force, 'dry-run', check, … } */
+/**
+ * An Expo app needs the theme's @expo-google-fonts packages installed (the fonts target imports them).
+ * Installs the missing ones with `npx expo install`; lists any the theme no longer uses.
+ */
+function installFonts(root, config, theme, flags) {
+  if (config.targets?.fonts?.platform !== 'expo') return;
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  const have = new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).filter((d) => d.startsWith('@expo-google-fonts/')));
+  const ids = Object.values(theme.recipe.font).filter((id) => !fontById(id)?.system);
+  const need = [...new Set(ids)].map((id) => `@expo-google-fonts/${id}`);
+  const missing = need.filter((p) => !have.has(p));
+  const unused = [...have].filter((p) => !need.includes(p) && FONTS.some((f) => `@expo-google-fonts/${f.id}` === p));
+  if (missing.length) {
+    if (flags['no-install']) {
+      console.log(`\nInstall the theme's fonts: npx expo install ${missing.join(' ')}`);
+    } else {
+      console.log(`\nInstalling ${missing.join(', ')}…`);
+      const r = spawnSync('npx', ['expo', 'install', ...missing], { cwd: root, stdio: 'inherit' });
+      if (r.status !== 0) fail(`could not install ${missing.join(' ')}; run \`npx expo install ${missing.join(' ')}\` yourself, then \`npm run tokens:build\`.`);
+    }
+  }
+  if (unused.length) console.log(`\nNo longer used by the theme (remove when you like): npm uninstall ${unused.join(' ')}`);
+}
+
+export async function themeCommand({ positional, flags, root, sourcePath, config, build }) {
+  const [sub = 'show', arg] = positional;
+  const tokens = () => JSON.parse(readFileSync(sourcePath, 'utf8'));
+
+  if (sub === 'presets') {
+    for (const p of PRESETS) console.log(`${p.id.padEnd(12)} ${encodeRecipe(p.recipe)}  ${p.description}`);
+    return;
+  }
+
+  if (sub === 'encode') {
+    console.log(encodeRecipe(readRecipe(arg, root)));
+    return;
+  }
+
+  if (sub === 'show') {
+    const status = themeStatus(tokens());
+    if (!status.applied) {
+      console.log('No theme recorded in tokens.json. Apply one with `halftone-tokens theme apply <code|preset>`.');
+      if (flags.check) process.exit(0);
+      return;
+    }
+    const name = status.recipe.preset ? ` (${presetById(status.recipe.preset)?.name ?? status.recipe.preset})` : '';
+    console.log(`Theme ${status.code}${name}\n  ${describe(status.recipe)}`);
+    if (status.drift.length) {
+      console.log(`\nEdited by hand since it was applied (${status.drift.length}):\n${status.drift.map((p) => `  ${p}`).join('\n')}`);
+      if (flags.check) fail('tokens.json no longer matches its recorded theme. Re-apply it, or apply with --force to record the edits away.');
+    }
+    return;
+  }
+
+  if (sub === 'apply') {
+    const recipe = readRecipe(arg, root);
+    const current = tokens();
+    const status = themeStatus(current);
+    const blocked = !status.applied
+      ? 'tokens.json has no theme recorded, so applying one would overwrite its brand and neutral ramps, semantic colours and radius ' +
+        'without knowing whether they were customised. Re-run with --force to go ahead.'
+      : status.drift.length
+        ? `these theme tokens were edited by hand since ${status.code} was applied:\n${status.drift.map((p) => `  ${p}`).join('\n')}\nRe-run with --force to overwrite them.`
+        : null;
+    if (blocked && !flags.force && !flags['dry-run']) fail(blocked);
+    const { tokens: next, theme } = applyRecipe(current, recipe);
+    console.log(`Theme ${theme.code}${recipe.preset ? ` (${presetById(recipe.preset)?.name})` : ''}\n  ${describe(theme.recipe)}`);
+    if (theme.adjustments.length) {
+      console.log(`\nAdjusted for contrast (WCAG AA), hue kept:`);
+      for (const a of theme.adjustments) console.log(`  ${a.mode.padEnd(5)} ${a.token.padEnd(28)} ${a.from} → ${a.to}`);
+    }
+    if (flags['dry-run']) {
+      console.log(`\n--dry-run: nothing written.${blocked && !flags.force ? `\nNote: ${blocked}` : ''}`);
+      return;
+    }
+    writeFileSync(sourcePath, JSON.stringify(next, null, 2) + '\n');
+    console.log(`\nWrote ${sourcePath.slice(root.length + 1)}.`);
+    installFonts(root, config, theme, flags);
+    await build();
+    return;
+  }
+
+  fail(`unknown command "theme ${sub}". Use apply, show, presets or encode.`, 2);
+}