@halftone-ds/tokens 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@halftone-ds/tokens",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsHendri/halftone.git",
+    "directory": "packages/tokens"
+  },
+  "homepage": "https://github.com/itsHendri/halftone/tree/main/packages/tokens#readme",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "nativewind",
+    "tailwindcss",
+    "shadcn",
+    "expo",
+    "wcag"
+  ],
+  "bin": {
+    "halftone-tokens": "cli.mjs"
+  },
+  "exports": {
+    ".": "./cli.mjs",
+    "./theme": {
+      "types": "./lib/theme/index.d.mts",
+      "default": "./lib/theme/index.mjs"
+    },
+    "./lib/*": "./lib/*.mjs",
+    "./targets/*": "./targets/*.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cli.mjs",
+    "push-figma.mjs",
+    "lib/",
+    "targets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "style-dictionary": "^5.5.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/push-figma.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * tokens/push-figma.mjs — mirror tokens/tokens.json into a Figma Variables collection.
+ *
+ *   npm run tokens:figma                       # writes tokens/generated/figma-variables.json
+ *   FIGMA_TOKEN=… FIGMA_FILE_KEY=… npm run tokens:figma   # …and POSTs it to the Variables REST API
+ *
+ * One-way, code → Figma. The payload creates (or updates, when FIGMA_COLLECTION_ID is set) a
+ * collection "Kit tokens" with two modes (Light, Dark): one COLOR variable per semantic colour, STRING
+ * variables for the theme's fonts and
+ * FLOAT variables for radius, spacing and font sizes. Every variable gets WEB code syntax
+ * (`var(--primary)` / `p-4`) so Dev Mode and the Figma MCP hand back the class names, not hex.
+ *
+ * The write endpoint (POST /v1/files/:key/variables) needs a full Enterprise seat. Without it, the
+ * generated JSON is still useful: paste it into a `use_figma` (Figma MCP) call, or import it with a
+ * variables plugin.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The app root: `halftone-tokens figma --root` sets KIT_TOKENS_ROOT; `npm run tokens:figma` runs from it.
+const root = process.env.KIT_TOKENS_ROOT ?? process.cwd();
+const theme = await import(pathToFileURL(join(root, 'tokens/generated/figma-theme.mjs')).href).catch(() => null);
+if (!theme) {
+  console.error('Run `npm run tokens:build` first (it emits tokens/generated/figma-theme.mjs).');
+  process.exit(1);
+}
+const { COLORS, NUMBERS, STRINGS } = theme;
+
+const hexToRgba = (hex) => {
+  const n = parseInt(hex.slice(1), 16);
+  return { r: ((n >> 16) & 255) / 255, g: ((n >> 8) & 255) / 255, b: (n & 255) / 255, a: 1 };
+};
+
+const COLLECTION = process.env.FIGMA_COLLECTION_ID ?? 'tmp-collection';
+const LIGHT = 'tmp-mode-light';
+const DARK = 'tmp-mode-dark';
+const creatingCollection = !process.env.FIGMA_COLLECTION_ID;
+
+const payload = {
+  variableCollections: creatingCollection ? [{ action: 'CREATE', id: COLLECTION, name: 'Kit tokens', initialModeId: LIGHT }] : [],
+  variableModes: creatingCollection
+    ? [
+        { action: 'UPDATE', id: LIGHT, name: 'Light', variableCollectionId: COLLECTION },
+        { action: 'CREATE', id: DARK, name: 'Dark', variableCollectionId: COLLECTION },
+      ]
+    : [],
+  variables: [],
+  variableModeValues: [],
+};
+
+for (const [name, { light, dark }] of Object.entries(COLORS)) {
+  const id = `tmp-color-${name}`;
+  payload.variables.push({
+    action: 'CREATE',
+    id,
+    name: `color/${name}`,
+    variableCollectionId: COLLECTION,
+    resolvedType: 'COLOR',
+    scopes: ['ALL_SCOPES'],
+    codeSyntax: { WEB: `var(--${name})` },
+  });
+  payload.variableModeValues.push({ variableId: id, modeId: LIGHT, value: hexToRgba(light) });
+  payload.variableModeValues.push({ variableId: id, modeId: DARK, value: hexToRgba(dark) });
+}
+
+for (const [group, entries] of Object.entries(NUMBERS)) {
+  for (const [key, { value, code }] of Object.entries(entries)) {
+    const id = `tmp-${group}-${key}`;
+    payload.variables.push({
+      action: 'CREATE',
+      id,
+      name: `${group}/${key}`,
+      variableCollectionId: COLLECTION,
+      resolvedType: 'FLOAT',
+      scopes:
+        group === 'radius' ? ['CORNER_RADIUS'] : group === 'font-size' ? ['FONT_SIZE'] : group === 'border' || group === 'icon' ? ['STROKE_FLOAT'] : ['GAP', 'WIDTH_HEIGHT'],
+      codeSyntax: { WEB: code },
+    });
+    payload.variableModeValues.push({ variableId: id, modeId: LIGHT, value });
+    payload.variableModeValues.push({ variableId: id, modeId: DARK, value });
+  }
+}
+
+for (const [group, entries] of Object.entries(STRINGS ?? {})) {
+  for (const [key, { value, code }] of Object.entries(entries)) {
+    const id = `tmp-${group}-${key}`;
+    payload.variables.push({
+      action: 'CREATE',
+      id,
+      name: `${group}/${key}`,
+      variableCollectionId: COLLECTION,
+      resolvedType: 'STRING',
+      scopes: ['FONT_FAMILY'],
+      codeSyntax: { WEB: code },
+    });
+    payload.variableModeValues.push({ variableId: id, modeId: LIGHT, value });
+    payload.variableModeValues.push({ variableId: id, modeId: DARK, value });
+  }
+}
+
+mkdirSync(join(root, 'tokens/generated'), { recursive: true });
+const out = join(root, 'tokens/generated/figma-variables.json');
+writeFileSync(out, JSON.stringify(payload, null, 2) + '\n');
+console.log(`Wrote ${out}: ${payload.variables.length} variables × 2 modes`);
+
+const token = process.env.FIGMA_TOKEN;
+const fileKey = process.env.FIGMA_FILE_KEY;
+if (!token || !fileKey) {
+  console.log('Set FIGMA_TOKEN and FIGMA_FILE_KEY to push to Figma (Enterprise seat required for the write API).');
+  process.exit(0);
+}
+const res = await fetch(`https://api.figma.com/v1/files/${fileKey}/variables`, {
+  method: 'POST',
+  headers: { 'X-Figma-Token': token, 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+});
+const body = await res.text();
+if (!res.ok) {
+  console.error(`Figma API ${res.status}: ${body}`);
+  process.exit(1);
+}
+console.log('Pushed to Figma:', body.slice(0, 400));

package/targets/design-md.mjs

@@ -0,0 +1,187 @@
+/**
+ * DESIGN.md (google-labs-code/design.md, spec version "alpha"): the tokens as YAML front matter plus
+ * 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 }
+ */
+import { describeTintLimits, textOnTintLimits } from '../lib/contrast.mjs';
+import { themeFonts } from './fonts.mjs';
+import { themeStatus } from '../lib/theme/index.mjs';
+import { group } from '../lib/resolve.mjs';
+
+const q = (s) => JSON.stringify(String(s));
+const px = (n) => `${n}px`;
+
+/** The Text variants of components/ui/text.tsx, as typography tokens, at the theme's typeset. */
+function typography(prim, type) {
+  const size = Object.fromEntries(group(prim, ['font', 'size']).map((t) => [t.key, Math.round(t.value * type.scale * 10) / 10]));
+  const families = Object.fromEntries(group(prim, ['font', 'family']).map((t) => [t.key, t.value]));
+  const heading = families.heading || families.sans || 'system-ui';
+  const sans = families.body || families.sans || 'system-ui';
+  const mono = families.mono || 'monospace';
+  const levels = [
+    ['h1', heading, size['4xl'], 800, 1.1, '-0.025em'],
+    ['h2', heading, size['3xl'], 600, 1.2, '-0.025em'],
+    ['h3', heading, size['2xl'], 600, 1.25, '-0.025em'],
+    ['h4', heading, size.xl, 600, 1.3, '-0.025em'],
+    ['lead', sans, size.xl, 400, 1.4],
+    ['large', sans, size.lg, 600, 1.4],
+    ['body', sans, size.base, 400, type.leading],
+    ['small', sans, size.sm, 500, 1],
+    ['muted', sans, size.sm, 400, 1.4],
+    ['code', mono, size.sm, 600, 1.4],
+  ];
+  return levels
+    .map(([name, family, fontSize, weight, lineHeight, tracking]) =>
+      [
+        `  ${name}:`,
+        `    fontFamily: ${q(family)}`,
+        `    fontSize: ${px(fontSize)}`,
+        `    fontWeight: ${weight}`,
+        `    lineHeight: ${lineHeight}`,
+        ...(tracking ? [`    letterSpacing: ${tracking}`] : []),
+      ].join('\n')
+    )
+    .join('\n');
+}
+
+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';
+  const description =
+    options.description ?? 'Brand-agnostic prototype kit: shadcn semantics, light and dark, WCAG AA enforced at build time.';
+  const colors = ctx.colors
+    .flatMap((c) => [`  ${c.name}: ${q(c.light)}`, `  ${c.name}-dark: ${q(c.dark)}`])
+    .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)}`),
+    `  control: ${px(Math.min(ctx.shape.control, 9999))}`,
+    `  full: ${px(9999)}`,
+  ].join('\n');
+  const fonts = themeFonts(ctx);
+  const status = themeStatus(ctx.source);
+  const fontName = (f) => (f ? f.family : 'the system font (SF / Roboto)');
+  const spacing = group(ctx.prim, ['space'])
+    .map((t) => `  ${q(t.key)}: ${px(t.value)}`)
+    .join('\n');
+  const hex = Object.fromEntries(ctx.colors.map((c) => [c.name, c.light]));
+  const darkHex = Object.fromEntries(ctx.colors.map((c) => [c.name, c.dark]));
+  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]));
+
+  const contents = `---
+version: alpha
+name: ${q(name)}
+description: ${q(description)}
+colors:
+${colors}
+typography:
+${typography(ctx.prim, ctx.type)}
+rounded:
+${rounded}
+spacing:
+${spacing}
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.${buttons}}"
+    height: 48px
+  button-secondary:
+    backgroundColor: "{colors.secondary}"
+    textColor: "{colors.secondary-foreground}"
+    rounded: "{rounded.${buttons}}"
+    height: 48px
+  card:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.card-foreground}"
+    rounded: "{rounded.lg}"
+    padding: 16px
+  input:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.md}"
+    height: 48px
+---
+
+<!-- ${ctx.header} -->
+
+# ${name}
+
+## Overview
+
+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
+\`tokens/tokens.json\`; everything else follows. The full rules and the component registry are in
+\`DESIGN_SYSTEM.md\` — read it before building UI.
+
+## Colors
+
+Semantic names only (the shadcn vocabulary), each usable as \`bg-\`, \`text-\` and \`border-\`. Never a
+hex literal or a Tailwind palette colour in UI code. Keys ending in \`-dark\` are the dark theme.
+
+- **Primary (${hex.primary} / dark ${darkHex.primary}):** the single most important action, links and focus.
+- **Background (${hex.background}) and Card (${hex.card}):** the page canvas and raised surfaces.
+- **Muted foreground (${hex['muted-foreground']}):** helper text, captions, placeholders.
+- **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.
+
+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:
+
+${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.
+
+## Typography
+
+Headings (h1–h4, titles) use ${fontName(fonts.heading)}; everything else uses ${fontName(fonts.body)}; code and
+figures (\`font-mono\`) use ${fonts.mono ? fonts.mono.family : 'the system monospace font'}. Typeset: body text ${ctx.type.size}px (every
+\`text-*\` size scales with it), running text leading ${ctx.type.leading}. Long-form text (articles, help, rendered
+markdown) goes in \`Prose\`: ${ctx.type.flow}em between blocks, lines up to ${ctx.type.measure} characters.
+Use the Text variants (h1–h4, lead, large, body, small, muted, code) rather than raw sizes. Medium weight for row titles, semibold for headings and
+values, bold only for hero amounts.
+
+## Layout
+
+A 4-pt grid, restricted to the steps in \`spacing\` (0–64px). Screen edge padding 20px, 20px between
+sections, 16px inside cards, 12px vertical in list rows. Siblings are spaced with gaps, not margins,
+and spacing varies to create hierarchy. Interactive targets are at least 44×44.
+
+## Elevation & Depth
+
+Mostly flat: hierarchy comes from surface colour (background → card) and borders. A shadow is only
+for something you can press or something floating above the page (dialogs, sheets, menus, toasts,
+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
+${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.
+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.
+
+## Do's and Don'ts
+
+- Do keep the brand colour for the primary action and focus; one primary action per screen.
+- Do check every screen in light and dark.
+- Don't nest cards inside cards or put a section title inside its card.
+- Don't use grey-on-grey text below 4.5:1, tap targets under 44×44, or icon-only buttons without a label.
+- Don't invent a component: if it is not in the registry, stop and add it properly.
+`;
+  return [{ path: options.out, contents }];
+}

