@halftone-ds/tokens 1.2.0 → 1.3.0

package/README.md

@@ -61,7 +61,8 @@ npx halftone-tokens theme resolve [--json]     # the code for tokens.json as it
 npx halftone-tokens theme shadcn <theme> [--out file] [--fonts-url url]   # a shadcn registry:theme item
 ```
 
-`<theme>` is a Halftone code (`ht1-…`, `ht2-…`, `ht3-…`), a preset name, a recipe `.json`, or a
+`<theme>` is a Halftone code (`ht1-…`, `ht2-…`, `ht3-…`), a preset name, a recipe `.json`, a system
+`.halftone.json` (see Systems), or a
 [shadcn/ui](https://ui.shadcn.com/create) preset code (`b5owWMfJ8l`). A shadcn code becomes the nearest Halftone
 recipe, and what it approximates or drops (shadcn-only greys, radius steps, fonts outside the list, icon
 libraries, chart colours, menu options, styles) is listed on stderr. The other way, `theme shadcn` writes the
@@ -71,6 +72,47 @@ as `registry:font` dependencies (hosted at halftonedesignsystem.com/r/font, or `
 From code: `decodeShadcnPreset`, `recipeFromShadcn`, `shadcnTheme` and `shadcnFont` in
 `@halftone-ds/tokens/theme` (browser-safe). The preset codec is ported from shadcn/ui (MIT).
 
+## Systems
+
+A **system** (`name.halftone.json`, what the Halftone Studio saves) is a recipe plus whatever was edited by hand
+on top of it: a seed per colour role (brand, neutral, danger, success, warning, info) with a 50–950 ramp, steps
+edited by hand, the role mapping for light and dark, text styles (h1–h4, lead, p, large, small, muted, code,
+blockquote), any Google Fonts family, corners, shadows, borders, named extras, component edits (Button, Chip,
+Badge, Input), and the brand (name, logos, icon background).
+
+```bash
+npx halftone-tokens theme apply ./acme.halftone.json   # writes tokens.json and records the system
+npx halftone-tokens theme show                         # the system, its overrides, and any contrast warnings
+npx halftone-tokens theme encode ./acme.halftone.json  # its ht- code, when it has no overrides
+```
+
+- `tokens.json` records the document under `$extensions`, without its brand images. A system with overrides has
+  no `ht-` code: a code only carries a recipe.
+- Generated colours are fixed for contrast as a recipe's are. A colour chosen by hand (a mapped role, an edited
+  step) is never moved: a pairing it fails is a warning.
+- A status ramp from a seed replaces the file's; applying a theme without one puts the curated ramp back.
+- Edited text styles are written as `semantic.type.<style>.{size,leading,weight,tracking,font}`, corners as
+  `semantic.radius.<step>` (the build uses them as fixed px), extras under `extra.*` (exported, not drawn by
+  the kits).
+- Every text style (`h1 h2 h3 h4 lead p large small muted code blockquote`), edited or not, is built as
+  `--type-<style>-{size,leading,weight,tracking}` (plus `-font` on Tailwind 4). nativewind3 adds the `text-`,
+  `leading-`, `tracking-` and `font-type-<style>` keys; shadcn-web adds `type-<style>` utilities; ts-theme adds
+  `TOKENS.textStyles`. With no edits they draw exactly what Tailwind's `text-*` classes did, with one exception:
+  tracking is em on every platform, so on native it scales with the style's size (NativeWind's own `tracking-*`
+  are fixed px there: `tracking-tight` is -0.25px). `themeVars` carries the styles to live previews
+  (`textStyleVars`, `themeTextStyles`).
+- Every theme writes a component layer, `semantic.component.<button|chip|badge|input>`: a corner, heights and
+  padding, a text style and each variant's fill, label, border and pressed colours (references to semantic
+  colours). Both kits read it as `--button-*`, `--chip-*`, `--badge-*` and `--field-*` (`bg-button-primary-bg`,
+  `rounded-chip`, `h-button-md`, `text-type-button` in nativewind3; `type-button` and the same colours in
+  shadcn-web), so a Button looks the same in both. A system's `components` sets any of it (roles by name, a
+  Foundations corner or px). The build's contrast gate checks every variant's label on its fill.
+
+From code (`@halftone-ds/tokens/system`, also in `/theme`, browser-safe): `normalizeSystem` / `validateSystem`,
+`createSystem`, `migrate(recipe | code, brand)` and `systemToRecipe`, `generateSystem(system, tokens)` (the same
+shape as `generateTheme`, plus `warnings`), `systemRamps`, `textStyles`, `systemRadii`, `systemCode` and
+`applySystem`. The document's shape is described in `lib/system/schema.mjs`.
+
 ## Guarantees
 
 - **Contrast check.** Every `X` / `X-foreground` pairing, body and muted text on every surface, each status

