@worldcoin/nucleus 0.1.4

package/tokens/formats/resolver-android.ts

@@ -0,0 +1,124 @@
+import { ANDROID_DRAWABLE_PREFIX } from './icons-android.js';
+import type { TokenCatalog } from './resolver-shared.js';
+
+/**
+ * Android token resolver generator.
+ *
+ * Emits `NucleusTokenResolver.kt` — a single object (Android ships one artifact, so there's no
+ * cross-module coupling to avoid) with `when`-based lookups mapping each type-scoped wire token to
+ * its compile-time Nucleus accessor. Colors are theme-aware (`isDark`); icons resolve straight to a
+ * `@DrawableRes` id (Android has no runtime icon `Variant` enum — variant availability is encoded in
+ * the type system). Tokens are type-scoped: font `s3`, color `text.primary`, button `inverse.32`,
+ * icon `name.variant`. Forward-only; returns null for unknown tokens so callers fall back + report.
+ */
+
+const PACKAGE_NAME = 'com.worldcoin.nucleus.tokens';
+
+interface Branch {
+  token: string;
+  value: string;
+}
+
+function sortBranches(branches: Branch[]): Branch[] {
+  return [...branches].sort((a, b) => a.token.localeCompare(b.token));
+}
+
+function whenBody(branches: Branch[], indent: string): string {
+  return sortBranches(branches)
+    .map((branch) => `${indent}"${branch.token}" -> ${branch.value}`)
+    .join('\n');
+}
+
+export function generateAndroidResolver(catalog: TokenCatalog): string {
+  // Colors are split into single-param colorLight/colorDark `when`s (kept short and ktlint-clean)
+  // behind a one-line `color(token, isDark)` dispatcher; primitives resolve the same in both.
+  const colorLightBranches: Branch[] = [
+    ...catalog.semanticColors.map((c) => ({
+      token: c.wireToken,
+      value: `NucleusSemanticColorsLight.${c.accessor}`,
+    })),
+    ...catalog.primitiveColors.map((c) => ({
+      token: c.wireToken,
+      value: `NucleusPrimitiveColors.${c.accessor}`,
+    })),
+  ];
+  const colorDarkBranches: Branch[] = [
+    ...catalog.semanticColors.map((c) => ({
+      token: c.wireToken,
+      value: `NucleusSemanticColorsDark.${c.accessor}`,
+    })),
+    ...catalog.primitiveColors.map((c) => ({
+      token: c.wireToken,
+      value: `NucleusPrimitiveColors.${c.accessor}`,
+    })),
+  ];
+  const fontBranches: Branch[] = catalog.fonts.map((f) => ({
+    token: f.wireToken,
+    value: `NucleusFonts.${f.wireToken}`,
+  }));
+  const buttonBranches: Branch[] = catalog.buttons.map((b) => ({
+    token: b.wireToken,
+    value: `NucleusButtons.${b.accessor}`,
+  }));
+  const iconBranches: Branch[] = catalog.icons.map((i) => ({
+    token: i.wireToken,
+    value: `R.drawable.${ANDROID_DRAWABLE_PREFIX}_${i.androidStem}_${i.variant}`,
+  }));
+
+  return `// AUTOGENERATED by tokens/build — do not edit by hand.
+
+package ${PACKAGE_NAME}
+
+import androidx.annotation.DrawableRes
+import androidx.compose.ui.graphics.Color
+import com.worldcoin.nucleus.R
+
+/**
+ * Resolves a canonical Nucleus token-path string — as emitted by the backend SDUI wire contract —
+ * to the corresponding compile-time Nucleus token. Forward-only; returns null for an unknown path
+ * so callers can fall back to a default and report the miss (server and client ship on different
+ * cadences, so an unknown token is expected and must not crash).
+ */
+object NucleusTokenResolver {
+    /** Resolves a color token path, e.g. \`semantic.color.text.primary\`, for the active theme. */
+    fun color(
+        token: String,
+        isDark: Boolean,
+    ): Color? = if (isDark) colorDark(token) else colorLight(token)
+
+    /** Resolves a typography token path, e.g. \`typography.subtitle.s3\`. */
+    fun font(token: String): NucleusFontStyle? =
+        when (token) {
+${whenBody(fontBranches, '            ')}
+            else -> null
+        }
+
+    /** Resolves a button style token path, e.g. \`component.button.inverse.32\`. */
+    fun button(token: String): NucleusButtonStyle? =
+        when (token) {
+${whenBody(buttonBranches, '            ')}
+            else -> null
+        }
+
+    /** Resolves an icon token path, e.g. \`icon.arrow-right.regular\`, to a drawable resource id. */
+    @DrawableRes
+    fun iconRes(token: String): Int? =
+        when (token) {
+${whenBody(iconBranches, '            ')}
+            else -> null
+        }
+
+    private fun colorLight(token: String): Color? =
+        when (token) {
+${whenBody(colorLightBranches, '            ')}
+            else -> null
+        }
+
+    private fun colorDark(token: String): Color? =
+        when (token) {
+${whenBody(colorDarkBranches, '            ')}
+            else -> null
+        }
+}
+`;
+}