package/targets/figma.mjs

@@ -0,0 +1,41 @@
+/**
+ * Input for push-figma.mjs: semantic colours per mode, the numeric scales with their class names (so
+ * Figma Variables carry `var(--primary)` / `p-4` code syntax), the theme's fonts as strings, and its
+ * shadows for reference (Figma effect styles can't be written through the Variables API).
+ *   options: { out: 'tokens/generated/figma-theme.mjs' }
+ */
+import { group } from '../lib/resolve.mjs';
+import { themeFonts } from './fonts.mjs';
+
+export default function figma(ctx, options) {
+  const colors = Object.fromEntries(ctx.colors.map((c) => [c.name, { light: c.light, dark: c.dark }]));
+  const num = (prefix, code) =>
+    Object.fromEntries(
+      group(ctx.prim, prefix)
+        .filter((t) => typeof t.value === 'number')
+        .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}` }]));
+  radius.control = { value: Math.min(ctx.shape.control, 9999), code: 'rounded-control' };
+  radius.full = { value: 9999, code: 'rounded-full' };
+  const numbers = {
+    radius,
+    space: num(['space'], (k) => `p-${k}`),
+    'font-size': num(['font', 'size'], (k) => `text-${k}`),
+    border: { width: { value: ctx.shape.borderWidth, code: 'border' } },
+    icon: { stroke: { value: ctx.shape.stroke, code: 'strokeWidth' } },
+  };
+  const fonts = themeFonts(ctx);
+  const strings = {
+    font: {
+      heading: { value: fonts.heading?.family ?? 'System', code: 'font-heading' },
+      body: { value: fonts.body?.family ?? 'System', code: 'font-sans' },
+    },
+  };
+  const contents =
+    `// ${ctx.header}\nexport const COLORS = ${JSON.stringify(colors, null, 2)};\nexport const NUMBERS = ${JSON.stringify(numbers, null, 2)};\n` +
+    `export const STRINGS = ${JSON.stringify(strings, null, 2)};\n` +
+    `/** shadow-sm / -md / -lg as CSS, per mode: make them effect styles by hand (not in the Variables API). */\nexport const SHADOWS = ${JSON.stringify(ctx.shape.shadows, null, 2)};\n`;
+  return [{ path: options.out, contents }];
+}

