@halftone-ds/tokens 1.1.0 → 1.3.0

package/lib/resolve.mjs

@@ -5,7 +5,9 @@
  */
 import StyleDictionary from 'style-dictionary';
 import { readFileSync } from 'node:fs';
-import { DENSITY, DEPTH, 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,50 +47,106 @@ 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' };
+  for (const [name, from] of Object.entries(STYLE_FALLBACK)) if (!byName[name] && byName[from]) colors.push({ ...byName[from], name });
   const shadows = (list, mode) =>
     Object.fromEntries(['1', '2', '3'].map((level) => [level, shadowCss(find(list, `shadow-${level}`) ?? DEPTH.soft[level][mode])]));
+  const borderWidth = find(semLight, 'border-width') ?? 1;
+  const md = radius.steps.find((s) => s.name === 'md')?.scale ?? 0.8;
+  const solid = BUTTON.solid;
+  const outline = FIELD.outline;
+  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: find(semLight, 'border-width') ?? 1,
+    borderWidth,
+    button: {
+      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: 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)),
+    },
     stroke: find(semLight, 'icon-stroke') ?? 2,
     shadows: { light: shadows(semLight, 'light'), dark: shadows(semDark, 'dark') },
     density: {
@@ -97,7 +155,37 @@ export async function loadTokens(sourcePath) {
     },
   };
   const type = typeScale(Object.fromEntries(Object.entries(TYPE).map(([key, value]) => [key, find(semLight, `type-${key}`) ?? value])));
-  return { source, semLight, semDark, prim, colors, radius, shape, type };
+  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 };
+  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);
+}

package/lib/system/index.d.mts

