@halftone-ds/tokens 1.1.0 → 1.3.0

package/lib/theme/apply.mjs

@@ -3,8 +3,17 @@
  * (status ramps, spacing, type sizes, motion, descriptions) is left exactly as it was. The recipe is
  * recorded under `$extensions["com.halftonedesignsystem.theme"]`, so the docs picker and `halftone-tokens theme show`
  * can tell which theme is applied, and whether anyone has hand-edited it since (drift).
+ *
+ * A system document (lib/system) is applied the same way (applySystem): the record keeps the document too,
+ * without its brand images. A system owns more than a recipe: edited text styles (semantic.type.<style>),
+ * corner overrides (semantic.radius.<step>), a border style, status ramps from its own seeds, and its extras
+ * (the `extra` group), and component edits (semantic.component.<name>, which every theme writes). What the previous theme owned and the new one doesn't is removed, and a status ramp it
+ * had replaced goes back to the curated one (red, green, amber, sky).
  */
+import { generateSystem, systemCode } from '../system/generate.mjs';
+import { normalizeSystem, withoutBrandImages } from '../system/schema.mjs';
 import { generateTheme } from './generate.mjs';
+import { BRAND_RAMPS } from './palettes.mjs';
 import { normalizeRecipe } from './recipe.mjs';
 import { flatten } from './refs.mjs';
 
@@ -12,6 +21,12 @@ export const THEME_EXTENSION = 'com.halftonedesignsystem.theme';
 
 const clone = (value) => JSON.parse(JSON.stringify(value));
 