package/targets/fonts.mjs

@@ -0,0 +1,91 @@
+/**
+ * The theme's fonts (primitive.font.family.heading / body / mono), as code that loads them:
+ *   options: { platform: 'expo', out: 'lib/fonts.ts' }   @expo-google-fonts imports, one per weight, and
+ *            the family name expo-font registers for each role and weight (FONT_FAMILY)
+ *   options: { platform: 'next', out: 'app/fonts.ts' }   next/font/google, exposing --kit-font-heading,
+ *            --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).
+ */
+import { FONTS } from '../lib/theme/fonts.mjs';
+import { group } from '../lib/resolve.mjs';
+
+const SUFFIX = { 400: 'Regular', 500: 'Medium', 600: 'SemiBold', 700: 'Bold' };
+
+/** The theme's fonts: { heading, body, mono }, each a FONTS entry or null (the platform's font). */
+export function themeFonts(ctx) {
+  const families = Object.fromEntries(group(ctx.prim, ['font', 'family']).map(({ key, value }) => [key, value]));
+  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(', ')}`);
+    return font.system ? null : font;
+  };
+  return { heading: pick('heading'), body: pick('body'), mono: pick('mono') };
+}
+
+/** The npm packages an Expo app needs for these fonts. */
+export const expoPackages = (fonts) => [...new Set(Object.values(fonts).filter(Boolean).map((f) => `@expo-google-fonts/${f.id}`))];
+
+function expo(ctx, fonts) {
+  const used = [...new Map(Object.values(fonts).filter(Boolean).map((f) => [f.id, f])).values()];
+  const name = (f, w) => `${f.expoPrefix}_${w}${SUFFIX[w]}`;
+  const imports = used.flatMap((f) => f.weights.map((w) => `import { ${name(f, w)} } from '@expo-google-fonts/${f.id}/${w}${SUFFIX[w]}';`));
+  const assets = used.flatMap((f) => f.weights.map((w) => name(f, w)));
+  const family = (f) => (f ? `{ ${f.weights.map((w) => `${w}: '${name(f, w)}'`).join(', ')} }` : 'null');
+  return `// ${ctx.header}
+${imports.join('\n')}${imports.length ? '\n' : ''}
+/** Font files for useFonts from expo-font (app/_layout.tsx). Empty when the theme uses the system font. */
+export const FONT_ASSETS = ${assets.length ? `{ ${assets.join(', ')} }` : '{}'};
+
+/**
+ * The family expo-font registers for each role and weight (null: the system font). Android does not pick a
+ * weight of a custom font from fontWeight, so components/ui/text.tsx sets the family per weight.
+ */
+export const FONT_FAMILY: Record<'heading' | 'body' | 'mono', Record<number, string> | null> = {
+  heading: ${family(fonts.heading)},
+  body: ${family(fonts.body)},
+  mono: ${family(fonts.mono)},
+};
+`;
+}
+
+const nextName = (f) => f.family.replace(/ /g, '_');
+
+function next(ctx, fonts) {
+  const { heading, body, mono } = fonts;
+  if (!heading && !body && !mono) {
+    return `// ${ctx.header}
+/** The theme uses the system fonts: no font variables (app/tokens.css falls back to the system stacks). */
+export const fontVariables = '';
+`;
+  }
+  const roles = [];
+  if (body) roles.push(['body', body]);
+  // The same family for both roles loads once; --kit-font-heading falls back to the body font.
+  if (heading && heading.id !== body?.id) roles.push(['heading', heading]);
+  if (mono) roles.push(['mono', mono]);
+  const loaders = [...new Set(roles.map(([, f]) => nextName(f)))];
+  return `// ${ctx.header}
+import { ${loaders.join(', ')} } from 'next/font/google';
+
+${roles
+  .map(
+    ([role, f]) =>
+      `const ${role} = ${nextName(f)}({ subsets: ['latin'], weight: [${f.weights.map((w) => `'${w}'`).join(', ')}], variable: '--kit-font-${role}', display: 'swap' });`
+  )
+  .join('\n')}
+
+/** Put on <html>: defines --kit-font-${roles.map(([r]) => r).join(' and --kit-font-')}, which app/tokens.css maps to font-sans, font-heading and font-mono. */
+export const fontVariables = [${roles.map(([role]) => `${role}.variable`).join(', ')}].join(' ');
+`;
+}
+
+export default function fontsTarget(ctx, options) {
+  const fonts = themeFonts(ctx);
+  const contents = options.platform === 'next' ? next(ctx, fonts) : expo(ctx, fonts);
+  return [{ path: options.out, contents }];
+}

package/targets/llms.mjs

@@ -0,0 +1,43 @@
+/**
+ * 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' }
+ */
+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';
+
+export default function llms(ctx, options) {
+  const rows = ctx.colors.map((c) => `| \`${c.name}\` | ${c.light} | ${c.dark} |`).join('\n');
+  const steps = (prefix, unit = 'px') =>
+    group(ctx.prim, prefix)
+      .map((t) => `${t.key} ${t.value}${unit}`)
+      .join(' · ');
+  const fonts = themeFonts(ctx);
+  const theme = themeStatus(ctx.source);
+  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\`.
+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))}.
+
+| Name | Light | Dark |
+|---|---|---|
+${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`}`}
+- 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)
+- 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')}
+`;
+  return [{ path: options.out, contents }];
+}

