@halftone-ds/tokens 1.1.0 → 1.3.0

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.1.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"

package/targets/design-md.mjs

@@ -3,9 +3,11 @@
  * short, platform-neutral prose an agent can load on its own. The spec has no light/dark modes, so
  * `colors` carries the light value under each name and the dark one under `<name>-dark`.
  * The detailed rules stay in DESIGN_SYSTEM.md; this file points there instead of repeating them.
- *   options: { out: 'DESIGN.md', name?: string, description?: string }
+ *   options: { out: 'DESIGN.md', name?: string, description?: string, platform?: 'mobile' | 'web' }
  */
 import { describeTintLimits, textOnTintLimits } from '../lib/contrast.mjs';
+import { describeComponents } from '../lib/theme/components.mjs';
+import { describeExtras } from '../lib/theme/extras.mjs';
 import { themeFonts } from './fonts.mjs';
 import { themeStatus } from '../lib/theme/index.mjs';
 import { group } from '../lib/resolve.mjs';
@@ -46,10 +48,42 @@ function typography(prim, type) {
     .join('\n');
 }
 
+/**
+ * The contrast sentence. A passing palette says the build names any pairing that falls short (and --strict
+ * fails on it); a failing one, which only builds without --strict, names its pairings.
+ */
+function contrastLine(ctx) {
+  const failures = ctx.contrastFailures ?? [];
+  if (!failures.length) {
+    return `Every \`X\` / \`X-foreground\` pairing, muted text on every surface, and every status tone used as text
+clears WCAG AA (4.5:1) in both themes; the build names any pairing that falls short, and \`--strict\` fails on it.`;
+  }
+  return `${failures.length} pairing(s) in this palette fall below WCAG AA (4.5:1). Fix them before handing a prototype
+over (\`npm run tokens:build -- --strict\` fails on them):
+
+${failures.map((f) => `- ${f.trim()}`).join('\n')}`;
+}
+
+/** How the theme's styles read in DESIGN.md. */
+const STYLE_TEXT = {
+  button: {
+    solid: 'The primary button is a solid brand fill.',
+    soft: 'The primary button is a soft brand tint with brand text.',
+    outline: 'The primary button is a brand outline with brand text, no fill.',
+    raised: 'The primary button is a solid brand fill with a darker bottom edge.',
+  },
+  field: {
+    outline: 'Text fields are outlined boxes.',
+    filled: 'Text fields are tinted, with a line along the bottom.',
+    underline: 'Text fields are a single line, no box.',
+  },
+};
+
 export default function designMd(ctx, options) {
   const name = options.name ?? 'Halftone';
-  // Which radius buttons use: 'control' (the theme's pill setting, the mobile kit) or a scale step (web: 'md').
-  const buttons = options.buttonRadius ?? 'control';
+  // The component layer: one theme for both kits (Button, Chip, Badge, Input).
+  const { button, input } = ctx.components;
+  const corner = (r) => (r >= 9999 ? '"{rounded.full}"' : px(r));
   const description =
     options.description ?? 'Brand-agnostic prototype kit: shadcn semantics, light and dark, WCAG AA enforced at build time.';
   const colors = ctx.colors
@@ -57,7 +91,7 @@ export default function designMd(ctx, options) {
     .join('\n');
   // The theme's radius: rounded-* are multiples of its base (rounded-lg); control is buttons and chips.
   const rounded = [
-    ...ctx.radius.steps.map((s) => `  ${s.name}: ${px(Math.round(ctx.radius.base * s.scale * 10) / 10)}`),
+    ...ctx.radius.steps.map((s) => `  ${s.name}: ${px(s.px)}`),
     `  control: ${px(Math.min(ctx.shape.control, 9999))}`,
     `  full: ${px(9999)}`,
   ].join('\n');
@@ -72,6 +106,19 @@ export default function designMd(ctx, options) {
   const radius = Object.fromEntries(group(ctx.prim, ['radius']).map((t) => [t.key, t.value]));
   const duration = Object.fromEntries(group(ctx.prim, ['duration']).map((t) => [t.key, t.value]));
 
+  // A system's own tokens: listed, never in the front matter's shared vocabulary.
+  const extras = describeExtras(ctx.extras ?? { color: [], text: [], radius: [], shadow: [], border: [] }, { platform: options.platform ?? 'mobile' });
+  const extrasSection = extras.length
+    ? `
+## Extras (this brand's own)
+
+Tokens this system added beyond the kit's slots. No kit component uses them; use them in screens, as classes like
+any token (never their hex). They are not part of the shared vocabulary above.
+
+${extras.join('\n')}
+`
+    : '';
+
   const contents = `---
 version: alpha
 name: ${q(name)}
@@ -88,13 +135,13 @@ components:
   button-primary:
     backgroundColor: "{colors.primary}"
     textColor: "{colors.primary-foreground}"
-    rounded: "{rounded.${buttons}}"
-    height: 48px
+    rounded: ${corner(button.radius)}
+    height: ${px(button.h.md)}
   button-secondary:
     backgroundColor: "{colors.secondary}"
     textColor: "{colors.secondary-foreground}"
-    rounded: "{rounded.${buttons}}"
-    height: 48px
+    rounded: ${corner(button.radius)}
+    height: ${px(button.h.md)}
   card:
     backgroundColor: "{colors.card}"
     textColor: "{colors.card-foreground}"
@@ -103,8 +150,8 @@ components:
   input:
     backgroundColor: "{colors.background}"
     textColor: "{colors.foreground}"
-    rounded: "{rounded.md}"
-    height: 48px
+    rounded: ${corner(input.radius)}
+    height: ${px(input.h.md)}
 ---
 
 <!-- ${ctx.header} -->
@@ -116,7 +163,7 @@ components:
 A neutral, brand-agnostic base for clickable prototypes on phone and web. Calm surfaces, one brand
 colour reserved for the primary action and focus, generous spacing, and both light and dark themes
 from day one. ${status.applied ? `The applied theme is \`${status.code}\`${status.drift.length ? ' (edited by hand since)' : ''}. ` : ''}Re-branding means applying a
-theme (\`npx halftone-tokens theme apply <code>\`, codes come from the docs theme picker) or editing
+theme (\`npx halftone-tokens theme apply <code|file.halftone.json>\`, both from Studio on the docs site) or editing
 \`tokens/tokens.json\`; everything else follows. The full rules and the component registry are in
 \`DESIGN_SYSTEM.md\` — read it before building UI.
 
@@ -131,8 +178,7 @@ hex literal or a Tailwind palette colour in UI code. Keys ending in \`-dark\` ar
 - **Destructive, Success, Warning, Info:** status only, each with its own \`-foreground\`.
 - **Chart 1–5:** data series.
 
-Every \`X\` / \`X-foreground\` pairing, muted text on every surface, and every status tone used as text
-clears WCAG AA (4.5:1) in both themes; the build refuses a palette that does not.
+${contrastLine(ctx)}
 
 A tone's text on that tone's own tint (\`text-success\` on \`bg-success/15\`) is a weaker pairing. With
 this palette it clears AA only for:
@@ -141,7 +187,7 @@ ${describeTintLimits(textOnTintLimits(ctx.colors))}.
 
 On a stronger tint, the text stays \`text-foreground\` and the tint, an icon or a dot carries the
 colour. \`halftone-tokens check\` flags class strings that break this.
-
+${extrasSection}
 ## Typography
 
 Headings (h1–h4, titles) use ${fontName(fonts.heading)}; everything else uses ${fontName(fonts.body)}; code and
@@ -165,13 +211,14 @@ a floating button). Content — inputs included — stays flat.
 
 ## Shapes
 
-Buttons are pills. Inputs ${radius.md}px, cards ${radius.lg}px, larger surfaces ${radius.xl}px, sheet tops
+Buttons ${button.radius >= 9999 ? 'are pills' : `have ${button.radius}px corners`}. Inputs ${input.radius}px, cards ${radius.lg}px, larger surfaces ${radius.xl}px, sheet tops
 ${radius['2xl']}px; chips, avatars and dots are fully round.
 
 ## Components
 
-Only components listed in the registry in \`DESIGN_SYSTEM.md\` exist. Controls are 48px tall (small
-40, large 56). Selected chips and segments are neutral (inverted foreground), never the brand colour.
+Only components listed in the registry in \`DESIGN_SYSTEM.md\` exist. ${STYLE_TEXT.button[ctx.styles.button]} ${STYLE_TEXT.field[ctx.styles.field]}
+Button, Chip, Badge and Input draw the theme's component tokens, the same in both kits: ${describeComponents(ctx.components).join('; ')}.
+Never restyle them by hand. Phones raise any tap target under 44px to 44.
 Motion: ${duration.fast}ms for micro-feedback, ${duration.base}ms for most transitions, ${duration.slow}ms for sheets, and
 nothing moves when the OS asks for reduced motion.
 

package/targets/figma.mjs

@@ -16,7 +16,7 @@ export default function figma(ctx, options) {
         .map((t) => [t.key, { value: t.value, code: code(t.key) }])
     );
   // The theme's radius: rounded-* scale with its base (rounded-lg); rounded-control is buttons and chips.
-  const radius = Object.fromEntries(ctx.radius.steps.map((s) => [s.name, { value: Math.round(ctx.radius.base * s.scale * 10) / 10, code: `rounded-${s.name}` }]));
+  const radius = Object.fromEntries(ctx.radius.steps.map((s) => [s.name, { value: s.px, code: `rounded-${s.name}` }]));
   radius.control = { value: Math.min(ctx.shape.control, 9999), code: 'rounded-control' };
   radius.full = { value: 9999, code: 'rounded-full' };
   const numbers = {

package/targets/fonts.mjs

@@ -6,10 +6,11 @@
  *            --kit-font-body and --kit-font-mono (app/tokens.css maps them to font-heading / font-sans / font-mono)
  * An empty family (heading, body) or Menlo (mono) is the platform's own font: nothing to load.
  *
- * Only fonts from the curated list (lib/theme/fonts.mjs) are supported; halftone-tokens theme apply installs
- * the @expo-google-fonts packages they need (see expoPackages).
+ * A curated font (lib/theme/fonts.mjs) loads the weights it lists; any other Google Fonts family (a system's
+ * fonts) loads 400–700 under the packages' own naming (fontByFamily). halftone-tokens theme apply installs the
+ * @expo-google-fonts packages they need (see expoPackages).
  */
-import { FONTS } from '../lib/theme/fonts.mjs';
+import { fontByFamily } from '../lib/theme/fonts.mjs';
 import { group } from '../lib/resolve.mjs';
 
 const SUFFIX = { 400: 'Regular', 500: 'Medium', 600: 'SemiBold', 700: 'Bold' };
@@ -20,8 +21,7 @@ export function themeFonts(ctx) {
   const pick = (role) => {
     const family = families[role];
     if (!family) return null;
-    const font = FONTS.find((f) => f.family === family);
-    if (!font) throw new Error(`fonts: "${family}" (font.family.${role}) is not in the curated font list; pick one of ${FONTS.filter((f) => !f.system).map((f) => f.family).join(', ')}`);
+    const font = fontByFamily(family);
     return font.system ? null : font;
   };
   return { heading: pick('heading'), body: pick('body'), mono: pick('mono') };

package/targets/llms.mjs

@@ -1,12 +1,14 @@
 /**
  * The tokens section of llms.txt: a compact Markdown fragment that registry-build stitches into the
  * app's llms.txt (and the docs site into /llms.txt).
- *   options: { out: 'tokens/generated/llms-tokens.md' }
+ *   options: { out: 'tokens/generated/llms-tokens.md', platform?: 'mobile' | 'web' }
  */
 import { group } from '../lib/resolve.mjs';
 import { AA, describeTintLimits, textOnTintLimits } from '../lib/contrast.mjs';
 import { themeStatus } from '../lib/theme/index.mjs';
 import { themeFonts } from './fonts.mjs';
+import { describeComponents } from '../lib/theme/components.mjs';
+import { describeExtras } from '../lib/theme/extras.mjs';
 
 export default function llms(ctx, options) {
   const rows = ctx.colors.map((c) => `| \`${c.name}\` | ${c.light} | ${c.dark} |`).join('\n');
@@ -16,12 +18,13 @@ export default function llms(ctx, options) {
       .join(' · ');
   const fonts = themeFonts(ctx);
   const theme = themeStatus(ctx.source);
+  const extras = describeExtras(ctx.extras ?? { color: [], text: [], radius: [], shadow: [], border: [] }, { platform: options.platform ?? 'mobile' });
   const contents = `<!-- ${ctx.header} -->
 ## Tokens
 
 Colours are semantic names only, used as Tailwind classes (\`bg-primary\`, \`text-muted-foreground\`,
 \`border-border\`, \`bg-success/15\`). Never hex, never Tailwind palette colours. Both themes are
-required; every fill/foreground pairing clears WCAG AA (${AA}:1), enforced by \`npm run tokens:build\`.
+required; ${ctx.contrastFailures?.length ? `${ctx.contrastFailures.length} pairing(s) in this palette fall below WCAG AA (${AA}:1): fix them (\`npm run tokens:build\` names them).` : `every fill/foreground pairing clears WCAG AA (${AA}:1); \`npm run tokens:build\` names any that falls short (\`--strict\` fails on it).`}
 A tone's own text on its own tint (\`text-success\` on \`bg-success/15\`) clears AA only for these
 tints; on a stronger one, put \`text-foreground\` on the tint:
 ${describeTintLimits(textOnTintLimits(ctx.colors))}.
@@ -31,13 +34,15 @@ ${describeTintLimits(textOnTintLimits(ctx.colors))}.
 ${rows}
 
 - Spacing (4-pt grid, Tailwind numeric scale): ${steps(['space'])}
-- Radius (\`rounded-*\`): ${ctx.radius.steps.map((s) => `${s.name} ${Math.round(ctx.radius.base * s.scale * 10) / 10}px`).join(' · ')} (multiples of \`--radius\` = ${ctx.radius.base}px)${options.controlRadius === false ? '; buttons use \`rounded-md\`' : `; \`rounded-control\` (buttons, chips) ${ctx.shape.control >= 9999 ? 'pill' : `${ctx.shape.control}px`}`}
+- Radius (\`rounded-*\`): ${ctx.radius.steps.map((s) => `${s.name} ${s.px}px`).join(' · ')} (multiples of \`--radius\` = ${ctx.radius.base}px); \`rounded-control\` ${ctx.shape.control >= 9999 ? 'pill' : `${ctx.shape.control}px`}
 - Depth: \`shadow-sm\` (controls, cards), \`shadow-md\` (raised, popovers), \`shadow-lg\` (menus, dialogs) are the theme's three elevation levels; no shadow colour modifiers on surfaces (thumbs and floating elements may add \`shadow-black/20\`)
 - Border \`border\` ${ctx.shape.borderWidth}px · icon stroke ${ctx.shape.stroke} (an Icon's \`strokeWidth\` is relative to 2)
+- Styles: ${ctx.styles.button} buttons, ${ctx.styles.field} fields
+- Components (one theme for both kits; never restyle them by hand): ${describeComponents(ctx.components).join('; ')}. Phones raise any tap target under 44px to 44
 - Fonts: headings ${fonts.heading?.family ?? 'system'}, body ${fonts.body?.family ?? 'system'}, mono ${fonts.mono?.family ?? 'system'} (applied by Text; \`font-heading\` makes any Text a heading, \`font-mono\` code and figures)
 - Typeset: body ${ctx.type.size}px, leading ${ctx.type.leading}; every \`text-*\` size below scales by ${ctx.type.scale}${theme.applied ? `\n- Theme: \`${theme.code}\` (\`npx halftone-tokens theme show\`)` : ''}
 - Font sizes (\`text-*\`): ${steps(['font', 'size'])}
 - Durations: ${steps(['duration'], 'ms')}
-`;
+${extras.length ? `\n### Extras (this brand's own)\n\nNo kit component uses these; screens may, as classes (never their hex):\n\n${extras.join('\n')}\n` : ''}`;
   return [{ path: options.out, contents }];
 }

package/targets/nativewind3.mjs

@@ -4,28 +4,47 @@
  *   options: { css: 'global.css', tailwind: 'tokens/generated/tailwind.theme.js' }
  */
 import { hexToHslTriplet } from '../lib/color.mjs';
-import { cssName, group, isColor, radiusCalc } from '../lib/resolve.mjs';
-import { TEXT_LINE_HEIGHT } from '../lib/theme/recipe.mjs';
+import { cssName, group, isColor, radiusCss } from '../lib/resolve.mjs';
+import { shadowCss, TEXT_LINE_HEIGHT } from '../lib/theme/recipe.mjs';
+import { COMPONENT_NAMES, COMPONENTS, componentColors, componentVars } from '../lib/theme/components.mjs';
+import { extraTextStyles } from '../lib/theme/extras.mjs';
+import { extraVars, styleVars, textStyleVars } from '../lib/theme/vars.mjs';
 
 const rem = (px) => (px >= 9999 ? '9999px' : `${Number((px / 16).toFixed(4))}rem`);
 
 /** Shape variables come from ctx.shape, which has defaults for a token file from before themes. */
 const SHAPE = new Set(['radius-control', 'border-width', 'icon-stroke']);
 
-function cssBlock(selector, tokens, shape) {
+function cssBlock(selector, tokens, shape, mode, colors) {
   const lines = tokens
-    // Shadows are literal in tailwind.theme.js: a var() box-shadow drops the view on native.
-    .filter((t) => t.$type !== 'shadow' && !SHAPE.has(cssName(t)) && !/^(density|type)-/.test(cssName(t)))
+    // Shadows are literal in tailwind.theme.js: a var() box-shadow drops the view on native. The styles'
+    // numbers come from shape (with their units), below.
+    // A system's radius steps are in borderRadius below, with their units.
+    .filter((t) => t.$type !== 'shadow' && !SHAPE.has(cssName(t)) && !/^(density|type|radius)-/.test(cssName(t)))
+    .filter((t) => isColor(t) || !/^(button|field)-/.test(cssName(t)))
     .map((t) => {
       const name = cssName(t);
       if (isColor(t)) return `    --${name}: ${hexToHslTriplet(t.$value)};`;
       if (name === 'radius') return `    --${name}: ${rem(t.$value)};`;
       return `    --${name}: ${t.$value};`;
     });
-  if (shape) {
+  if (shape.control !== undefined) {
     lines.push(`    --radius-control: ${rem(shape.control)};`, `    --border-width: ${shape.borderWidth}px;`, `    --icon-stroke: ${shape.stroke};`);
     for (const size of ['sm', 'md', 'lg', 'x']) lines.push(`    --control-${size}: ${shape.density[size]}px;`);
   }
+  // The text styles (Text h1…blockquote): literal at the typeset, so an edited style is one variable.
+  if (shape.textStyles) for (const [name, value] of Object.entries(textStyleVars(shape.textStyles, 'hsl'))) lines.push(`    ${name}: ${value};`);
+  // Style colours a token file from before the styles doesn't have (resolve.mjs adds them), then the styles' numbers.
+  const present = new Set(tokens.filter(isColor).map(cssName));
+  for (const c of colors) if (!present.has(c.name)) lines.push(`    --${c.name}: ${hexToHslTriplet(c[mode])};`);
+  for (const [name, value] of Object.entries(styleVars(shape.styleShape, 'hsl')[mode])) lines.push(`    ${name}: ${value};`);
+  // The component layer (Button, Chip, Badge, Input): corners, sizes, text and each variant's colours.
+  if (shape.components) for (const [name, value] of Object.entries(componentVars(shape.components, 'hsl', hexToHslTriplet)[mode])) lines.push(`    ${name}: ${value};`);
+  // A system's extras: colours, text styles and border widths (corners and shadows are literal in tailwind.theme.js).
+  if (shape.extras) {
+    const extra = Object.entries(extraVars(shape.extras, 'hsl')[mode]).filter(([name]) => !/^--(radius|shadow)-/.test(name));
+    if (extra.length) lines.push('    /* Extras: this system\'s own tokens. No kit component uses them; screens may. */', ...extra.map(([name, value]) => `    ${name}: ${value};`));
+  }
   return `  ${selector} {\n${lines.join('\n')}\n  }`;
 }
 
@@ -36,15 +55,23 @@ export default function nativewind3(ctx, options) {
 @tailwind utilities;
 
 @layer base {
-${cssBlock(':root', ctx.semLight, ctx.shape)}
+${cssBlock(':root', ctx.semLight, { ...ctx.shape, styleShape: ctx.shape, textStyles: ctx.textStyles, extras: ctx.extras, components: ctx.components }, 'light', ctx.colors)}
 
-${cssBlock('.dark:root', ctx.semDark)}
+${cssBlock('.dark:root', ctx.semDark, { styleShape: ctx.shape, extras: ctx.extras, components: ctx.components }, 'dark', ctx.colors)}
 }
 `;
   const colors = Object.fromEntries(ctx.colors.map((c) => [c.name, `hsl(var(--${c.name}))`]));
-  const borderRadius = Object.fromEntries(ctx.radius.steps.map((s) => [s.name, radiusCalc(s.scale)]));
+  // The styles' fills carry their own opacity (an outline button, a transparent field). No /90 modifiers on these.
+  colors.button = 'hsl(var(--button) / var(--button-alpha))';
+  colors.field = 'hsl(var(--field) / var(--field-alpha))';
+  const borderRadius = Object.fromEntries(ctx.radius.steps.map((s) => [s.name, radiusCss(s)]));
   borderRadius.control = 'var(--radius-control)';
-  const borderWidth = { DEFAULT: 'var(--border-width)' };
+  // Field style: rounded-field (top) and rounded-b-field-b (bottom).
+  borderRadius.field = 'var(--field-radius)';
+  borderRadius['field-b'] = 'var(--field-radius-b)';
+  // The styles' widths: border-button-w / border-b-button-edge-w, border-field-w / border-b-field-edge-w (named
+  // apart from the colours, or border-button would set both).
+  const borderWidth = { DEFAULT: 'var(--border-width)', 'button-w': 'var(--button-border-w)', 'button-edge-w': 'var(--button-edge-w)', 'field-w': 'var(--field-border-w)', 'field-edge-w': 'var(--field-edge-w)' };
   // The theme's depth takes over Tailwind's shadow scale: 1 = xs/sm/shadow, 2 = md, 3 = lg/xl/2xl. Light
   // values: native can't switch a box-shadow per scheme.
   const s = ctx.shape.shadows.light;
@@ -60,9 +87,47 @@ ${cssBlock('.dark:root', ctx.semDark)}
       .map(({ key, value }) => [key, [rem(value * scale), { lineHeight: rem(TEXT_LINE_HEIGHT[key] * scale * leadingFactor) }]])
   );
   const lineHeight = { prose: rem(size * leading) };
-  const spacing = { 'control-x': 'var(--control-x)', flow: rem(size * flow) };
+  const spacing = { 'control-x': 'var(--control-x)', 'field-x': 'var(--field-x)', flow: rem(size * flow) };
   const maxWidth = { measure: rem(measure * size * 0.5) };
-  const tailwind = `// ${ctx.header}\nmodule.exports = ${JSON.stringify({ colors, borderRadius, borderWidth, boxShadow, height, minHeight: height, width: height, spacing, fontSize, lineHeight, maxWidth }, null, 2)};\n`;
+  // The text styles, one key per property: text-type-h1, leading-type-h1, tracking-type-h1, font-type-h1 (Text's
+  // variants). Variables (global.css), so a system's edited style changes one value.
+  for (const name of Object.keys(ctx.textStyles)) {
+    fontSize[`type-${name}`] = `var(--type-${name}-size)`;
+    lineHeight[`type-${name}`] = `var(--type-${name}-leading)`;
+  }
+  const letterSpacing = Object.fromEntries(Object.keys(ctx.textStyles).map((name) => [`type-${name}`, `var(--type-${name}-tracking)`]));
+  const fontWeight = Object.fromEntries(Object.keys(ctx.textStyles).map((name) => [`type-${name}`, `var(--type-${name}-weight)`]));
+  // The component layer: bg-button-primary-bg, rounded-button, h-button-md, px-button-x, text-type-button,
+  // border-button-primary-w… Each colour carries its opacity (--button-primary-bg-a).
+  Object.assign(colors, componentColors(ctx.components, (key, alpha) => (alpha ? `hsl(var(--${key}) / var(--${key}-a))` : `hsl(var(--${key}))`)));
+  for (const name of COMPONENT_NAMES) {
+    const c = ctx.components[name];
+    const p = COMPONENTS[name].prefix;
+    if (name !== 'input') borderRadius[p] = `var(--${p}-radius)`;
+    for (const size of Object.keys(c.h)) height[`${p}-${size}`] = `var(--${p}-h-${size})`;
+    if (name !== 'input') spacing[`${p}-x`] = `var(--${p}-x)`;
+    fontSize[`type-${p}`] = `var(--${p}-text-size)`;
+    lineHeight[`type-${p}`] = `var(--${p}-text-leading)`;
+    letterSpacing[`type-${p}`] = `var(--${p}-text-tracking)`;
+  }
+  Object.assign(spacing, { 'button-x-sm': 'var(--button-x-sm)', 'button-x-lg': 'var(--button-x-lg)' });
+  for (const variant of Object.keys(ctx.components.button.variants)) {
+    borderWidth[`button-${variant}-w`] = `var(--button-${variant}-border-w)`;
+    borderWidth[`button-${variant}-edge-w`] = `var(--button-${variant}-edge-w)`;
+  }
+  // A system's extras: bg-<name>, rounded-<name>, shadow-<name>, border-<name> (its width), text-type-<name>…
+  const extras = ctx.extras ?? { color: [], text: [], radius: [], shadow: [], border: [] };
+  for (const c of extras.color) colors[c.name] = `hsl(var(--${c.name}))`;
+  for (const r of extras.radius) borderRadius[r.name] = rem(r.px);
+  for (const sh of extras.shadow) boxShadow[sh.name] = shadowCss(sh.light);
+  for (const b of extras.border) borderWidth[b.name] = `var(--border-${b.name}-width)`;
+  for (const name of Object.keys(extraTextStyles(extras))) {
+    fontSize[`type-${name}`] = `var(--type-${name}-size)`;
+    lineHeight[`type-${name}`] = `var(--type-${name}-leading)`;
+    letterSpacing[`type-${name}`] = `var(--type-${name}-tracking)`;
+    fontWeight[`type-${name}`] = `var(--type-${name}-weight)`;
+  }
+  const tailwind = `// ${ctx.header}\nmodule.exports = ${JSON.stringify({ colors, borderRadius, borderWidth, boxShadow, height, minHeight: height, width: height, spacing, fontSize, lineHeight, letterSpacing, fontWeight, maxWidth }, null, 2)};\n`;
   return [
     { path: options.css, contents: css },
     { path: options.tailwind, contents: tailwind },

package/targets/registry-theme.mjs

@@ -4,7 +4,7 @@
  *   options: { out: 'tokens/generated/theme.registry.json' }
  */
 import { hexToHslTriplet, hexToOklch } from '../lib/color.mjs';
-import { radiusCalc } from '../lib/resolve.mjs';
+import { radiusCss } from '../lib/resolve.mjs';
 
 export default function registryTheme(ctx, options) {
   const radius = `${ctx.radius.base / 16}rem`;
@@ -20,7 +20,7 @@ export default function registryTheme(ctx, options) {
           theme: {
             extend: {
               colors: Object.fromEntries(ctx.colors.map((c) => [c.name, `hsl(var(--${c.name}))`])),
-              borderRadius: Object.fromEntries(ctx.radius.steps.map((s) => [s.name, radiusCalc(s.scale)])),
+              borderRadius: Object.fromEntries(ctx.radius.steps.map((s) => [s.name, radiusCss(s)])),
             },
           },
         },
@@ -28,7 +28,7 @@ export default function registryTheme(ctx, options) {
     },
     web: {
       cssVars: {
-        theme: Object.fromEntries(ctx.radius.steps.map((s) => [`radius-${s.name}`, radiusCalc(s.scale)])),
+        theme: Object.fromEntries(ctx.radius.steps.map((s) => [`radius-${s.name}`, radiusCss(s)])),
         light: { radius, ...vars(hexToOklch, 'light') },
         dark: vars(hexToOklch, 'dark'),
       },