package/cli.mjs

@@ -22,7 +22,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { checkContrast, AA, describeTintLimits, textOnTintLimits } from './lib/contrast.mjs';
+import { checkContrast, AA, componentFailures, describeTintLimits, textOnTintLimits } from './lib/contrast.mjs';
 import { scanTintText } from './lib/scan.mjs';
 import { loadTokens } from './lib/resolve.mjs';
 
@@ -89,7 +89,10 @@ export async function run(argv = process.argv.slice(2)) {
   };
 
   // `strict: true` here is the full set of pairings (muted and accent surfaces too), not the CLI flag.
-  const failures = checkContrast(ctx.colors, { strict: true });
+  const base = checkContrast(ctx.colors, { strict: true });
+  // The components' own pairings (a Button variant's label on its fill), once per colour pair.
+  const seen = new Set(base.map((line) => /^\s+(\w+) .*\((#\w+) on (#\w+)\)$/.exec(line)?.slice(1).join(' ')));
+  const failures = [...base, ...componentFailures(ctx.components, ctx.colors, seen)];
   ctx.contrastFailures = failures;
   if (failures.length) {
     gate(

package/lib/contrast.mjs

@@ -5,6 +5,7 @@
  */
 import { apcaContrast } from './apca.mjs';
 import { blend, contrast } from './color.mjs';
+import { componentPairs } from './theme/components.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.
@@ -125,3 +126,35 @@ 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)];
 }
+
+/**
+ * The component layer's label-on-fill pairings (lib/theme/components.mjs), in both modes, as rows like contrastReport's:
+ * { mode, label, fgName, bgName, fg, bg, threshold, ratio, component, variant }. `bgName` is the fill's role.
+ */
+export function componentContrast(components, background) {
+  return ['light', 'dark'].flatMap((mode) =>
+    componentPairs(components, mode, background[mode], blend).map((p) => ({
+      mode,
+      label: p.label,
+      fgName: p.fgRole,
+      bgName: p.bgRole,
+      fg: p.fg,
+      bg: p.bg,
+      threshold: AA,
+      ratio: contrast(p.fg, p.bg),
+      component: p.component,
+      variant: p.variant,
+    }))
+  );
+}
+
+/** The failing component pairings as report lines, leaving out any colour pair `seen` already reports ('mode fg bg'). */
+export function componentFailures(components, colors, seen = new Set()) {
+  const background = Object.fromEntries(['light', 'dark'].map((mode) => [mode, colors.find((c) => c.name === 'background')?.[mode] ?? '#ffffff']));
+  const lines = new Set();
+  for (const r of componentContrast(components, background)) {
+    if (r.ratio >= r.threshold || seen.has(`${r.mode} ${r.fg} ${r.bg}`)) continue;
+    lines.add(`  ${r.mode.padEnd(5)} ${r.label.padEnd(36)} ${r.ratio.toFixed(2)} / ${r.threshold}  (${r.fg} on ${r.bg})`);
+  }
+  return [...lines];
+}

package/lib/resolve.mjs

@@ -5,7 +5,9 @@
  */
 import StyleDictionary from 'style-dictionary';
 import { readFileSync } from 'node:fs';
-import { BUTTON, DEFAULT_RECIPE, DENSITY, DEPTH, FIELD, fieldWidth, shadowCss, TYPE, typeScale } from './theme/recipe.mjs';
+import { componentLayer, readComponents } from './theme/components.mjs';
+import { extraList } from './theme/extras.mjs';
+import { BUTTON, DEFAULT_RECIPE, DENSITY, DEPTH, FIELD, fieldWidth, resolveTextStyles, shadowCss, textEdits, TYPE, typeScale } from './theme/recipe.mjs';
 
 export const MODES = ['light', 'dark'];
 
@@ -45,48 +47,78 @@ export function cssName(token) {
 /**
  * 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.
+ * of 0 makes every rounded-* square. A system can set a step outright (semantic.radius.md = 6): that step is
+ * `fixed` at its px and no longer follows the base.
+ *   → [{ name, scale, px, fixed }]
  */
-function radiusScales(prim) {
+function radiusScales(prim, sem, base) {
   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)) }));
+  const fixed = Object.fromEntries(sem.filter((t) => t.path[1] === 'radius' && t.path.length === 3).map((t) => [t.path[2], t.$value]));
+  return steps.map((t) => {
+    const scale = Number((t.$value / anchor).toFixed(4));
+    const set = typeof fixed[t.path[2]] === 'number';
+    return { name: t.path[2], scale, px: set ? fixed[t.path[2]] : Math.round(base * scale * 10) / 10, fixed: set };
+  });
 }
 
 export function radiusCalc(scale) {
   return scale === 1 ? 'var(--radius)' : `calc(var(--radius) * ${scale})`;
 }
 