package/targets/nativewind3.mjs

@@ -0,0 +1,70 @@
+/**
+ * NativeWind 4 / Tailwind 3 (shadcn v3 shape): bare HSL triplets in `:root` and `.dark:root`, plus the
+ * colour + radius maps tailwind.config.js spreads in.
+ *   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';
+
+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) {
+  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)))
+    .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) {
+    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;`);
+  }
+  return `  ${selector} {\n${lines.join('\n')}\n  }`;
+}
+
+export default function nativewind3(ctx, options) {
+  const css = `/* ${ctx.header} */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+${cssBlock(':root', ctx.semLight, ctx.shape)}
+
+${cssBlock('.dark:root', ctx.semDark)}
+}
+`;
+  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)]));
+  borderRadius.control = 'var(--radius-control)';
+  const borderWidth = { DEFAULT: 'var(--border-width)' };
+  // 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;
+  const boxShadow = { xs: s[1], sm: s[1], DEFAULT: s[1], md: s[2], lg: s[3], xl: s[3], '2xl': s[3] };
+  // Density: control heights (h-control-sm / h-control / h-control-lg, and min-h-*) and padding (px-control-x).
+  const height = { 'control-sm': 'var(--control-sm)', control: 'var(--control-md)', 'control-lg': 'var(--control-lg)' };
+  // The typeset, literal (native has no runtime theme): text-xs…4xl and their line heights scaled, and
+  // Prose's leading-prose, gap-flow and max-w-measure (native has no ch: half the text size per character).
+  const { scale, leadingFactor, size, leading, flow, measure } = ctx.type;
+  const fontSize = Object.fromEntries(
+    group(ctx.prim, ['font', 'size'])
+      .filter(({ key }) => key in TEXT_LINE_HEIGHT)
+      .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 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`;
+  return [
+    { path: options.css, contents: css },
+    { path: options.tailwind, contents: tailwind },
+  ];
+}