package/tokens/formats/resolver-ios.ts

@@ -0,0 +1,128 @@
+import type { TokenCatalog } from './resolver-shared.js';
+
+/**
+ * iOS token resolver generator.
+ *
+ * Emits one `+TokenResolvable.swift` conformance per primitive type (color/font/button/icon),
+ * each living in that type's own target so a consumer only pulls in what it imports — no
+ * monolithic target that depends on every module. Each conforms to the `TokenResolvable`
+ * protocol (hand-written in the zero-dependency `NucleusTokens` target). Forward-only; an
+ * unknown token returns `nil` and trips `assertionFailure` in debug builds.
+ *
+ * Tokens are type-scoped (the resolver type implies the namespace): font `s3`, color
+ * `text.primary`, button `inverse.32`, icon `name.variant`.
+ */
+
+const HEADER = '// AUTOGENERATED by tokens/build — do not edit by hand.';
+
+interface Row {
+  key: string;
+  value: string;
+}
+
+function dictionary(name: string, type: string, rows: Row[]): string {
+  const body = [...rows]
+    .sort((a, b) => a.key.localeCompare(b.key))
+    .map((row) => `    "${row.key}": ${row.value},`)
+    .join('\n');
+  return `private let ${name}: [String: ${type}] = [\n${body}\n]`;
+}
+
+function simpleResolvable(args: {
+  type: string;
+  mapName: string;
+  rows: Row[];
+  doc: string;
+}): string {
+  return `${HEADER}
+
+import NucleusTokens
+
+${dictionary(args.mapName, args.type, args.rows)}
+
+extension ${args.type}: TokenResolvable {
+    /// ${args.doc}
+    public static func resolve(token: String) -> ${args.type}? {
+        guard let value = ${args.mapName}[token] else {
+            assertionFailure("unknown ${args.type} token: \\(token)")
+            return nil
+        }
+        return value
+    }
+}
+`;
+}
+
+export function generateIOSColorResolvable(catalog: TokenCatalog): string {
+  const rows: Row[] = [...catalog.semanticColors, ...catalog.primitiveColors].map((c) => ({
+    key: c.wireToken,
+    value: `.${c.accessor}`,
+  }));
+  return simpleResolvable({
+    type: 'NucleusColor',
+    mapName: 'colorTokens',
+    rows,
+    doc: 'Resolves a type-scoped color token, e.g. `text.primary` or `grey.900`.',
+  });
+}
+
+export function generateIOSFontResolvable(catalog: TokenCatalog): string {
+  const rows: Row[] = catalog.fonts.map((f) => ({ key: f.wireToken, value: `.${f.wireToken}` }));
+  return simpleResolvable({
+    type: 'NucleusFont',
+    mapName: 'fontTokens',
+    rows,
+    doc: 'Resolves a type-scoped typography token (bare id), e.g. `s3`.',
+  });
+}
+
+export function generateIOSButtonResolvable(catalog: TokenCatalog): string {
+  const rows: Row[] = catalog.buttons.map((b) => ({ key: b.wireToken, value: `.${b.accessor}` }));
+  return simpleResolvable({
+    type: 'NucleusButton',
+    mapName: 'buttonTokens',
+    rows,
+    doc: 'Resolves a type-scoped button style token, e.g. `inverse.32`.',
+  });
+}
+
+export function generateIOSIconResolvable(catalog: TokenCatalog): string {
+  const names = dictionary(
+    'iconTokens',
+    'NucleusIcon',
+    catalog.iconNames.map((i) => ({ key: i.name, value: `.${i.swiftCase}` })),
+  );
+  const variants = dictionary(
+    'variantTokens',
+    'NucleusIcon.Variant',
+    catalog.iconVariants.map((v) => ({ key: v, value: `.${v}` })),
+  );
+  return `${HEADER}
+
+import NucleusTokens
+
+${names}
+
+${variants}
+
+extension NucleusIcon: TokenResolvable {
+    /// Resolves a type-scoped icon token \`name.variant\`, e.g. \`arrow-right.regular\`.
+    public static func resolve(token: String) -> (icon: NucleusIcon, variant: NucleusIcon.Variant)? {
+        let components = token.components(separatedBy: ".")
+        guard components.count == 2 else {
+            assertionFailure("NucleusIcon token must be \`name.variant\`: \\(token)")
+            return nil
+        }
+        guard
+            let icon = iconTokens[components[0]],
+            let variant = variantTokens[components[1]],
+            icon.availableVariants.contains(variant)
+        else {
+            assertionFailure("unknown NucleusIcon token: \\(token)")
+            return nil
+        }
+        return (icon, variant)
+    }
+}
+`;
+}