+/** A radius step as CSS: a multiple of --radius, or its own px when a system fixed it. */
+export function radiusCss(step) {
+  return step.fixed ? (step.px >= 9999 ? '9999px' : `${Number((step.px / 16).toFixed(4))}rem`) : radiusCalc(step.scale);
+}
+
 /**
  * Everything a target needs:
- *   semLight / semDark   semantic tokens per mode (colours + radius), in tokens.json order
+ *   semLight / semDark   semantic tokens per mode (colours + radius), in tokens.json order, but the component layer
+ *   compLight / compDark the component layer's tokens per mode (semantic.component.*; read as `components` below)
  *   prim                 primitive tokens (mode-independent)
  *   colors               [{ name, light, dark }] semantic colours as hex
- *   radius               { base: px, steps: [{ name, scale }] }
+ *   radius               { base: px, steps: [{ name, scale, px, fixed }] } (fixed: set by a system, not scaled)
  *   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)
+ *   textStyles           { h1: { font, weight, size, leading, tracking, edited }, … } the Text variants at the typeset,
+ *                          with a system's edited styles (semantic.type.<style>) on top (recipe.mjs resolveTextStyles)
  *   shape.button/.field  the styles' numbers (semantic.button / .field), radii in px; a token file from
  *                          before the styles gets solid buttons and outline fields, and colours to match
  *   styles               { button, field }: the style names, from the recorded theme (or the defaults)
+ *   extras               a system's own tokens (tokens.json `extra.*`) as lists (lib/theme/extras.mjs extraList)
+ *   components           the component layer (semantic.component.*: Button, Chip, Badge, Input) resolved, as
+ *                          lib/theme/components.mjs componentLayer returns it; a file from before it gets the defaults
  */
 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');
+  // The component layer (semantic.component.*) is read on its own (ctx.components), not as plain tokens.
+  const compLight = light.filter((t) => t.path[0] === 'semantic' && t.path[1] === 'component');
+  const compDark = dark.filter((t) => t.path[0] === 'semantic' && t.path[1] === 'component');
+  const semLight = light.filter((t) => t.path[0] === 'semantic' && t.path[1] !== 'component');
+  const semDark = dark.filter((t) => t.path[0] === 'semantic' && t.path[1] !== 'component');
   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 radiusBase = semLight.find((t) => cssName(t) === 'radius').$value;
   const radius = {
-    base: semLight.find((t) => cssName(t) === 'radius').$value,
-    steps: radiusScales(prim),
+    base: radiusBase,
+    steps: radiusScales(prim, semLight, radiusBase),
   };
   const find = (list, name) => list.find((t) => cssName(t) === name)?.$value;
+  // The style numbers live in the component layer (semantic.component.button / .input); older files had
+  // semantic.button / semantic.field.
+  const LEGACY = { 'button-': 'component-button-', 'field-': 'component-input-' };
+  const style = (list, name) => {
+    const prefix = Object.keys(LEGACY).find((p) => name.startsWith(p));
+    const comp = list === semDark ? compDark : compLight;
+    return find(comp, LEGACY[prefix] + name.slice(prefix.length)) ?? find(list, name);
+  };
   // Style colours a token file from before the styles doesn't have: what the components drew before.
   const byName = Object.fromEntries(colors.map((c) => [c.name, c]));
   const STYLE_FALLBACK = { button: 'primary', 'button-foreground': 'primary-foreground', 'button-edge': 'primary', field: 'input', 'field-edge': 'input' };