package/targets/registry-theme.mjs

@@ -0,0 +1,38 @@
+/**
+ * The theme as shadcn registry `cssVars`, for the `registry:theme` items: `native` in the NativeWind 4 /
+ * Tailwind 3 shape (HSL triplets + tailwind config extension), `web` in the Tailwind 4 shape (oklch).
+ *   options: { out: 'tokens/generated/theme.registry.json' }
+ */
+import { hexToHslTriplet, hexToOklch } from '../lib/color.mjs';
+import { radiusCalc } from '../lib/resolve.mjs';
+
+export default function registryTheme(ctx, options) {
+  const radius = `${ctx.radius.base / 16}rem`;
+  const vars = (convert, mode) => Object.fromEntries(ctx.colors.map((c) => [c.name, convert(c[mode])]));
+  const theme = {
+    native: {
+      cssVars: {
+        light: { radius, ...vars(hexToHslTriplet, 'light') },
+        dark: vars(hexToHslTriplet, 'dark'),
+      },
+      tailwind: {
+        config: {
+          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)])),
+            },
+          },
+        },
+      },
+    },
+    web: {
+      cssVars: {
+        theme: Object.fromEntries(ctx.radius.steps.map((s) => [`radius-${s.name}`, radiusCalc(s.scale)])),
+        light: { radius, ...vars(hexToOklch, 'light') },
+        dark: vars(hexToOklch, 'dark'),
+      },
+    },
+  };
+  return [{ path: options.out, contents: JSON.stringify(theme, null, 2) + '\n' }];
+}