@@ -0,0 +1,168 @@
+/** Types for @halftone-ds/tokens/system (index.mjs): the HalftoneSystem v1 document. */
+import type { Mode, Neutral, Recipe, RecipeInput, Theme, TokensJson } from '../theme/index.mjs';
+
+export type ColorRole = 'brand' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
+export type StatusRole = 'danger' | 'success' | 'warning' | 'info';
+export type Step = '50' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | '950';
+/** The neutral also has '0' (white) and '1000' (black). */
+export type NeutralStep = Step | '0' | '1000';
+export type TextStyleName = 'h1' | 'h2' | 'h3' | 'h4' | 'lead' | 'p' | 'large' | 'small' | 'muted' | 'code' | 'blockquote';
+export type FontRole = 'heading' | 'body' | 'mono';
+export type RadiusStep = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type ShadowLevel = '1' | '2' | '3';
+export type BorderStyle = 'solid' | 'dashed' | 'dotted';
+export type ExtraKind = 'color' | 'text' | 'radius' | 'shadow' | 'border';
+/** A 6-digit lowercase hex colour, '#2563eb'. */
+export type Hex = `#${string}`;
+/** A ramp step ('brand.600', 'neutral.0') or a hex. */
+export type RoleValue = `${ColorRole}.${NeutralStep}` | Hex;
+
+/**
+ * One colour role. brand: its seed is recipe.brand (a seed here folds into it). neutral: a hex seed makes a custom
+ * neutral; a preset name folds into recipe.neutral. A status role without a seed keeps the base file's ramp.
+ */
+export type ColorOverride = {
+  seed?: Hex;
+  /** The step the seed is pinned to, when not its nearest one. */
+  anchor?: Step;
+  /** Steps edited by hand. */
+  steps?: Partial<Record<NeutralStep, Hex>>;
+};
+export type RoleOverride = { light?: RoleValue; dark?: RoleValue };
+/** size px, leading × size, tracking em. */
+export type TextStyle = { font: FontRole; weight: number; size: number; leading: number; tracking: number };
+export type ShadowLayer = { x: number; y: number; blur: number; spread: number; color: Hex; alpha: number; inset?: true };
+export type Shadow = Record<Mode, ShadowLayer[]>;
+export type BorderOverride = { width?: number; style?: BorderStyle };
+
+export type ExtraColor = { name: string } & ({ value: Hex | Record<Mode, Hex> } | { seed: Hex; anchor?: Step; steps?: Partial<Record<Step, Hex>> });
+export type ExtraText = { name: string } & TextStyle;
+export type ExtraRadius = { name: string; value: number };
+export type ExtraShadow = { name: string } & Shadow;
+export type ExtraBorder = { name: string; width: number; style?: BorderStyle };
+export type Extras = { color: ExtraColor[]; text: ExtraText[]; radius: ExtraRadius[]; shadow: ExtraShadow[]; border: ExtraBorder[] };
+
+/** As the docs site's brand store keeps it (apps/docs lib/brand/svg.ts). */
+export type BrandImage = { svg?: string; png?: string; mono?: boolean; aspect: number };
+export type IconBackground = 'brand' | 'white' | 'black' | Hex;
+export type SystemBrand = {
+  name: string;
+  iconBackground: IconBackground;
+  logo?: BrandImage;
+  logoDark?: BrandImage;
+  mark?: BrandImage;
+  markDark?: BrandImage;
+};
+
+/** A normalised system: every section present, overrides only. */
+export type HalftoneSystem = {
+  kind: 'halftone.system';
+  v: 1;
+  id: string;
+  name: string;
+  preset?: string;
+  updatedAt?: string;
+  recipe: Recipe;
+  colors: Partial<Record<ColorRole, ColorOverride>>;
+  roles: Partial<Record<string, RoleOverride>>;
+  type: Partial<Record<TextStyleName, Partial<TextStyle>>>;
+  /** Any Google Fonts family. */
+  fonts: Partial<Record<FontRole, string>>;
+  radius: Partial<Record<RadiusStep, number>>;
+  shadow: Partial<Record<ShadowLevel, Shadow>>;
+  border: BorderOverride;
+  extras: Extras;
+  brand: SystemBrand;
+  /** Component-level edits (Button, Chip, Badge, Input), overrides only. Button and Input styles fold into the recipe. */
+  components: SystemComponents;
+};
+
+/** A component colour: a role (any semantic colour), or 'none' for a fill or border. */
+export type ComponentEdit = {
+  style?: string;
+  /** A Foundations corner, or px. */
+  radius?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | number;
+  size?: Partial<Record<'sm' | 'md' | 'lg' | 'x', number>>;
+  /** A text style (h1…blockquote). */
+  text?: string;
+  variants?: Record<string, Partial<Record<'fill' | 'label' | 'border' | 'pressed', string>>>;
+};
+export type SystemComponents = Partial<Record<'button' | 'chip' | 'badge' | 'input', ComponentEdit>>;
+
+/** What normalizeSystem accepts: any section may be missing, a shadow may be a plain layer list, a layer partial. */
+export type HalftoneSystemInput = Partial<Omit<HalftoneSystem, 'recipe' | 'colors' | 'shadow' | 'extras' | 'brand' | 'components' | 'kind' | 'v'>> & {
+  kind?: 'halftone.system';
+  v?: number;
+  recipe?: RecipeInput;
+  colors?: Partial<Record<Exclude<ColorRole, 'neutral'>, ColorOverride>> & { neutral?: Omit<ColorOverride, 'seed'> & { seed?: Hex | Neutral } };
+  shadow?: Partial<Record<ShadowLevel, Partial<ShadowLayer>[] | { light?: Partial<ShadowLayer>[]; dark?: Partial<ShadowLayer>[] }>>;
+  extras?: Partial<Record<ExtraKind, Array<Record<string, unknown> & { name: string }>>>;
+  brand?: Partial<SystemBrand>;
+  components?: SystemComponents;
+};
+
+/** A contrast pairing the fixer left failing because a colour in it was chosen by hand. */
+export type ContrastWarning = { mode: Mode; label: string; fg: string; bg: string; ratio: number; threshold: number; locked: string[] };
+
+/** A colour role's ramp as the Studio draws it. */
+export type SystemRamp = {
+  /** The seed (a neutral preset's name for a preset neutral). */
+  seed: string;
+  /** The step the seed sits on (null for a preset neutral). */
+  anchor: Step | null;
+  source: 'recipe' | 'seed' | 'base';
+  /** Before edits. */
+  generated: Record<string, string>;
+  /** After edits. */
+  values: Record<string, string>;
+  edited: string[];
+};
+export type ResolvedTextStyle = TextStyle & { edited: (keyof TextStyle)[] };
+
+export const SYSTEM_KIND: 'halftone.system';
+export const SYSTEM_VERSION: 1;
+export const COLOR_ROLES: ColorRole[];
+export const STATUS_ROLES: StatusRole[];
+/** Every semantic colour a role mapping can set. */
+export const ROLE_NAMES: string[];
+export const TEXT_STYLES: TextStyleName[];
+export const TEXT_KEYS: (keyof TextStyle)[];
+export const TEXT_DEFAULTS: Record<TextStyleName, Omit<TextStyle, 'leading'> & { leading: number | 'prose' }>;
+export const FONT_ROLES: FontRole[];
+export const RADIUS_STEPS: RadiusStep[];
+export const SHADOW_LEVELS: ShadowLevel[];
+export const BORDER_STYLES: BorderStyle[];
+export const EXTRA_KINDS: ExtraKind[];
+
+export class SystemError extends Error {
+  /** Every problem, as 'path: message'. */
+  errors: string[];
+}
+export function isSystem(value: unknown): boolean;
+/** Why an extra can't take this name (a built-in slot, a Tailwind class it would shadow, a theme variable, `taken`), or null. */
+export function extraNameProblem(kind: ExtraKind, name: string, taken?: string[]): string | null;
+export function newSystemId(): string;
+export function normalizeSystem(input: HalftoneSystemInput | HalftoneSystem): HalftoneSystem;
+export function validateSystem(input: unknown): { ok: boolean; errors: string[]; system: HalftoneSystem | null };
+/** A new system with a fresh id and the time. */
+export function createSystem(input?: HalftoneSystemInput): HalftoneSystem;
+/** Every override as a path ('colors.danger.seed', 'roles.primary.dark', 'extras.color.sunset'). */
+export function systemOverrides(system: HalftoneSystemInput | HalftoneSystem): string[];
+export function hasOverrides(system: HalftoneSystemInput | HalftoneSystem): boolean;
+export function withoutBrandImages(system: HalftoneSystem): HalftoneSystem;
+
+/** The theme for a system: generateTheme's shape; `extra` holds the extras as a DTCG group. */
+export function generateSystem(system: HalftoneSystemInput | HalftoneSystem, base: TokensJson, options?: { fix?: boolean }): Theme & { extra?: Record<string, unknown> };
+/** The ht- code, or null when the system has overrides a code can't carry. */
+export function systemCode(system: HalftoneSystemInput | HalftoneSystem): string | null;
+export function systemRamps(system: HalftoneSystemInput | HalftoneSystem, base: TokensJson): Record<ColorRole, SystemRamp>;
+export function textStyles(system: HalftoneSystemInput | HalftoneSystem): Record<TextStyleName, ResolvedTextStyle>;
+/** rounded-sm…2xl in px. */
+export function systemRadii(system: HalftoneSystemInput | HalftoneSystem, base: TokensJson, theme?: Theme): Record<RadiusStep, number>;
+
+/** A system from a recipe (or an ht- code) and the Studio's brand; a document is normalised. */
+export function migrate(input: RecipeInput | string | HalftoneSystemInput, brand?: Partial<SystemBrand>, options?: { id?: string; name?: string; updatedAt?: string }): HalftoneSystem;
+/** The recipe under a system, its code (null with overrides) and the overrides a recipe loses. */
+export function systemToRecipe(system: HalftoneSystemInput | HalftoneSystem): { recipe: Recipe; code: string | null; lost: string[] };
+/** Commit a system into tokens.json; the record keeps the document without brand images. */
+export function applySystem(tokens: TokensJson, system: HalftoneSystemInput | HalftoneSystem): { tokens: TokensJson; theme: Theme; system: HalftoneSystem };