@@ -97,21 +129,21 @@ export async function loadTokens(sourcePath) {
   const md = radius.steps.find((s) => s.name === 'md')?.scale ?? 0.8;
   const solid = BUTTON.solid;
   const outline = FIELD.outline;
-  const fieldRound = find(semLight, 'field-round') ?? outline.round;
-  const fieldRoundBottom = find(semLight, 'field-round-bottom') ?? outline.roundBottom;
+  const fieldRound = style(semLight, 'field-round') ?? outline.round;
+  const fieldRoundBottom = style(semLight, 'field-round-bottom') ?? outline.roundBottom;
   const shape = {
     control: find(semLight, 'radius-control') ?? 9999,
     borderWidth,
     button: {
-      alpha: find(semLight, 'button-alpha') ?? solid.alpha,
-      border: find(semLight, 'button-border-width') ?? solid.border,
-      edge: find(semLight, 'button-edge-width') ?? solid.edge,
+      alpha: style(semLight, 'button-alpha') ?? solid.alpha,
+      border: style(semLight, 'button-border-width') ?? solid.border,
+      edge: style(semLight, 'button-edge-width') ?? solid.edge,
     },
     field: {
-      alpha: { light: find(semLight, 'field-alpha') ?? outline.alpha.light, dark: find(semDark, 'field-alpha') ?? outline.alpha.dark },
-      border: find(semLight, 'field-border-width') ?? fieldWidth(outline.border, borderWidth),
-      edge: find(semLight, 'field-edge-width') ?? fieldWidth(outline.edge, borderWidth),
-      inset: find(semLight, 'field-inset') ?? outline.inset,
+      alpha: { light: style(semLight, 'field-alpha') ?? outline.alpha.light, dark: style(semDark, 'field-alpha') ?? outline.alpha.dark },
+      border: style(semLight, 'field-border-width') ?? fieldWidth(outline.border, borderWidth),
+      edge: style(semLight, 'field-edge-width') ?? fieldWidth(outline.edge, borderWidth),
+      inset: style(semLight, 'field-inset') ?? outline.inset,
       radius: Number((radius.base * md * fieldRound).toFixed(4)),
       radiusBottom: Number((radius.base * md * fieldRoundBottom).toFixed(4)),
     },
@@ -123,9 +155,37 @@ export async function loadTokens(sourcePath) {
     },
   };
   const type = typeScale(Object.fromEntries(Object.entries(TYPE).map(([key, value]) => [key, find(semLight, `type-${key}`) ?? value])));
+  const textStyles = resolveTextStyles(type, textEdits(source.semantic?.type));
   const recorded = source.$extensions?.['com.halftonedesignsystem.theme']?.recipe ?? {};
   const styles = { button: recorded.button ?? DEFAULT_RECIPE.button, field: recorded.field ?? DEFAULT_RECIPE.field };
-  return { source, semLight, semDark, prim, colors, radius, shape, type, styles };
+  const extras = extraList(source.extra);
+  const components = loadComponents({ source, compLight, compDark, prim, colors, radius, shape, type, textStyles, styles, recorded });
+  return { source, semLight, semDark, compLight, compDark, prim, colors, radius, shape, type, textStyles, styles, extras, components };
+}
+
+/** The component layer from the file, or (a file from before it) the defaults on the file's colours and shape. */
+function loadComponents({ source, compLight, compDark, prim, colors, radius, shape, type, textStyles, styles, recorded }) {
+  const flat = (list) => Object.fromEntries(list.map((t) => [t.path.join('.'), t.$value]));
+  const read = readComponents(flat(compLight), flat(compDark), source.semantic?.component);
+  if (read) return read;
+  const byName = Object.fromEntries(colors.map((c) => [c.name, c]));
+  const primMap = Object.fromEntries(prim.map((t) => [t.path.join('.'), t.$value]));
+  const outline = FIELD[styles.field] ?? FIELD.outline;
+  return componentLayer({
+    styles,
+    controls: recorded.controls ?? (shape.control >= 9999 ? 'pill' : 'match'),
+    corner: (name) => radius.steps.find((s) => s.name === name)?.px ?? radius.base,
+    density: shape.density,
+    borderWidth: shape.borderWidth,
+    button: shape.button,
+    field: { ...shape.field, round: outline.round, roundBottom: outline.roundBottom },
+    textStyles,
+    type,
+    hex: (ref, mode) => {
+      const name = /^\{semantic\.color\.(.+)\}$/.exec(ref)?.[1];
+      return String(name ? byName[name]?.[mode] : primMap[ref.slice(1, -1)]).toLowerCase();
+    },
+  }).shape;
 }
 
 /** Primitive tokens under a path prefix, e.g. group(prim, ['font', 'size']) → [{ key: 'xs', value: 12 }, …]. */

