@halftone-ds/tokens 1.2.0 → 1.3.0

package/lib/theme/recipe.mjs

@@ -104,6 +104,74 @@ export const typeScale = ({ size, leading, flow, measure }) => ({
 });
 
 
+/** The Text variants both kits draw (components/ui/text.tsx on mobile; the type-* utilities on the web). */
+export const TEXT_STYLES = ['h1', 'h2', 'h3', 'h4', 'lead', 'p', 'large', 'small', 'muted', 'code', 'blockquote'];
+
+/**
+ * The text styles as the kits draw them at the default typeset (16px, leading 1.75), from the mobile kit's
+ * components/ui/text.tsx and Tailwind's sizes: size px, leading × size, tracking em. `leading: 'prose'` is the typeset's own leading
+ * (Text p's leading-prose); every other leading scales with the typeset's (leading / 1.75), and sizes with
+ * size / 16. `small` is leading-none, which never scales.
+ */
+export const TEXT_DEFAULTS = {
+  h1: { font: 'heading', weight: 800, size: 36, leading: 40 / 36, tracking: -0.025 },
+  h2: { font: 'heading', weight: 600, size: 30, leading: 36 / 30, tracking: -0.025 },
+  h3: { font: 'heading', weight: 600, size: 24, leading: 32 / 24, tracking: -0.025 },
+  h4: { font: 'heading', weight: 600, size: 20, leading: 28 / 20, tracking: -0.025 },
+  lead: { font: 'body', weight: 400, size: 20, leading: 28 / 20, tracking: 0 },
+  p: { font: 'body', weight: 400, size: 16, leading: 'prose', tracking: 0 },
+  large: { font: 'body', weight: 600, size: 18, leading: 28 / 18, tracking: 0 },
+  small: { font: 'body', weight: 500, size: 14, leading: 1, tracking: 0 },
+  muted: { font: 'body', weight: 400, size: 14, leading: 20 / 14, tracking: 0 },
+  code: { font: 'mono', weight: 600, size: 14, leading: 20 / 14, tracking: 0 },
+  blockquote: { font: 'body', weight: 400, size: 16, leading: 24 / 16, tracking: 0 },
+};
+
+const FONT_REF = /^\{primitive\.font\.family\.(heading|body|mono)\}$/;
+
+/**
+ * A system's edited text styles from a semantic.type group: a theme's ({ h1: { size, … } }) or a token file's
+ * DTCG one ({ h1: { size: { $value } } }). The font is a reference to a role's family; a style's other keys
+ * are numbers. The typeset's own numbers (size, leading, flow, measure) are skipped.
+ *   → { h1: { size, leading, weight, tracking, font: 'heading' } }
+ */
+export function textEdits(group = {}) {
+  const out = {};
+  for (const name of TEXT_STYLES) {
+    const style = group?.[name];
+    if (!style || typeof style !== 'object' || '$value' in style) continue;
+    const value = (v) => (v && typeof v === 'object' && '$value' in v ? v.$value : v);
+    const edit = {};
+    for (const key of ['size', 'leading', 'weight', 'tracking']) if (typeof value(style[key]) === 'number') edit[key] = value(style[key]);
+    const font = FONT_REF.exec(String(value(style.font) ?? ''));
+    if (font) edit.font = font[1];
+    out[name] = edit;
+  }
+  return out;
+}
+
+/**
+ * Every text style as drawn at a typeset (typeScale), edits on top, unrounded:
+ *   { h1: { font, weight, size: px, leading: × size, tracking: em, lineHeight: px, edited: bool } }
+ * Sizes scale by the typeset's size / 16 and line heights by its leading / 1.75; Text p takes the typeset's
+ * leading itself and Text small (leading-none) never scales. With no edits this is exactly what the kits drew
+ * with Tailwind's text-* classes.
+ */
+export function resolveTextStyles(type, edits = {}) {
+  return Object.fromEntries(
+    TEXT_STYLES.map((name) => {
+      const d = TEXT_DEFAULTS[name];
+      const leading = d.leading === 'prose' ? type.leading : d.leading === 1 ? 1 : d.leading * type.leadingFactor;
+      const edit = edits[name] ?? {};
+      const style = { font: d.font, weight: d.weight, size: d.size * type.scale, leading, tracking: d.tracking, ...edit, edited: Object.keys(edit).length > 0 };
+      // The line height in px, multiplied in the order the text-* classes always were (so it rounds the same).
+      const px = Math.round(d.size * (d.leading === 'prose' ? 1 : d.leading) * 1e6) / 1e6;
+      style.lineHeight = 'size' in edit || 'leading' in edit ? style.size * style.leading : d.leading === 'prose' ? px * type.scale * type.leading : d.leading === 1 ? style.size : px * type.scale * type.leadingFactor;
+      return [name, style];
+    })
+  );
+}
+
 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,