package/lib/system/index.mjs

@@ -0,0 +1,33 @@
+/**
+ * @halftone-ds/tokens/system — the HalftoneSystem document: one design system (a recipe plus everything edited
+ * by hand on top of it), as the Studio keeps it and `halftone-tokens theme apply ./name.halftone.json` commits it.
+ * Pure ESM with no Node APIs. See schema.mjs for the shape.
+ */
+export {
+  BORDER_STYLES,
+  COLOR_ROLES,
+  createSystem,
+  EXTRA_KINDS,
+  extraNameProblem,
+  FONT_ROLES,
+  hasOverrides,
+  isSystem,
+  newSystemId,
+  normalizeSystem,
+  RADIUS_STEPS,
+  ROLE_NAMES,
+  SHADOW_LEVELS,
+  STATUS_ROLES,
+  SYSTEM_KIND,
+  SYSTEM_VERSION,
+  SystemError,
+  systemOverrides,
+  TEXT_DEFAULTS,
+  TEXT_KEYS,
+  TEXT_STYLES,
+  validateSystem,
+  withoutBrandImages,
+} from './schema.mjs';
+export { generateSystem, systemCode, systemRadii, systemRamps, textStyles } from './generate.mjs';
+export { migrate, systemToRecipe } from './migrate.mjs';
+export { applySystem } from '../theme/apply.mjs';