package/lib/system/generate.mjs

@@ -0,0 +1,212 @@
+/**
+ * generateSystem — a HalftoneSystem expanded into a theme, the same shape generateTheme returns. Pure ESM.
+ *
+ *   generateSystem(doc, base)  base = the app's tokens.json
+ *     1. generateTheme(doc.recipe, base), with
+ *     2. a ramp for every colour role from its seed (brandRamp; a custom neutral from its seed; a status
+ *        role without one keeps base's ramp), then the steps edited by hand
+ *     3. the role mapping, light and dark: the fixer moves only generated colours; a role mapped by hand, or
+ *        on an edited step, keeps its colour, and a pairing that fails because of it is a warning
+ *     4. per-style text tokens (semantic.type.<style>.{size,leading,weight,tracking,font}) for edited styles
+ *     5. fonts, radius, shadow and border overrides
+ *     6. extras, as the `extra` token group (theme.extra)
+ *     7. the component layer (semantic.component.<name>), with the system's `components` edits on top
+ *
+ * A system with no overrides is exactly generateTheme(doc.recipe, base) (a test holds it to that).
+ * The theme's `code` is its recipe's: a lossy handle when the system has overrides (systemCode says so).
+ */
+import { encodeRecipe } from '../theme/codec.mjs';
+import { generateTheme, withComponents } from '../theme/generate.mjs';
+import { STEPS } from '../theme/palettes.mjs';
+import { anchorStep, brandRamp, neutralAnchorStep, neutralRamp, neutralSeedRamp } from '../theme/ramp.mjs';
+import { FIELD, fieldWidth, typeScale, LEADING, FLOW, resolveTextStyles } from '../theme/recipe.mjs';
+import { resolvedMap } from '../theme/refs.mjs';
+import { COLOR_ROLES, EXTRA_KINDS, hasOverrides, normalizeSystem, RADIUS_STEPS, STATUS_ROLES, TEXT_STYLES } from './schema.mjs';
+
+const round = (n, places = 4) => Number(n.toFixed(places));
+const alphaHex = (alpha) => Math.round(alpha * 255).toString(16).padStart(2, '0');
+
+/** A layer as a DTCG shadow value. */
+const shadowValue = (l) => ({ offsetX: l.x, offsetY: l.y, blur: l.blur, spread: l.spread, color: `${l.color}${alphaHex(l.alpha)}`, ...(l.inset ? { inset: true } : {}) });
+const shadowToken = (s) => ({ light: s.light.map(shadowValue), dark: s.dark.map(shadowValue) });
+
+/** The base file's primitives, resolved (its ramps may be references). */
+const basePrimitives = (base) => resolvedMap({ primitive: base.primitive }, 'light');
+
+/**
+ * Every colour role's ramp: { role: { seed, anchor, source, generated, values, edited } }.
+ *   source     'recipe' (brand, a preset neutral), 'seed' (a seed set in the system) or 'base' (a status
+ *              ramp from tokens.json)
+ *   generated  the ramp before edits; values: after them; edited: the steps edited by hand
+ * The Studio draws its ramp strips from this.
+ */
+export function systemRamps(input, base) {
+  const doc = normalizeSystem(input);
+  const { recipe, colors } = doc;
+  const prim = basePrimitives(base);
+  const out = {};
+  for (const role of COLOR_ROLES) {
+    const c = colors[role] ?? {};
+    let generated;
+    let seed;
+    let anchor;
+    let source;
+    if (role === 'brand') {
+      seed = recipe.brand;
+      anchor = c.anchor ?? anchorStep(seed);
+      generated = brandRamp(seed, { anchor: c.anchor });
+      source = 'recipe';
+    } else if (role === 'neutral') {
+      if (c.seed) {
+        seed = c.seed;
+        anchor = c.anchor ?? neutralAnchorStep(seed);
+        generated = neutralSeedRamp(seed, { anchor: c.anchor });
+        source = 'seed';
+      } else {
+        generated = neutralRamp(recipe.neutral, recipe.brand);
+        seed = recipe.neutral;
+        anchor = null;
+        source = 'recipe';
+      }
+    } else if (c.seed) {
+      seed = c.seed;
+      anchor = c.anchor ?? anchorStep(seed);
+      generated = brandRamp(seed, { anchor: c.anchor });
+      source = 'seed';
+    } else {
+      generated = Object.fromEntries(STEPS.filter((s) => `primitive.color.${role}.${s}` in prim).map((s) => [s, prim[`primitive.color.${role}.${s}`]]));
+      if (Object.keys(generated).length !== STEPS.length) throw new Error(`generateSystem: the base tokens have no ${role} ramp (primitive.color.${role}.50…950)`);
+      seed = generated['600'];
+      anchor = '600';
+      source = 'base';
+    }
+    const edited = Object.keys(c.steps ?? {});
+    out[role] = { seed, anchor, source, generated, values: { ...generated, ...c.steps }, edited };
+  }
+  return out;
+}
+
+/** A role's value as the theme writes it: '{primitive.color.brand.600}' or a hex. */
+const roleRef = (value) => (value.startsWith('#') ? value : `{primitive.color.${value}}`);
+
+/**
+ * Every text style as drawn: { h1: { font, weight, size, leading, tracking, edited: [keys] }, … }. Defaults follow
+ * the recipe's typeset (sizes × size / 16, line heights × leading / 1.75); edited keys are as set.
+ */
+export function textStyles(input) {
+  const doc = normalizeSystem(input);
+  const type = typeScale({ size: Number(doc.recipe.size), leading: LEADING[doc.recipe.leading], flow: FLOW[doc.recipe.flow], measure: Number(doc.recipe.measure) });
+  const generated = resolveTextStyles(type);
+  return Object.fromEntries(
+    TEXT_STYLES.map((name) => {
+      const { font, weight, size, leading, tracking } = generated[name];
+      const edits = doc.type[name] ?? {};
+      return [name, { font, weight, size: round(size, 2), leading: round(leading), tracking, ...edits, edited: Object.keys(edits) }];
+    })
+  );
+}
+
+/** rounded-sm…2xl in px: the base radius × each step's ratio to lg (as the build draws them), or as edited. */
+export function systemRadii(input, base, theme = generateSystem(input, base)) {
+  const doc = normalizeSystem(input);
+  const prim = basePrimitives(base);
+  const lg = prim['primitive.radius.lg'];
+  return Object.fromEntries(RADIUS_STEPS.map((step) => [step, doc.radius[step] ?? round((theme.radius * prim[`primitive.radius.${step}`]) / lg, 2)]));
+}
+
+/** The `extra` token group (DTCG) for a system's extras, or undefined when it has none. */
+function extraTokens(doc) {
+  const group = {};
+  const fontRef = (role) => `{primitive.font.family.${role}}`;
+  for (const kind of EXTRA_KINDS) {
+    if (!doc.extras[kind].length) continue;
+    group[kind] = {};
+    for (const { name, ...item } of doc.extras[kind]) {
+      if (kind === 'color') {
+        if (item.seed) {
+          const values = { ...brandRamp(item.seed, { anchor: item.anchor }), ...item.steps };
+          group.color[name] = Object.fromEntries(STEPS.map((s) => [s, { $type: 'color', $value: values[s] }]));
+        } else group.color[name] = { $type: 'color', $value: item.value };
+      }
+      if (kind === 'text') {
+        group.text[name] = {
+          font: { $type: 'fontFamily', $value: fontRef(item.font) },
+          weight: { $type: 'fontWeight', $value: item.weight },
+          size: { $type: 'number', $value: item.size },
+          leading: { $type: 'number', $value: item.leading },
+          tracking: { $type: 'number', $value: item.tracking },
+        };
+      }
+      if (kind === 'radius') group.radius[name] = { $type: 'number', $value: item.value };
+      if (kind === 'shadow') group.shadow[name] = { $type: 'shadow', $value: shadowToken(item) };
+      if (kind === 'border') {
+        group.border[name] = { width: { $type: 'number', $value: item.width }, ...(item.style ? { style: { $type: 'strokeStyle', $value: item.style } } : {}) };
+      }
+    }
+  }
+  return Object.keys(group).length ? group : undefined;
+}
+
+/** The theme for a system, on top of `base` (a tokens.json object). `fix: false` skips the contrast fixer. */
+export function generateSystem(input, base, { fix = true } = {}) {
+  const doc = normalizeSystem(input);
+  const { recipe, colors } = doc;
+
+  // 1–3. Colours: only a system that changes them goes through generateTheme's system hook.
+  const touchesColors = Object.keys(colors).length > 0 || Object.keys(doc.roles).length > 0;
+  let options = {};
+  if (touchesColors) {
+    const ramps = systemRamps(doc, base);
+    const changed = (role) => colors[role] !== undefined;
+    options = {
+      colors: {
+        ramps: Object.fromEntries(COLOR_ROLES.filter(changed).map((role) => [role, ramps[role].values])),
+        anchor: ramps.brand.anchor,
+        anchors: Object.fromEntries(STATUS_ROLES.filter((role) => colors[role]?.seed).map((role) => [role, ramps[role].anchor])),
+        roles: Object.fromEntries(Object.entries(doc.roles).map(([name, v]) => [name, Object.fromEntries(Object.entries(v).map(([mode, value]) => [mode, roleRef(value)]))])),
+        edited: Object.fromEntries(COLOR_ROLES.filter((role) => ramps[role].edited.length).map((role) => [role, ramps[role].edited])),
+      },
+    };
+  }
+  const theme = generateTheme(recipe, base, { fix, ...options });
+  if (!hasOverrides(doc)) return theme;
+
+  const semantic = { ...theme.semantic };
+  // 4. Text styles someone edited: every key, so the style is whole (the kits read all five).
+  const edited = Object.keys(doc.type);
+  if (edited.length) {
+    const styles = textStyles(doc);
+    semantic.type = { ...semantic.type };
+    for (const name of edited) {
+      const { font, weight, size, leading, tracking } = styles[name];
+      semantic.type[name] = { size, leading, weight, tracking, font: `{primitive.font.family.${font}}` };
+    }
+  }
+  // 5. Fonts, radius, shadow, border.
+  const fonts = { ...theme.fonts, ...doc.fonts };
+  if (Object.keys(doc.radius).length) semantic.radius = { ...semantic.radius, ...doc.radius };
+  if (Object.keys(doc.shadow).length) {
+    semantic.shadow = { ...semantic.shadow };
+    for (const [level, s] of Object.entries(doc.shadow)) semantic.shadow[level] = shadowToken(s);
+  }
+  let { borderWidth, field } = theme;
+  if (Object.keys(doc.border).length) {
+    semantic.border = { ...semantic.border, ...doc.border };
+    if (doc.border.width !== undefined) {
+      borderWidth = doc.border.width;
+      // The field's widths follow the border's (outline fields) or a 1px floor (filled, underline).
+      const fld = FIELD[recipe.field];
+      field = { ...field, border: fieldWidth(fld.border, borderWidth), edge: fieldWidth(fld.edge, borderWidth) };
+    }
+  }
+  // 6. Extras.
+  const extra = extraTokens(doc);
+  // 7. The component layer again, on the edited corners, border and text styles, with the system's own component edits.
+  return withComponents({ ...theme, semantic, fonts, borderWidth, field, ...(extra ? { extra } : {}) }, base, doc.components);
+}
+
+/** The ht- code for a system with no overrides; null when one would be lost (a code holds only the recipe). */
+export function systemCode(input) {
+  const doc = normalizeSystem(input);
+  return hasOverrides(doc) ? null : encodeRecipe(doc.recipe);
+}