+/** The status ramps the kits ship, which a system's own status seed replaces until it is removed. */
+const STATUS_RAMPS = { danger: BRAND_RAMPS.red, success: BRAND_RAMPS.green, warning: BRAND_RAMPS.amber, info: BRAND_RAMPS.sky };
+
+/** A DTCG group as { 'prefix.path': $value }. */
+const flatValues = (group, prefix) => Object.fromEntries(flatten(group).map((t) => [[prefix, ...t.path].join('.'), t.$value]));
+
 /** The values a theme owns, as { 'path.to.token': $value }. */
 function ownedValues(theme) {
   const out = {};
@@ -19,9 +34,10 @@ function ownedValues(theme) {
     for (const [step, hex] of Object.entries(ramp)) out[`primitive.color.${group}.${step}`] = hex;
   }
   for (const [name, value] of Object.entries(theme.semantic.color)) out[`semantic.color.${name}`] = value;
-  out['semantic.radius.base'] = theme.semantic.radius.base;
-  out['semantic.radius.control'] = theme.semantic.radius.control;
-  out['semantic.border.width'] = theme.semantic.border.width;
+  // base and control, and a system's corners (sm…2xl).
+  for (const [key, value] of Object.entries(theme.semantic.radius)) out[`semantic.radius.${key}`] = value;
+  // width, and a system's style.
+  for (const [key, value] of Object.entries(theme.semantic.border)) out[`semantic.border.${key}`] = value;
   out['semantic.icon.stroke'] = theme.semantic.icon.stroke;
   for (const [level, value] of Object.entries(theme.semantic.shadow)) out[`semantic.shadow.${level}`] = value;
   out['semantic.density.scale'] = theme.semantic.density.scale;
@@ -29,11 +45,27 @@ function ownedValues(theme) {
   out['primitive.font.family.heading'] = theme.fonts.heading;
   out['primitive.font.family.body'] = theme.fonts.body;
   out['primitive.font.family.mono'] = theme.fonts.mono;
-  for (const [key, value] of Object.entries(theme.semantic.type)) out[`semantic.type.${key}`] = value;
+  for (const [key, value] of Object.entries(theme.semantic.type)) {
+    // The typeset's numbers, and a system's text styles ({ size, leading, weight, tracking, font }).
+    if (value && typeof value === 'object') for (const [k, v] of Object.entries(value)) out[`semantic.type.${key}.${k}`] = v;
+    else out[`semantic.type.${key}`] = value;
+  }
+  // The component layer (Button, Chip, Badge, Input): leaves are numbers, references, or { light, dark }.
+  const walk = (node, path) => {
+    for (const [key, value] of Object.entries(node)) {
+      if (value && typeof value === 'object' && !('light' in value && 'dark' in value)) walk(value, `${path}.${key}`);
+      else out[`${path}.${key}`] = value;
+    }
+  };
+  walk(theme.semantic.component, 'semantic.component');
+  if (theme.extra) Object.assign(out, flatValues(theme.extra, 'extra'));
   return out;
 }
 
-const TYPES = { radius: 'number', border: 'number', icon: 'number', density: 'number', type: 'number', shadow: 'shadow', font: 'fontFamily', color: 'color' };
+/** The `$type` of each token an `extra` group holds, by path. */
+const extraTypes = (theme) => Object.fromEntries(flatten(theme.extra ?? {}).map((t) => [['extra', ...t.path].join('.'), t.$type]));
+
+const TYPES = { radius: 'number', border: 'number', icon: 'number', density: 'number', type: 'number', button: 'number', field: 'number', shadow: 'shadow', font: 'fontFamily', color: 'color' };
 const DESCRIPTIONS = {
   'semantic.radius.control': 'Corner radius of mobile buttons and chips: rounded-control. 9999 = pills; otherwise the base radius.',
   'semantic.border.width': 'Width of `border` (px). border-2 and border-hairline stay explicit.',
@@ -53,48 +85,191 @@ const DESCRIPTIONS = {
   'semantic.type.leading': "Typeset: line height of running text (× size); the text sizes' line heights scale by leading / 1.75.",
   'semantic.type.flow': 'Typeset: space between blocks of long-form text (Prose), em.',
   'semantic.type.measure': 'Typeset: the longest line of long-form text (Prose), characters.',
+  'semantic.color.button': 'The primary button: bg-button (its alpha is component.button.alpha). Follows the theme\'s button style.',
+  'semantic.color.button-foreground': 'Text and icons on the primary button: text-button-foreground.',
+  'semantic.color.button-edge': 'The primary button\'s border and bottom edge: border-button-edge.',
+  'semantic.color.field': 'Text fields: bg-field (its alpha is component.input.alpha). Follows the theme\'s field style.',
+  'semantic.color.field-edge': 'Text fields\' border or bottom line: border-field-edge.',
 };
 
 function typeOf(path) {
-  return TYPES[path.split('.')[1]] ?? 'color';
+  const parts = path.split('.');
+  if (parts[0] === 'semantic' && parts[1] === 'type' && parts.length === 4) return { font: 'fontFamily', weight: 'fontWeight' }[parts[3]] ?? 'number';
+  if (path === 'semantic.border.style') return 'strokeStyle';
+  if (parts[1] === 'component') return COLOR_SLOTS.has(parts.at(-1)) ? 'color' : parts.at(-1) === 'font' ? 'fontFamily' : 'number';
+  return TYPES[parts[1]] ?? 'color';
 }
 
-function setPath(root, path, $value) {
+const COLOR_SLOTS = new Set(['fill', 'label', 'border', 'pressed', 'ring']);
+/** What a component token is, for its $description (semantic.component.<name>.…). */
+const COMPONENT_DESCRIPTION = {
+  radius: 'corner radius (px; 9999 = a pill)',
+  'radius-bottom': 'bottom corner radius (px)',
+  'height.sm': 'small height (px; phones raise a touch target under 44 to 44)',
+  'height.md': 'height (px; phones raise a touch target under 44 to 44)',
+  'height.lg': 'large height (px)',
+  'x.sm': 'small horizontal padding (px)',
+  'x.md': 'horizontal padding (px)',
+  'x.lg': 'large horizontal padding (px)',
+  'text.size': 'text size (px), from its text style',
+  'text.leading': 'line height (px), fitted to the control',
+  'text.tracking': 'letter spacing (em)',
+  'text.font': "the text style's font",
+  fill: 'fill colour (a role)',
+  'fill-alpha': 'fill opacity',
+  label: 'label colour (a role)',
+  border: 'border colour (a role)',
+  'border-alpha': 'border opacity',
+  'border-width': 'border width (px)',
+  'edge-width': 'bottom edge width (px)',
+  pressed: 'pressed and hover fill (derived from the fill unless set)',
+  'pressed-alpha': 'pressed and hover opacity',
+  ring: 'focus ring colour (the border, faded)',
+  'ring-alpha': 'focus ring opacity',
+  alpha: "the style's fill opacity",
+  round: '1 = rounded top corners, 0 = square',
+  'round-bottom': '1 = rounded bottom corners, 0 = square',
+  inset: '1 = inner padding, 0 = flush',
+};
+
+const TEXT_DESCRIPTION = {
+  size: 'size (px)',
+  leading: 'line height (× size)',
+  weight: 'font weight',
+  tracking: 'letter spacing (em)',
+  font: 'font family (a role: heading, body or mono)',
+};
+function describe(path) {
+  if (DESCRIPTIONS[path]) return DESCRIPTIONS[path];
+  const parts = path.split('.');
+  if (parts[1] === 'type' && parts.length === 4) return `Text ${parts[2]}: ${TEXT_DESCRIPTION[parts[3]] ?? parts[3]}. Edited in the system.`;
+  if (parts[1] === 'radius' && parts.length === 3) return `rounded-${parts[2]} (px), edited in the system; otherwise a multiple of the base radius.`;
+  if (path === 'semantic.border.style') return 'Border style: solid, dashed or dotted.';
+  if (parts[1] === 'component') {
+    const [name, ...rest] = parts.slice(2);
+    const key = rest.join('.');
+    const label = { button: 'Button', chip: 'Chip', badge: 'Badge', input: 'Input' }[name] ?? name;
+    if (COMPONENT_DESCRIPTION[key]) return `${label}: ${COMPONENT_DESCRIPTION[key]}.`;
+    if (rest.length === 2 && COMPONENT_DESCRIPTION[rest[1]]) return `${label} ${rest[0]}: ${COMPONENT_DESCRIPTION[rest[1]]}.`;
+  }
+  return undefined;
+}
+
+function setPath(root, path, $value, $type = typeOf(path)) {
   let node = root;
   const keys = path.split('.');
   for (const key of keys.slice(0, -1)) node = node[key] ??= {};
   const leaf = keys.at(-1);
   if (node[leaf] && typeof node[leaf] === 'object' && '$value' in node[leaf]) node[leaf].$value = $value;
-  else node[leaf] = { $type: typeOf(path), ...(DESCRIPTIONS[path] ? { $description: DESCRIPTIONS[path] } : {}), $value };
+  else {
+    const $description = describe(path);
+    node[leaf] = { $type, ...($description ? { $description } : {}), $value };
+  }
 }
 
-/** → { tokens, theme }. `tokens` is a new object; the input is not touched. */
-export function applyRecipe(tokens, recipe) {
-  const theme = generateTheme(recipe, tokens);
+/** Remove a token, and any group it leaves empty. */
+function deletePath(root, path) {
+  const keys = path.split('.');
+  const chain = [root];
+  for (const key of keys.slice(0, -1)) {
+    const next = chain.at(-1)[key];
+    if (!next || typeof next !== 'object') return;
+    chain.push(next);
+  }
+  delete chain.at(-1)[keys.at(-1)];
+  for (let i = chain.length - 1; i > 0; i--) {
+    if (Object.keys(chain[i]).some((k) => !k.startsWith('$'))) break;
+    delete chain[i - 1][keys[i - 1]];
+  }
+}
+
+/** The theme a tokens.json's record describes, generated on that file (null when there is none). */
+function recordedTheme(tokens) {
+  const record = tokens.$extensions?.[THEME_EXTENSION];
+  if (record?.system) return generateSystem(record.system, tokens);
+  if (record?.recipe) return generateTheme(record.recipe, tokens);
+  return null;
+}
+
+/** What the recorded theme owns, or nothing when this version can't read the record (a newer one wrote it). */
+function previouslyOwned(tokens) {
+  try {
+    const previous = recordedTheme(tokens);
+    return previous ? ownedValues(previous) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The file a new theme is generated on: the status ramps the recorded system replaced go back to the curated
+ * ones first, so a new system builds on those (a seed regenerates its ramp anyway), and the new theme's colours
+ * are fixed against the ramps it will ship with.
+ */
+function prepare(tokens) {
   const out = clone(tokens);
-  for (const [path, value] of Object.entries(ownedValues(theme))) {
-    setPath(out, path, value);
+  for (const path of Object.keys(previouslyOwned(tokens))) {
+    const [, , ramp, step] = path.split('.');
+    if (path.startsWith('primitive.color.') && STATUS_RAMPS[ramp]?.[step]) setPath(out, path, STATUS_RAMPS[ramp][step]);
   }
+  return out;
+}
+
+/** Write a theme's values, drop what the previous theme owned and this one doesn't, and record it. */
+function commit(tokens, theme, record) {
+  const out = clone(tokens);
+  const owned = ownedValues(theme);
+  // Status ramps went back in prepare(); everything else the new theme doesn't own goes.
+  for (const path of Object.keys(previouslyOwned(tokens))) if (!(path in owned) && !path.startsWith('primitive.color.')) deletePath(out, path);
+  const types = extraTypes(theme);
+  for (const [path, value] of Object.entries(owned)) setPath(out, path, value, types[path]);
   const { $extensions = {}, ...rest } = out;
-  const record = { version: theme.recipe.v, code: theme.code, recipe: theme.recipe };
   if (theme.adjustments.length) record.adjustments = theme.adjustments;
-  return { tokens: { ...rest, $extensions: { ...$extensions, [THEME_EXTENSION]: record } }, theme };
+  if (theme.warnings?.length) record.warnings = theme.warnings;
+  return { ...rest, $extensions: { ...$extensions, [THEME_EXTENSION]: record } };
+}
+
+/** → { tokens, theme }. `tokens` is a new object; the input is not touched. */
+export function applyRecipe(tokens, recipe) {
+  const base = prepare(tokens);
+  const theme = generateTheme(recipe, base);
+  const record = { version: theme.recipe.v, code: theme.code, recipe: theme.recipe };
+  return { tokens: commit(base, theme, record), theme };
+}
+
+/**
+ * A system document into tokens.json → { tokens, theme, system }. The record keeps the document without its
+ * brand images, and the code only when the system has no overrides (a code can't carry them).
+ */
+export function applySystem(tokens, input) {
+  const system = normalizeSystem(input);
+  const base = prepare(tokens);
+  const theme = generateSystem(system, base);
+  const code = systemCode(system);
+  const record = { version: theme.recipe.v, ...(code ? { code } : {}), recipe: theme.recipe, system: withoutBrandImages(system) };
+  return { tokens: commit(base, theme, record), theme, system };
 }
 
 /**
  * What theme a tokens.json carries:
  *   { applied: false }                               no theme recorded
  *   { applied: true, code, recipe, drift: [paths] }  drift = owned paths edited since the theme was applied
+ *   … system                                         when a system document was applied; code is null when
+ *                                                    the system has overrides (no code reproduces it)
  */
 export function themeStatus(tokens) {
   const record = tokens.$extensions?.[THEME_EXTENSION];
   if (!record?.recipe) return { applied: false };
-  const expected = ownedValues(generateTheme(record.recipe, tokens));
+  const expected = ownedValues(recordedTheme(tokens));
   const actual = Object.fromEntries(flatten(tokens).map((t) => [t.path.join('.'), t.$value]));
   // A path the file doesn't have yet (a newer halftone-tokens owns more) is not an edit; apply adds it.
   const drift = Object.entries(expected)
     .filter(([path, value]) => path in actual && JSON.stringify(actual[path]) !== JSON.stringify(value))
     .map(([path]) => path);
   // Normalised: a recipe recorded by an older halftone-tokens gets the axes it didn't have (the typeset).
+  if (record.system) {
+    const system = normalizeSystem(record.system);
+    return { applied: true, code: systemCode(system), recipe: system.recipe, system, drift };
+  }
   return { applied: true, code: record.code, recipe: normalizeRecipe(record.recipe), drift };
 }

package/lib/theme/codec.mjs

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