package/lib/system/migrate.mjs

@@ -0,0 +1,38 @@
+/**
+ * migrate — a HalftoneSystem from what came before it: a theme recipe (or its ht- code) and the Studio's brand.
+ * A document already is cleaned up and brought to the current version. Pure ESM.
+ *
+ *   migrate(recipe | code | system, brand?, { id?, name?, updatedAt? })  → HalftoneSystem
+ *   systemToRecipe(system)  → { recipe, code, lost }: the other way; `lost` lists the overrides a recipe can't
+ *                             hold (code is null when there are any)
+ *
+ * A recipe migrates to a system with no overrides, so it round-trips: systemToRecipe(migrate(r)).recipe is r, and
+ * generateSystem(migrate(r), base) is generateTheme(r, base).
+ */
+import { decodeRecipe, encodeRecipe, isThemeCode } from '../theme/codec.mjs';
+import { presetById } from '../theme/presets.mjs';
+import { normalizeRecipe } from '../theme/recipe.mjs';
+import { isSystem, newSystemId, normalizeSystem, systemOverrides } from './schema.mjs';
+
+export function migrate(input, brand, { id, name, updatedAt } = {}) {
+  if (isSystem(input)) {
+    const doc = normalizeSystem(input);
+    return { ...doc, ...(id ? { id } : {}), ...(name ? { name } : {}), ...(updatedAt ? { updatedAt } : {}), ...(brand ? { brand: normalizeSystem({ brand }).brand } : {}) };
+  }
+  const recipe = typeof input === 'string' && isThemeCode(input) ? decodeRecipe(input) : normalizeRecipe(input ?? {});
+  const preset = recipe.preset ? presetById(recipe.preset) : undefined;
+  return normalizeSystem({
+    id: id ?? newSystemId(),
+    name: name ?? (brand?.name?.trim() || preset?.name || 'My system'),
+    ...(recipe.preset ? { preset: recipe.preset } : {}),
+    updatedAt: updatedAt ?? new Date().toISOString(),
+    recipe,
+    ...(brand ? { brand } : {}),
+  });
+}
+
+export function systemToRecipe(input) {
+  const doc = normalizeSystem(input);
+  const lost = systemOverrides(doc);
+  return { recipe: doc.recipe, code: lost.length ? null : encodeRecipe(doc.recipe), lost };
+}