package/tokens/formats/resolver-shared.ts

@@ -0,0 +1,176 @@
+import { loadButtonDefinition, resolveButtonStyles } from './buttons.js';
+import { discoverIconTokens, type IconVariant } from './icons-shared.js';
+import { loadColorTokens, loadFontDefinitions } from './loaders.js';
+import { camelCasePath, publicColorPath, typographyTokenPath } from './shared.js';
+
+/**
+ * Shared catalog for the token-path ↔ token resolvers. Enumerates every published token with both
+ * its canonical path (for reference) and the **type-scoped wire token** the backend emits and the
+ * resolvers key on — the namespace that the resolver type already implies is stripped:
+ *   - color:      `semantic.color.text.primary` → `text.primary`  (and `primitive.color.grey.900` → `grey.900`)
+ *   - typography: `typography.subtitle.s3`       → `s3`
+ *   - button:     `component.button.inverse.32`  → `inverse.32`
+ *   - icon:       `icon.arrow-right.regular`      → `arrow-right.regular`
+ * Reuses the same accessor-naming the platform token generators use, so the resolver can't drift.
+ */
+
+const PRIMITIVE_SOURCE = 'tokens/definitions/color/primitive.json';
+const SEMANTIC_LIGHT_SOURCE = 'tokens/definitions/color/semantic.light.json';
+const FONT_SOURCE = 'tokens/definitions/font/fonts.json';
+const BUTTON_SOURCE = 'tokens/definitions/component/button.json';
+
+export interface ColorEntry {
+  /** Type-scoped wire token, e.g. `text.primary` / `grey.900`. */
+  wireToken: string;
+  /** `NucleusColor` / `NucleusSemanticColors*` accessor, e.g. `textPrimary`. */
+  accessor: string;
+}
+
+export interface FontEntry {
+  /** Type-scoped wire token (bare id), e.g. `s3`. Also the `NucleusFont(s)` accessor. */
+  wireToken: string;
+  /** camelCase web-constant key, e.g. `subtitleS3`. */
+  key: string;
+}
+
+export interface ButtonEntry {
+  /** Type-scoped wire token, e.g. `inverse.32`. */
+  wireToken: string;
+  /** `NucleusButton(s)` accessor + web-constant key, e.g. `inverse32`. */
+  accessor: string;
+}
+
+export interface IconEntry {
+  /** Type-scoped wire token, e.g. `arrow-right.regular`. */
+  wireToken: string;
+  /** camelCase web-constant key, e.g. `arrowRightRegular`. */
+  key: string;
+  /** kebab-case icon name, e.g. `arrow-right`. */
+  name: string;
+  /** `NucleusIcon` Swift case, e.g. `arrowRight`. */
+  swiftCase: string;
+  /** `NucleusIcon` Kotlin object, e.g. `ArrowRight`. */
+  kotlinCase: string;
+  /** snake_case stem in android drawable names, e.g. `arrow_right`. */
+  androidStem: string;
+  variant: IconVariant;
+}
+
+export interface IconNameEntry {
+  /** kebab-case wire name, e.g. `arrow-right`. */
+  name: string;
+  swiftCase: string;
+  kotlinCase: string;
+  androidStem: string;
+}
+
+export interface TokenCatalog {
+  semanticColors: ColorEntry[];
+  primitiveColors: ColorEntry[];
+  fonts: FontEntry[];
+  buttons: ButtonEntry[];
+  icons: IconEntry[];
+  /** Distinct icon names (for the iOS name → NucleusIcon map). */
+  iconNames: IconNameEntry[];
+  /** Icon variants present across the set (for the iOS variant map). */
+  iconVariants: IconVariant[];
+}
+
+function colorEntries(source: string): ColorEntry[] {
+  return loadColorTokens(source).map((leaf) => ({
+    wireToken: publicColorPath(leaf.path).join('.'),
+    accessor: camelCasePath(publicColorPath(leaf.path)),
+  }));
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+export function buildTokenCatalog(): TokenCatalog {
+  // Light & dark semantic palettes share the same key paths; the light source is sufficient.
+  const semanticColors = colorEntries(SEMANTIC_LIGHT_SOURCE);
+  const primitiveColors = colorEntries(PRIMITIVE_SOURCE);
+
+  const fonts: FontEntry[] = loadFontDefinitions(FONT_SOURCE).tokens.map((token) => {
+    const path = typographyTokenPath(token.name); // typography.subtitle.s3
+    return {
+      wireToken: token.name, // bare id, e.g. s3
+      key: camelCasePath(path.split('.').slice(1)), // subtitleS3 (web)
+    };
+  });
+
+  const buttons: ButtonEntry[] = resolveButtonStyles(
+    loadButtonDefinition(BUTTON_SOURCE),
+  ).map((style) => ({
+    wireToken: `${style.variant}.${style.size}`, // inverse.32
+    accessor: `${style.variant}${style.size}`, // inverse32
+  }));
+
+  const discovered = discoverIconTokens();
+  const icons: IconEntry[] = discovered.flatMap((icon) =>
+    icon.variants.map((variant) => ({
+      wireToken: `${icon.name}.${variant}`, // arrow-right.regular
+      key: `${icon.swiftCase}${capitalize(variant)}`, // arrowRightRegular
+      name: icon.name,
+      swiftCase: icon.swiftCase,
+      kotlinCase: icon.kotlinCase,
+      androidStem: icon.androidStem,
+      variant,
+    })),
+  );
+  const iconNames: IconNameEntry[] = discovered.map((icon) => ({
+    name: icon.name,
+    swiftCase: icon.swiftCase,
+    kotlinCase: icon.kotlinCase,
+    androidStem: icon.androidStem,
+  }));
+  const iconVariants = [...new Set(discovered.flatMap((icon) => icon.variants))].sort();
+
+  const catalog = {
+    semanticColors,
+    primitiveColors,
+    fonts,
+    buttons,
+    icons,
+    iconNames,
+    iconVariants,
+  };
+  validateCatalog(catalog);
+  return catalog;
+}
+
+/**
+ * Generation-time round-trip guard: the wire tokens a single resolver keys on must be unique
+ * (colors merge semantic + primitive into one `NucleusColor` map), and every per-family web key
+ * must be unique. (Wrong-accessor regressions are caught by the native builds in CI.)
+ */
+function validateCatalog(catalog: TokenCatalog): void {
+  const groups: Array<[string, string[]]> = [
+    // NucleusColor.resolve keys on one merged map → must be unique across semantic + primitive.
+    [
+      'color wire tokens',
+      [...catalog.semanticColors, ...catalog.primitiveColors].map((e) => e.wireToken),
+    ],
+    ['font wire tokens', catalog.fonts.map((e) => e.wireToken)],
+    ['button wire tokens', catalog.buttons.map((e) => e.wireToken)],
+    ['icon wire tokens', catalog.icons.map((e) => e.wireToken)],
+    ['ColorTokens keys', catalog.semanticColors.map((e) => e.accessor)],
+    ['PrimitiveColorTokens keys', catalog.primitiveColors.map((e) => e.accessor)],
+    ['TypographyTokens keys', catalog.fonts.map((e) => e.key)],
+    ['ButtonTokens keys', catalog.buttons.map((e) => e.accessor)],
+    ['IconTokens keys', catalog.icons.map((e) => e.key)],
+  ];
+  for (const [label, values] of groups) {
+    const seen = new Set<string>();
+    for (const value of values) {
+      if (!value) {
+        throw new Error(`resolver catalog: empty value in ${label}`);
+      }
+      if (seen.has(value)) {
+        throw new Error(`resolver catalog: duplicate "${value}" in ${label}`);
+      }
+      seen.add(value);
+    }
+  }
+}

package/tokens/formats/resolver-web.ts

@@ -0,0 +1,89 @@
+import type { TokenCatalog } from './resolver-shared.js';
+
+/**
+ * Web token-path constants generator.
+ *
+ * Emits a runtime CommonJS module (`token-paths.js`) plus literal-typed declarations
+ * (`token-paths.d.ts`) exporting one frozen object per token family, keyed by descriptive
+ * camelCase, value = the type-scoped wire token (e.g. `text.primary`, `s3`, `inverse.32`,
+ * `arrow-right.regular`). This is the source of truth the app-backend SDUI library imports
+ * instead of hand-writing token literals — so the backend maintains no mapping of its own.
+ */
+
+interface ConstObject {
+  name: string;
+  doc: string;
+  entries: Array<{ key: string; value: string }>;
+}
+
+function constObjects(catalog: TokenCatalog): ConstObject[] {
+  const objects: ConstObject[] = [
+    {
+      name: 'ColorTokens',
+      doc: 'Type-scoped semantic color tokens, e.g. `text.primary`.',
+      entries: catalog.semanticColors.map((c) => ({ key: c.accessor, value: c.wireToken })),
+    },
+    {
+      name: 'PrimitiveColorTokens',
+      doc: 'Type-scoped primitive color tokens, e.g. `grey.900`.',
+      entries: catalog.primitiveColors.map((c) => ({ key: c.accessor, value: c.wireToken })),
+    },
+    {
+      name: 'TypographyTokens',
+      doc: 'Type-scoped typography tokens (bare id), e.g. `s3`.',
+      entries: catalog.fonts.map((f) => ({ key: f.key, value: f.wireToken })),
+    },
+    {
+      name: 'ButtonTokens',
+      doc: 'Type-scoped button style tokens, e.g. `inverse.32`.',
+      entries: catalog.buttons.map((b) => ({ key: b.accessor, value: b.wireToken })),
+    },
+    {
+      name: 'IconTokens',
+      doc: 'Type-scoped icon tokens, e.g. `arrow-right.regular`.',
+      entries: catalog.icons.map((i) => ({ key: i.key, value: i.wireToken })),
+    },
+  ];
+  return objects.map((object) => ({
+    ...object,
+    entries: [...object.entries].sort((a, b) => a.key.localeCompare(b.key)),
+  }));
+}
+
+const HEADER = '// AUTOGENERATED by tokens/build — do not edit by hand.';
+
+export function generateWebTokenPathsJs(catalog: TokenCatalog): string {
+  const lines: string[] = [
+    "'use strict';",
+    HEADER,
+    "Object.defineProperty(exports, '__esModule', { value: true });",
+    '',
+  ];
+  for (const object of constObjects(catalog)) {
+    lines.push(`exports.${object.name} = Object.freeze({`);
+    for (const { key, value } of object.entries) {
+      lines.push(`  ${key}: '${value}',`);
+    }
+    lines.push('});');
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function generateWebTokenPathsDts(catalog: TokenCatalog): string {
+  const lines: string[] = [
+    HEADER,
+    '// Canonical Nucleus token-path constants — runtime values with literal types.',
+    '',
+  ];
+  for (const object of constObjects(catalog)) {
+    lines.push(`/** ${object.doc} */`);
+    lines.push(`export declare const ${object.name}: {`);
+    for (const { key, value } of object.entries) {
+      lines.push(`  readonly ${key}: '${value}';`);
+    }
+    lines.push('};');
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/tokens/formats/shared.ts

@@ -0,0 +1,70 @@
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+export function readTemplate(path: string): string {
+  return readFileSync(resolve(ROOT, path), 'utf8');
+}
+
+export function camelCasePath(path: string[]): string {
+  return path
+    .map((segment, index) =>
+      index === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1),
+    )
+    .join('');
+}
+
+export function kebabCasePath(path: string[]): string {
+  return path.join('-').replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+export function kebabCase(value: string): string {
+  return value.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+export function snakeCase(value: string): string {
+  return value
+    .replace(/\.[^./]+$/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+export function publicColorPath(path: string[]): string[] {
+  if ((path[0] === 'primitive' || path[0] === 'semantic') && path[1] === 'color') {
+    return path.slice(2);
+  }
+  return path;
+}
+
+const REFERENCE_RE = /^\{(.+)\}$/;
+
+export function parseReference(rawValue: string): string[] | null {
+  const match = rawValue.match(REFERENCE_RE);
+  return match ? match[1].split('.') : null;
+}
+
+const FONT_CATEGORY: Record<string, string> = {
+  d: 'display',
+  n: 'number',
+  h: 'headline',
+  s: 'subtitle',
+  l: 'label',
+  b: 'body',
+};
+
+/**
+ * Grouped typography path for a flat font-token id, e.g. `s1` → `typography.subtitle.s1`.
+ * The category is derived from the id prefix (UI Kit 4.0 grouping).
+ */
+export function typographyTokenPath(fontName: string): string {
+  const category = FONT_CATEGORY[fontName[0]];
+  if (!category) {
+    throw new Error(
+      `Cannot derive typography category for font token "${fontName}". ` +
+        `Add a prefix mapping to FONT_CATEGORY in formats/shared.ts.`,
+    );
+  }
+  return `typography.${category}.${fontName}`;
+}

package/tokens/formats/types-web.ts

@@ -0,0 +1,61 @@
+/**
+ * Web TypeScript types generator.
+ *
+ * Emits literal-union types so consumers (e.g. the app-backend SDUI library) get compile-time
+ * safety instead of `Record<string, string>` when referencing tokens. The members are the
+ * type-scoped wire tokens the backend emits and the resolvers key on (the same `wireToken` values
+ * that drive `token-paths.{js,d.ts}`, so the union types and the runtime constants can never
+ * diverge):
+ *   - colors: `text.primary` (semantic) / `grey.900` (primitive)
+ *   - typography: `s3`
+ *   - buttons: `inverse.32`
+ *   - icons: `arrow-right.regular`
+ */
+
+function unionType(name: string, values: string[]): string {
+  const members = [...new Set(values)].sort();
+  if (members.length === 0) {
+    return `export type ${name} = never;`;
+  }
+  return `export type ${name} =\n${members.map((v) => `  | '${v}'`).join('\n')};`;
+}
+
+export interface WebTypesInput {
+  /** Type-scoped color wire tokens (semantic + primitive). */
+  colorTokens: string[];
+  /** Type-scoped typography wire tokens (bare ids). */
+  typographyTokens: string[];
+  /** Type-scoped button style wire tokens. */
+  buttonStyleTokens: string[];
+  /** Type-scoped icon wire tokens. */
+  iconTokens: string[];
+}
+
+export function generateWebTypes({
+  colorTokens,
+  typographyTokens,
+  buttonStyleTokens,
+  iconTokens,
+}: WebTypesInput): string {
+  return [
+    '// AUTOGENERATED by tokens/build — do not edit by hand.',
+    '// Type-scoped Nucleus wire tokens as literal-union types.',
+    '',
+    '/** Type-scoped color token, e.g. `text.primary`. */',
+    unionType('ColorToken', colorTokens),
+    '',
+    '/** Type-scoped typography token (bare id), e.g. `s3`. */',
+    unionType('TypographyToken', typographyTokens),
+    '',
+    '/** Type-scoped button style token, e.g. `inverse.32`. */',
+    unionType('ButtonStyleToken', buttonStyleTokens),
+    '',
+    '/** Type-scoped icon token, e.g. `arrow-right.regular`. */',
+    unionType('IconToken', iconTokens),
+    '',
+    '/** Runtime token maps are published as JSON modules (camelCase keys → values). */',
+    'declare const tokens: Record<string, string>;',
+    'export default tokens;',
+    '',
+  ].join('\n');
+}