package/lib/theme/semantic.mjs

@@ -13,8 +13,18 @@ const p = (ramp, step) => `{primitive.color.${ramp}.${step}}`;
 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') {
+/**
+ * The status tones' steps, as offsets from the step their seed sits on (600 for the curated ramps the kits
+ * ship), light and dark: a status seed that lands on another step moves its tone with it, as the brand does.
+ */
+const STATUS_STEPS = { danger: [0, -1], success: [1, -1], warning: [1, -2], info: [1, -1] };
+const status = (ramp, anchor = '600') => ({ light: p(ramp, shift(anchor, STATUS_STEPS[ramp][0])), dark: p(ramp, shift(anchor, STATUS_STEPS[ramp][1])) });
+
+/**
+ * { name: { light: ref, dark: ref } } in the order the kit's tokens.json lists them. `anchors` holds the step
+ * each status seed sits on (`{ danger: '500' }`); a status without one uses its 600, the curated ramps' seed.
+ */
+export function semanticColors(anchor = '600', anchors = {}) {
   const brand = { light: b(anchor), dark: b(darkStep(anchor)) };
   const onDark = { light: n(0), dark: n(950) };
   return {
@@ -32,13 +42,13 @@ export function semanticColors(anchor = '600') {
     '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: status('danger', anchors.danger),
     'destructive-foreground': onDark,
-    success: { light: p('success', 700), dark: p('success', 500) },
+    success: status('success', anchors.success),
     'success-foreground': onDark,
-    warning: { light: p('warning', 700), dark: p('warning', 400) },
+    warning: status('warning', anchors.warning),
     'warning-foreground': onDark,
-    info: { light: p('info', 700), dark: p('info', 500) },
+    info: status('info', anchors.info),
     'info-foreground': onDark,
     border: { light: n(200), dark: n(800) },
     input: { light: n(200), dark: n(800) },
@@ -59,7 +69,9 @@ export function semanticColors(anchor = '600') {
   };
 }
 
-const shift = (step, by) => STEPS[Math.min(STEPS.length - 1, Math.max(0, STEPS.indexOf(step) + by))];
+function shift(step, by) {
+  return STEPS[Math.min(STEPS.length - 1, Math.max(0, STEPS.indexOf(step) + by))];
+}
 
 /**
  * The colours a recipe's styles add (button, field), from the base colours after their contrast fix, so a moved

package/lib/theme/shadcn.mjs

@@ -247,7 +247,7 @@ export function shadcnTheme(theme, { name, title: label, description, fontsUrl =
     $schema: 'https://ui.shadcn.com/schema/registry-item.json',
     name: name ?? `halftone-${theme.code}`,
     title: label ?? `Halftone theme ${theme.code}`,
-    description: description ?? `A Halftone theme (${theme.code}): colours for light and dark, radius, shadows and fonts. halftonedesignsystem.com/themes/?t=${theme.code}`,
+    description: description ?? `A Halftone theme (${theme.code}): colours for light and dark, radius, shadows and fonts. halftonedesignsystem.com/studio/?t=${theme.code}`,
     type: 'registry:theme',
     ...(dependencies.length ? { registryDependencies: dependencies } : {}),
     cssVars: {

package/lib/theme/vars.mjs

@@ -5,7 +5,9 @@
  *   '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';
+import { componentVars } from './components.mjs';
+import { extraList, extraTextStyles } from './extras.mjs';
+import { resolveTextStyles, shadowCss, textEdits } from './recipe.mjs';
 
 export const rem = (px) => (px >= 9999 ? '9999px' : `${px / 16}rem`);
 
@@ -20,10 +22,40 @@ export const typeVars = (type) => ({
   '--typeset-measure': `${type.measure}ch`,
 });
 
+const fixed = (n, places = 4) => Number(n.toFixed(places));
+
+/** A theme's text styles as drawn (recipe.mjs resolveTextStyles): its typeset, its edited styles on top. */
+export const themeTextStyles = (theme) => resolveTextStyles(theme.type, textEdits(theme.semantic?.type));
+
+/**
+ * The text styles' variables, --type-<style>-{size,leading,weight,tracking,font}, from resolveTextStyles. Literal
+ * values at the theme's typeset, in each kit's units:
+ *   'hsl'    mobile (NativeWind): size and line height in rem (native line heights are lengths); the font is
+ *            the role, which components/ui/text.tsx picks in JS, so no variable. Tracking is em on native too:
+ *            NativeWind resolves it against the style's own size (its preset's tracking-* are fixed px instead)
+ *   'oklch'  web: rem and a unitless line height; the font is the role's family variable. `font(role)` writes
+ *            it (the build adds fallbacks; a live theme always sets --kit-font-*)
+ */
+export function textStyleVars(styles, format, font = (role) => `var(--kit-font-${role})`) {
+  const vars = {};
+  // Mobile rounds rem to 4 places, as nativewind3's text-* sizes always were.
+  const length = (px) => (format === 'hsl' ? `${fixed(px / 16)}rem` : rem(fixed(px)));
+  for (const [name, s] of Object.entries(styles)) {
+    const v = `--type-${name}`;
+    vars[`${v}-size`] = length(s.size);
+    vars[`${v}-leading`] = format === 'hsl' ? length(s.lineHeight ?? s.size * s.leading) : String(fixed(s.leading, 6));
+    vars[`${v}-weight`] = String(s.weight);
+    vars[`${v}-tracking`] = `${s.tracking}em`;
+    if (format !== 'hsl') vars[`${v}-font`] = font(s.font);
+  }
+  return vars;
+}
+
 /**
  * The button and field styles' variables (both formats), from a theme's or a token file's { button, field }
- * (generate.mjs, resolve.mjs). Widths and radii are numbers on the light block; the field's fill opacity is
- * per mode. A field's inner padding is the kit's own: 1rem on mobile (hsl), px-3 on the web (oklch).
+ * (generate.mjs, resolve.mjs). Widths are numbers on the light block; the field's fill opacity is per mode. A
+ * field's corners and padding are the component layer's (componentVars: --field-radius, --field-radius-b,
+ * --field-x).
  */
 export function styleVars({ button, field }, format) {
   return {
@@ -34,9 +66,6 @@ export function styleVars({ button, field }, format) {
       '--field-alpha': String(field.alpha.light),
       '--field-border-w': `${field.border}px`,
       '--field-edge-w': `${field.edge}px`,
-      '--field-radius': rem(field.radius),
-      '--field-radius-b': rem(field.radiusBottom),
-      '--field-x': field.inset ? (format === 'hsl' ? '1rem' : 'calc(var(--spacing) * 3)') : '0px',
       // Web: a boxed field keeps shadcn's shadow-xs; a filled or underline field has none.
       ...(format === 'hsl' ? {} : { '--field-shadow': field.border ? 'var(--shadow-1)' : '0 0 #0000' }),
     },
@@ -44,7 +73,29 @@ export function styleVars({ button, field }, format) {
   };
 }
 
-/** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } */
+/**
+ * A system's extras as variables (lib/theme/extras.mjs): --<colour> (a ramp's --<name>-<step>), --radius-<name>,
+ * --shadow-<name> per mode, --border-<name>-width and --type-<name>-*. `font` as textStyleVars takes it.
+ */
+export function extraVars(list, format, font) {
+  const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
+  const light = {};
+  const dark = {};
+  for (const c of list.color) {
+    light[`--${c.name}`] = convert(c.light);
+    dark[`--${c.name}`] = convert(c.dark);
+  }
+  for (const r of list.radius) light[`--radius-${r.name}`] = rem(r.px);
+  for (const s of list.shadow) {
+    light[`--shadow-${s.name}`] = shadowCss(s.light);
+    dark[`--shadow-${s.name}`] = shadowCss(s.dark);
+  }
+  for (const b of list.border) light[`--border-${b.name}-width`] = `${b.width}px`;
+  Object.assign(light, textStyleVars(extraTextStyles(list), format, font));
+  return { light, dark };
+}
+
+/** { light: { '--primary': '…', '--radius': '0.625rem' }, dark: { … } } (a system's extras too) */
 export function themeVars(theme, format) {
   const convert = format === 'hsl' ? hexToHslTriplet : hexToOklch;
   const mode = (m) => {
@@ -56,10 +107,12 @@ export function themeVars(theme, format) {
       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));
+      Object.assign(vars, typeVars(theme.type), textStyleVars(themeTextStyles(theme), format));
     }
     Object.assign(vars, styleVars(theme, format)[m]);
+    if (theme.components) Object.assign(vars, componentVars(theme.components, format, convert)[m]);
     for (const [level, value] of Object.entries(theme.semantic.shadow)) vars[`--shadow-${level}`] = shadowCss(value[m]);
+    if (theme.extra) Object.assign(vars, extraVars(extraList(theme.extra), format)[m]);
     return vars;
   };
   return { light: mode('light'), dark: mode('dark') };

package/lib/theme-cli.mjs

@@ -2,7 +2,8 @@
  * `halftone-tokens theme …` — commit a theme from the docs picker into tokens.json.
  *
  *   theme apply <theme> [--dry-run] [--force]
- *        write the theme into tokens.json (only the paths a theme owns) and rebuild
+ *        write the theme into tokens.json (only the paths a theme owns) and rebuild; a system document is
+ *        recorded in tokens.json's $extensions (without its brand images)
  *   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
@@ -12,19 +13,22 @@
  *   theme shadcn <theme> [--out file] [--fonts-url url]
  *                          the theme as a shadcn registry:theme item (stdout, or a file), for `npx shadcn add`
  *
- * <theme> is a Halftone code (ht1-…, ht2-…, ht3-…), a preset name, a recipe .json, or a shadcn/ui preset code
- * (ui.shadcn.com/create, e.g. b5owWMfJ8l), which becomes the nearest Halftone recipe: what it approximates
- * or drops is listed on stderr.
+ * <theme> is a Halftone code (ht1-…, ht2-…, ht3-…), a preset name, a recipe .json, a system document
+ * (name.halftone.json, from the Studio), or a shadcn/ui preset code (ui.shadcn.com/create, e.g. b5owWMfJ8l),
+ * which becomes the nearest Halftone recipe: what it approximates or drops is listed on stderr.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 
 import { cvdWarnings, describeCvdWarnings, MIN_DELTA_E } from './cvd.mjs';
-import { FONTS } from './theme/fonts.mjs';
+import { FONTS, fontByFamily } from './theme/fonts.mjs';
+import { isSystem, normalizeSystem, SystemError, systemOverrides } from './system/schema.mjs';
+import { systemCode } from './system/generate.mjs';
 
 import {
   applyRecipe,
+  applySystem,
   decodeRecipe,
   encodeRecipe,
   fontById,
@@ -37,6 +41,7 @@ import {
   recipeFromShadcn,
   SHADCN_FONTS_URL,
   shadcnTheme,
+  THEME_EXTENSION,
   themeStatus,
 } from './theme/index.mjs';
 
@@ -51,8 +56,55 @@ function printNotes(code, notes) {
   console.error(`From shadcn preset ${code}, approximated or not carried:\n${notes.map((n) => `  - ${n}`).join('\n')}`);
 }
 
+/** { recipe, system? }: a system document when <theme> is one (name.halftone.json), else a recipe. */
+function readTheme(arg, root) {
+  // resolve: an absolute path stays itself (join would put it under root).
+  const file = arg ? resolve(root, arg) : '';
+  if (arg?.endsWith('.json') && existsSync(file)) {
+    let json;
+    try {
+      json = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (error) {
+      fail(`${arg} is not valid JSON: ${error.message}`);
+    }
+    if (isSystem(json)) {
+      try {
+        const system = normalizeSystem(json);
+        return { recipe: system.recipe, system };
+      } catch (error) {
+        if (error instanceof SystemError) fail(`${arg}: ${error.message}`);
+        throw error;
+      }
+    }
+  }
+  return { recipe: readRecipe(arg, root) };
+}
+
+/** Why a system has no code: its overrides, briefly. */
+function noCode(system) {
+  const overrides = systemOverrides(system);
+  const shown = overrides.slice(0, 6).join(', ') + (overrides.length > 6 ? `, and ${overrides.length - 6} more` : '');
+  return `"${system.name}" has ${overrides.length} override(s) a theme code can't carry (${shown}). Share its .halftone.json instead.`;
+}
+
+/** A system's overrides, grouped by section, for `show` and `apply`. */
+function describeOverrides(system) {
+  const bySection = {};
+  for (const path of systemOverrides(system)) {
+    const [section, ...rest] = path.split('.');
+    (bySection[section] ??= []).push(rest.join('.'));
+  }
+  return Object.entries(bySection).map(([section, list]) => `${section}: ${list.join(', ')}`);
+}
+
+function printWarnings(warnings) {
+  if (!warnings?.length) return;
+  console.log(`\nBelow WCAG AA because of colours chosen by hand (warnings; the fixer leaves hand-picked colours alone):`);
+  for (const w of warnings) console.log(`  ${w.mode.padEnd(5)} ${w.label.padEnd(40)} ${w.ratio}:1 (needs ${w.threshold})${w.locked.length ? `  · chosen: ${w.locked.join(', ')}` : ''}`);
+}
+
 function readRecipe(arg, root) {
-  if (!arg) fail('say which theme: a code (ht1-…, ht2-… or ht3-…), a preset name, a recipe .json or a shadcn preset code', 2);
+  if (!arg) fail('say which theme: a code (ht1-…, ht2-… or ht3-…), a preset name, a recipe .json, a system .halftone.json or a shadcn preset code', 2);
   if (isThemeCode(arg)) {
     try {
       return decodeRecipe(arg);
@@ -62,7 +114,7 @@ function readRecipe(arg, root) {
   }
   const preset = presetById(arg.toLowerCase());
   if (preset) return normalizeRecipe({ ...preset.recipe, preset: preset.id });
-  const file = join(root, arg);
+  const file = resolve(root, arg);
   if (arg.endsWith('.json') && existsSync(file)) return normalizeRecipe(JSON.parse(readFileSync(file, 'utf8')));
   // Last, so a preset name that happens to look like one (bold, brutalist) stays Halftone's preset.
   const shadcn = isShadcnPresetCode(arg) ? decodeShadcnPreset(arg) : null;
@@ -98,7 +150,8 @@ 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);
+  // The theme's families: curated ones, or any Google Fonts family a system names.
+  const ids = Object.values(theme.fonts).filter(Boolean).map(fontByFamily).filter((f) => !f.system).map((f) => f.id);
   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));
@@ -124,7 +177,9 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   }
 
   if (sub === 'encode') {
-    console.log(encodeRecipe(readRecipe(arg, root)));
+    const { recipe, system } = readTheme(arg, root);
+    if (system && !systemCode(system)) fail(noCode(system));
+    console.log(encodeRecipe(recipe));
     return;
   }
 
@@ -166,6 +221,7 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   if (sub === 'resolve') {
     const status = themeStatus(tokens());
     if (!status.applied) fail('no theme recorded in tokens.json, so there is no code for it. Apply one with `halftone-tokens theme apply <theme>`.');
+    if (!status.code) fail(`the applied system ${noCode(status.system)} Its document is recorded in tokens.json ($extensions).`);
     if (status.drift.length) fail(`tokens.json was edited by hand since ${status.code} was applied (${status.drift.length} token(s)); no code reproduces it. \`theme show\` lists them.`);
     if (flags.json) console.log(JSON.stringify({ code: status.code, recipe: status.recipe }, null, 2));
     else console.log(status.code);
@@ -173,8 +229,8 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   }
 
   if (sub === 'shadcn') {
-    const recipe = readRecipe(arg, root);
-    const { theme } = applyRecipe(tokens(), recipe);
+    const { recipe, system } = readTheme(arg, root);
+    const { theme } = system ? applySystem(tokens(), system) : applyRecipe(tokens(), recipe);
     const item = shadcnTheme(theme, {
       ...(recipe.preset ? { name: `halftone-${recipe.preset}`, title: `Halftone ${presetById(recipe.preset)?.name} theme` } : {}),
       fontsUrl: typeof flags['fonts-url'] === 'string' ? flags['fonts-url'] : SHADCN_FONTS_URL,
@@ -194,8 +250,16 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
       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.system) {
+      const { system } = status;
+      const overrides = describeOverrides(system);
+      console.log(`System "${system.name}"${status.code ? ` ${status.code}` : ' (no theme code: it has overrides)'}\n  ${describe(status.recipe)}`);
+      if (overrides.length) console.log(`\nOverrides:\n${overrides.map((o) => `  ${o}`).join('\n')}`);
+      printWarnings(tokens().$extensions?.[THEME_EXTENSION]?.warnings);
+    } else {
+      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.');
@@ -204,7 +268,7 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
   }
 
   if (sub === 'apply') {
-    const recipe = readRecipe(arg, root);
+    const { recipe, system } = readTheme(arg, root);
     const current = tokens();
     const status = themeStatus(current);
     const blocked = !status.applied
@@ -214,12 +278,18 @@ export async function themeCommand({ positional, flags, root, sourcePath, config
         ? `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)}`);
+    const { tokens: next, theme } = system ? applySystem(current, system) : applyRecipe(current, recipe);
+    if (system) {
+      const code = systemCode(system);
+      const overrides = describeOverrides(system);
+      console.log(`System "${system.name}"${code ? ` ${code}` : ''}\n  ${describe(theme.recipe)}`);
+      if (overrides.length) console.log(`\nOverrides (no theme code carries these; tokens.json records the document):\n${overrides.map((o) => `  ${o}`).join('\n')}`);
+    } else 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}`);
     }
+    printWarnings(theme.warnings);
     const cvd = cvdWarnings(theme.resolved);
     if (cvd.length) {
       console.log(`\nColour vision: ${cvd.length} pair(s) of tones closer than ΔE ${MIN_DELTA_E} (a warning; give them an icon or a label as well):`);

package/lib/usage.mjs

@@ -0,0 +1,136 @@
+/**
+ * Which components draw which tokens: the Studio's "Show usage" (apps/docs). Each kit's `registry:build` calls
+ * tokenUsage with its registry (component ids and their files) and writes the result to
+ * registry/generated/token-usage.json, which the docs site reads.
+ *
+ *   tokenUsage({ root, components: [{ id, files }], tokens }) → { 'color.primary': ['button', …], 'radius.md': […], … }
+ *
+ * Keys:
+ *   color.<name>   a semantic colour (or an extra) in a class (bg-primary, text-muted-foreground/80, border-input),
+ *                  var(--name), or the mobile palette (palette.mutedForeground)
+ *   radius.<step>  rounded-sm…2xl, full, control (any side: rounded-t-md)
+ *   shadow.<1|2|3> shadow-xs / shadow-sm / shadow (1), shadow-md (2), shadow-lg / xl / 2xl (3)
+ *   type.<style>   type-h2 (web), text-type-h2 (mobile), or a Text variant ("h2")
+ *   font.<role>    font-heading, font-sans (body), font-mono
+ *   border.width   border, border-x…, the theme's width
+ *   component.<name>  the component layer (button, chip, badge, input): its classes (bg-button-primary-bg,
+ *                  rounded-chip, type-badge) and variables (--field-*). A variant colour also counts as the role
+ *                  tokens.json points it at (bg-chip-selected-bg → color.foreground), so a role's usage still finds it
+ * A static read of class strings: a class built at runtime from parts is not seen.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { COMPONENT_NAMES, COMPONENTS, SLOT_VAR } from './theme/components.mjs';
+
+const TEXT_STYLES = ['h1', 'h2', 'h3', 'h4', 'lead', 'p', 'large', 'small', 'muted', 'code', 'blockquote'];
+const COLOR_UTILITY =
+  /^(?:bg|text|border(?:-[xytrblse])?|divide|outline|ring(?:-offset)?|fill|stroke|from|via|to|accent|caret|placeholder|decoration|shadow)-(.+?)(?:\/[\d.]+)?$/;
+const RADIUS = /^rounded(?:-[trblse]{1,2})?-(sm|md|lg|xl|2xl|full|control)$/;
+const SHADOW = { 'shadow-2xs': '1', 'shadow-xs': '1', 'shadow-sm': '1', shadow: '1', 'shadow-md': '2', 'shadow-lg': '3', 'shadow-xl': '3', 'shadow-2xl': '3' };
+const FONT = { 'font-heading': 'heading', 'font-sans': 'body', 'font-mono': 'mono' };
+
+const camel = (s) => s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+
+/** The class itself, without variants (`dark:hover:`, `[&_svg]:`), important (`!`) or a negative sign. */
+function baseClass(token) {
+  let depth = 0;
+  let cut = -1;
+  for (let i = 0; i < token.length; i++) {
+    if (token[i] === '[') depth++;
+    else if (token[i] === ']') depth--;
+    else if (token[i] === ':' && depth === 0) cut = i;
+  }
+  return token.slice(cut + 1).replace(/^!|!$/g, '').replace(/^-/, '');
+}
+
+/** The colour names a token file defines: semantic colours and extras (a ramp's steps as name-step). */
+export function colourNames(tokens) {
+  const names = new Set(Object.keys(tokens.semantic?.color ?? {}));
+  for (const [name, node] of Object.entries(tokens.extra?.color ?? {})) {
+    if (node && '$value' in node) names.add(name);
+    else for (const step of Object.keys(node ?? {})) if (/^\d+$/.test(step)) names.add(`${name}-${step}`);
+  }
+  return names;
+}
+
+/** The prefix each component's classes and variables use (Input's are field-*). */
+const PREFIX = Object.fromEntries(COMPONENT_NAMES.map((name) => [COMPONENTS[name].prefix, name]));
+const COMPONENT_CLASS = new RegExp(`(?:^|[-(])(${Object.keys(PREFIX).join('|')})-`);
+
+/**
+ * The component layer's colour classes and the roles tokens.json points them at, both modes:
+ * { 'chip-selected-bg': ['foreground'], … }.
+ */
+export function componentColourRoles(tokens) {
+  const out = {};
+  for (const name of COMPONENT_NAMES) {
+    const group = tokens.semantic?.component?.[name];
+    if (!group) continue;
+    for (const [variant, slots] of Object.entries(group)) {
+      if (!slots || typeof slots !== 'object' || '$value' in slots) continue;
+      for (const [slot, key] of Object.entries(SLOT_VAR)) {
+        const value = slots[slot]?.$value;
+        if (!value) continue;
+        const refs = typeof value === 'object' ? [value.light, value.dark] : [value];
+        const roles = [...new Set(refs.map((r) => /^\{semantic\.color\.([a-z0-9-]+)\}$/.exec(String(r))?.[1]).filter(Boolean))];
+        out[`${COMPONENTS[name].prefix}-${variant}-${key}`] = roles;
+      }
+    }
+  }
+  return out;
+}
+
+/** The token keys one source file uses. `roles`: componentColourRoles. */
+export function usageIn(code, colours, roles = {}) {
+  const keys = new Set();
+  // Comments go first: an apostrophe in one ("the theme's") would pair with a quote in the code.
+  const source = code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|\s)\/\/.*$/gm, '$1');
+  const byCamel = new Map([...colours].map((n) => [camel(n), n]));
+  for (const m of source.matchAll(/(["'`])((?:(?!\1)[^\\]|\\.)*)\1/g)) {
+    for (const token of m[2].split(/\s+/)) {
+      if (!token) continue;
+      const cls = baseClass(token);
+      const colour = COLOR_UTILITY.exec(cls);
+      if (colour && colours.has(colour[1])) keys.add(`color.${colour[1]}`);
+      if (colour && roles[colour[1]]) for (const role of roles[colour[1]]) keys.add(`color.${role}`);
+      const component = COMPONENT_CLASS.exec(cls);
+      if (component && (roles[colour?.[1]] || /^(rounded|h|w|size|px|type|text-type|leading-type|tracking-type|border(-b)?)-/.test(cls))) keys.add(`component.${PREFIX[component[1]]}`);
+      const radius = RADIUS.exec(cls);
+      if (radius) keys.add(`radius.${radius[1]}`);
+      if (SHADOW[cls]) keys.add(`shadow.${SHADOW[cls]}`);
+      const type = /^(?:text-)?type-([a-z0-9]+)$/.exec(cls);
+      if (type && TEXT_STYLES.includes(type[1])) keys.add(`type.${type[1]}`);
+      if (FONT[cls]) keys.add(`font.${FONT[cls]}`);
+      if (/^border(?:-[xytrblse])?$/.test(cls)) keys.add('border.width');
+    }
+  }
+  for (const m of source.matchAll(/var\(--([a-z0-9-]+)\)/g)) if (colours.has(m[1])) keys.add(`color.${m[1]}`);
+  for (const m of source.matchAll(/--(button|chip|badge|field)-[a-z0-9-]+/g)) if (!/^--(button|field)(-(foreground|edge))?$/.test(m[0])) keys.add(`component.${PREFIX[m[1]]}`);
+  for (const m of source.matchAll(/\b(?:palette|colors|colours)\.([a-z][A-Za-z0-9]*)\b/g)) if (byCamel.has(m[1])) keys.add(`color.${byCamel.get(m[1])}`);
+  for (const m of source.matchAll(/\bvariant(?:=|:\s*)\{?["']([a-z0-9]+)["']/g)) if (TEXT_STYLES.includes(m[1])) keys.add(`type.${m[1]}`);
+  return keys;
+}
+
+export function tokenUsage({ root, components, tokens }) {
+  const colours = colourNames(tokens);
+  const roles = componentColourRoles(tokens);
+  const usage = {};
+  for (const { id, files } of components) {
+    const keys = new Set();
+    for (const file of files ?? []) {
+      let source;
+      try {
+        source = readFileSync(join(root, file), 'utf8');
+      } catch {
+        continue;
+      }
+      for (const key of usageIn(source, colours, roles)) keys.add(key);
+    }
+    for (const key of keys) (usage[key] ??= []).push(id);
+  }
+  return Object.fromEntries(
+    Object.keys(usage)
+      .sort()
+      .map((key) => [key, [...new Set(usage[key])].sort()])
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halftone-ds/tokens",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Design tokens (W3C DTCG) to NativeWind, Tailwind 4 / shadcn, TypeScript, DESIGN.md and Figma, with a WCAG AA contrast gate. The token build behind Halftone.",
   "license": "MIT",
   "type": "module",
@@ -28,6 +28,10 @@
       "types": "./lib/theme/index.d.mts",
       "default": "./lib/theme/index.mjs"
     },
+    "./system": {
+      "types": "./lib/system/index.d.mts",
+      "default": "./lib/system/index.mjs"
+    },
     "./lib/*": "./lib/*.mjs",
     "./targets/*": "./targets/*.mjs",
     "./package.json": "./package.json"