inkhouse 0.1.0-beta.0

package/src/tokens.ts

@@ -0,0 +1,717 @@
+import { parseColor, mergeTokens as deepMergeTokens } from './colors';
+import { readVariableTokens } from './variables';
+import type { ScannedTokenMap } from './token-source';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A flat record of token name -> value (e.g. color name -> oklch string). */
+export type TokenGroup = Record<string, string>;
+
+/** A theme block contains optional color, radius, spacing, fontSize, and shadow groups. */
+export interface ThemeTokens {
+  color?: TokenGroup;
+  font?: TokenGroup;
+  radius?: TokenGroup;
+  spacing?: TokenGroup;
+  fontSize?: TokenGroup;
+  shadow?: TokenGroup;
+}
+
+/** Core (non-theme) tokens. */
+export interface CoreTokens {
+  font?: TokenGroup;
+}
+
+/** Top-level tokens structure with core + named themes. */
+export interface Tokens {
+  core?: CoreTokens;
+  primary?: ThemeTokens;
+  secondary?: ThemeTokens;
+  tertiary?: ThemeTokens;
+  [theme: string]: ThemeTokens | CoreTokens | undefined;
+}
+
+/** DTCG token leaf node. */
+export interface DTCGEntry {
+  $type: string;
+  $value: string;
+  $description?: string;
+}
+
+/** DTCG output structure (recursive groups with $metadata at root). */
+export interface DTCGTokens {
+  $metadata?: {
+    description: string;
+    note: string;
+  };
+  [key: string]: any;
+}
+
+export interface VariableTokenDiffOptions {
+  allowNewTokensFromFigma?: boolean;
+  newTokenPrefixes?: string[];
+}
+
+/** Component definitions fetched from dev server. */
+export interface ComponentDefs {
+  schemaVersion?: number;
+  version?: string;
+  generatedAt?: string;
+  components: any[];
+  spacingScale: Record<string, any>;
+  colorTokens: any[];
+  paletteTokens?: Record<string, string>;
+  iconRegistry?: Record<string, { module: string; exportName: string; svg: string }>;
+  styleMap?: Record<string, { declarations: Record<string, string>; media?: string }[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Mutable state
+// ---------------------------------------------------------------------------
+
+export let TOKENS: Tokens = {"primary":{"color":{"background":"oklch(1 0 0)","foreground":"oklch(0.141 0.005 285.823)","card":"oklch(1 0 0)","card-foreground":"oklch(0.141 0.005 285.823)","popover":"oklch(1 0 0)","popover-foreground":"oklch(0.141 0.005 285.823)","primary":"oklch(62.71% 0.17 149.21)","primary-foreground":"oklch(0.982 0.018 155.826)","secondary":"oklch(0.967 0.001 286.375)","secondary-foreground":"oklch(0.21 0.006 285.885)","muted":"oklch(0.967 0.001 286.375)","muted-foreground":"oklch(0.552 0.016 285.938)","accent":"oklch(0.967 0.001 286.375)","accent-foreground":"oklch(0.21 0.006 285.885)","destructive":"oklch(0.577 0.245 27.325)","border":"oklch(0.92 0.004 286.32)","input":"oklch(0.92 0.004 286.32)","ring":"oklch(0.723 0.219 149.579)","sidebar":"oklch(0.985 0 0)","sidebar-foreground":"oklch(0.141 0.005 285.823)","sidebar-primary":"oklch(0.723 0.219 149.579)","sidebar-primary-foreground":"oklch(0.982 0.018 155.826)","sidebar-accent":"oklch(0.967 0.001 286.375)","sidebar-accent-foreground":"oklch(0.21 0.006 285.885)","sidebar-border":"oklch(0.92 0.004 286.32)","sidebar-ring":"oklch(0.723 0.219 149.579)"},"font":{"sans":"\"Open Sans\", ui-sans-serif, system-ui, sans-serif","heading":"\"Open Sans\", ui-sans-serif, system-ui, sans-serif"},"radius":{"base":"0.5rem","sm":"0.25rem","md":"0.5rem","lg":"0.75rem","xl":"1rem","2xl":"1.25rem","full":"624rem"},"spacing":{"xs":"0.25rem","sm":"0.5rem","md":"1rem","lg":"1.5rem","xl":"2rem","2xl":"3rem","3xl":"4rem","4xl":"6rem"},"fontSize":{"xs":"0.75rem","sm":"0.875rem","base":"1rem","lg":"1.125rem","xl":"1.25rem","2xl":"1.5rem","3xl":"1.875rem","4xl":"2.25rem","5xl":"3rem","6xl":"3.75rem"},"shadow":{"sm":"0 1px 2px 0 rgb(0 0 0 / 0.05)","DEFAULT":"0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)","md":"0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)","lg":"0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.05)","xl":"0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.04)","2xl":"0 25px 50px -12px rgb(0 0 0 / 0.25)","inner":"inset 0 2px 4px 0 rgb(0 0 0 / 0.05)"}},"secondary":{"color":{"background":"oklch(1 0 0)","foreground":"oklch(0.141 0.005 285.823)","card":"oklch(1 0 0)","card-foreground":"oklch(0.141 0.005 285.823)","popover":"oklch(1 0 0)","popover-foreground":"oklch(0.141 0.005 285.823)","primary":"oklch(62.71% 0.17 250)","primary-foreground":"oklch(0.982 0.018 250)","secondary":"oklch(0.967 0.001 286.375)","secondary-foreground":"oklch(0.21 0.006 285.885)","muted":"oklch(0.967 0.001 286.375)","muted-foreground":"oklch(0.552 0.016 285.938)","accent":"oklch(0.967 0.001 286.375)","accent-foreground":"oklch(0.21 0.006 285.885)","destructive":"oklch(0.577 0.245 250)","border":"oklch(0.92 0.004 286.32)","input":"oklch(0.92 0.004 286.32)","ring":"oklch(0.723 0.219 250)","sidebar":"oklch(0.985 0 0)","sidebar-foreground":"oklch(0.141 0.005 285.823)","sidebar-primary":"oklch(0.723 0.219 250)","sidebar-primary-foreground":"oklch(0.982 0.018 250)","sidebar-accent":"oklch(0.967 0.001 286.375)","sidebar-accent-foreground":"oklch(0.21 0.006 285.885)","sidebar-border":"oklch(0.92 0.004 286.32)","sidebar-ring":"oklch(0.723 0.219 250)"},"font":{"sans":"\"Inter\", ui-sans-serif, system-ui, sans-serif","heading":"\"Playfair Display\", Georgia, serif"},"radius":{"base":"1rem","sm":"0.75rem","md":"1rem","lg":"1.25rem","xl":"1.5rem","2xl":"1.75rem","full":"624rem"}}};
+const EMBEDDED_TOKENS_SNAPSHOT: Tokens = JSON.parse(JSON.stringify(TOKENS));
+
+// Component definitions - fetched from dev server at runtime
+// This starts empty and is populated by fetchComponentDefsFromServer()
+export let COMPONENT_DEFS: ComponentDefs = { components: [], spacingScale: {}, colorTokens: [], paletteTokens: {}, iconRegistry: {} };
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function mergeTokens(base: any, override: any): any {
+  if (!isPlainObject(base)) return override;
+  const out: Record<string, any> = {};
+  for (const key in base) out[key] = base[key];
+  for (const key in override) {
+    if (isPlainObject(base[key]) && isPlainObject(override[key])) {
+      out[key] = mergeTokens(base[key], override[key]);
+    } else {
+      out[key] = override[key];
+    }
+  }
+  return out;
+}
+
+function parseDimensionToPx(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  if (raw.endsWith('px')) {
+    const n = parseFloat(raw.slice(0, -2));
+    return Number.isFinite(n) ? n : null;
+  }
+  if (raw.endsWith('rem')) {
+    const n = parseFloat(raw.slice(0, -3));
+    return Number.isFinite(n) ? n * 16 : null;
+  }
+  if (/^-?[0-9.]+$/.test(raw)) {
+    const n = parseFloat(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function normalizeFontFamily(value: unknown): string {
+  return String(value || '')
+    .split(',')[0]
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .toLowerCase();
+}
+
+function valuesAreSemanticallyEqual(path: string[], baseValue: unknown, nextValue: unknown): boolean {
+  if (baseValue === undefined || nextValue === undefined) return false;
+  const group = path.length >= 2 ? path[1] : '';
+
+  if (group === 'color') {
+    try {
+      const a = parseColor(baseValue);
+      const b = parseColor(nextValue);
+      const eps = 1 / 255 + 1e-6;
+      return (
+        Math.abs(a.r - b.r) <= eps &&
+        Math.abs(a.g - b.g) <= eps &&
+        Math.abs(a.b - b.b) <= eps &&
+        Math.abs((a.a == null ? 1 : a.a) - (b.a == null ? 1 : b.a)) <= 0.01
+      );
+    } catch (_e) {
+      return String(baseValue).trim() === String(nextValue).trim();
+    }
+  }
+
+  if (group === 'radius' || group === 'spacing' || group === 'fontSize') {
+    const a = parseDimensionToPx(baseValue);
+    const b = parseDimensionToPx(nextValue);
+    if (a != null && b != null) return Math.abs(a - b) < 0.001;
+    return String(baseValue).trim() === String(nextValue).trim();
+  }
+
+  if (group === 'font') {
+    return normalizeFontFamily(baseValue) === normalizeFontFamily(nextValue);
+  }
+
+  return String(baseValue).trim() === String(nextValue).trim();
+}
+
+function hasLeafValues(node: unknown): boolean {
+  if (!isPlainObject(node)) return node !== undefined;
+  for (const key in node) {
+    if (hasLeafValues((node as Record<string, unknown>)[key])) return true;
+  }
+  return false;
+}
+
+function isColorValueObject(value: unknown): boolean {
+  if (!isPlainObject(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.r === 'number' &&
+    typeof candidate.g === 'number' &&
+    typeof candidate.b === 'number' &&
+    (candidate.a === undefined || typeof candidate.a === 'number')
+  );
+}
+
+function isKnownThemeGroupName(name: string): boolean {
+  return (
+    name === 'color' ||
+    name === 'radius' ||
+    name === 'font' ||
+    name === 'spacing' ||
+    name === 'fontSize' ||
+    name === 'shadow'
+  );
+}
+
+function buildVariableDiffPatch(
+  base: unknown,
+  next: unknown,
+  path: string[] = [],
+  options?: VariableTokenDiffOptions
+): Record<string, unknown> | unknown | undefined {
+  const treatNextAsLeaf = !isPlainObject(next) || isColorValueObject(next);
+  if (treatNextAsLeaf) {
+    if (valuesAreSemanticallyEqual(path, base, next)) return undefined;
+    return next;
+  }
+  if (!isPlainObject(base) || isColorValueObject(base)) {
+    // Only allow new leaf tokens under known theme groups when explicitly enabled.
+    const allowNew = options && options.allowNewTokensFromFigma === true;
+    if (!allowNew) return undefined;
+    return undefined;
+  }
+
+  const allowNew = options && options.allowNewTokensFromFigma === true;
+  const allowedPrefixes = (options && options.newTokenPrefixes) ? options.newTokenPrefixes : [];
+
+  const out: Record<string, unknown> = {};
+  for (const key in next) {
+    const hasBaseKey = key in (base as Record<string, unknown>);
+    if (!hasBaseKey) {
+      const nextValue = (next as Record<string, unknown>)[key];
+      // Always allow brand-new top-level themes from Figma (e.g. "client2"),
+      // so theme creation does not silently drop to sparse diffs.
+      if (path.length === 0 && key !== 'core' && isPlainObject(nextValue)) {
+        out[key] = nextValue;
+        continue;
+      }
+
+      if (!allowNew) continue;
+      const parentTheme = path[0] || '';
+      const parentGroup = path[1] || '';
+      // Allow adding a missing known token group under an existing theme.
+      if (path.length === 1 && parentTheme !== 'core' && isKnownThemeGroupName(key) && isPlainObject(nextValue)) {
+        out[key] = nextValue;
+        continue;
+      }
+      const isKnownGroup =
+        parentGroup === 'color' ||
+        parentGroup === 'radius' ||
+        parentGroup === 'font' ||
+        parentGroup === 'spacing' ||
+        parentGroup === 'fontSize' ||
+        parentGroup === 'shadow';
+      const isLeaf = !isPlainObject(nextValue);
+      const isThemeScope = path.length >= 2 && parentTheme !== 'core';
+      if (!isLeaf || !isKnownGroup || !isThemeScope) continue;
+
+      if (allowedPrefixes.length > 0) {
+        let prefixMatch = false;
+        for (let i = 0; i < allowedPrefixes.length; i++) {
+          if (key.startsWith(allowedPrefixes[i])) {
+            prefixMatch = true;
+            break;
+          }
+        }
+        if (!prefixMatch) continue;
+      }
+    }
+
+    const child = buildVariableDiffPatch(
+      (base as Record<string, unknown>)[key],
+      (next as Record<string, unknown>)[key],
+      path.concat(key),
+      options
+    );
+    if (child !== undefined && hasLeafValues(child)) out[key] = child;
+  }
+
+  return Object.keys(out).length ? out : undefined;
+}
+
+function numberToDimensionToken(value: number): string {
+  if (!Number.isFinite(value)) return '0';
+  const rounded = Math.round(value * 1000) / 1000;
+  const rem = rounded / 16;
+  if (Math.abs(rem * 16 - rounded) < 0.001) {
+    const remStr = String(Math.round(rem * 1000) / 1000).replace(/\.0+$/, '').replace(/(\.\d*?)0+$/, '$1');
+    return `${remStr}rem`;
+  }
+  const pxStr = String(rounded).replace(/\.0+$/, '').replace(/(\.\d*?)0+$/, '$1');
+  return `${pxStr}px`;
+}
+
+function mapDimensionGroup(group: Record<string, number>): TokenGroup {
+  const out: TokenGroup = {};
+  for (const key in group) {
+    const value = group[key];
+    if (!Number.isFinite(value)) continue;
+    out[key] = numberToDimensionToken(value);
+  }
+  return out;
+}
+
+function hasKeys(group: Record<string, unknown> | undefined): boolean {
+  return !!group && Object.keys(group).length > 0;
+}
+
+function buildTokenPatchFromScanned(map: ScannedTokenMap): Tokens {
+  const patch: Tokens = {};
+
+  const primary: ThemeTokens = {};
+  if (hasKeys(map.colors)) primary.color = { ...map.colors };
+  if (hasKeys(map.fonts)) primary.font = { ...map.fonts };
+  if (hasKeys(map.radius)) primary.radius = mapDimensionGroup(map.radius);
+  if (hasKeys(map.spacing)) primary.spacing = mapDimensionGroup(map.spacing);
+  if (hasKeys(map.fontSize)) primary.fontSize = mapDimensionGroup(map.fontSize);
+  if (hasKeys(map.shadows)) primary.shadow = { ...map.shadows };
+  if (Object.keys(primary).length > 0) patch.primary = primary;
+
+  for (const themeName in map.themes) {
+    const scanned = map.themes[themeName];
+    if (!scanned) continue;
+    const themedPatch: ThemeTokens = {};
+    if (hasKeys(scanned.colors)) themedPatch.color = { ...scanned.colors };
+    if (hasKeys(scanned.fonts)) themedPatch.font = { ...scanned.fonts };
+    if (hasKeys(scanned.radius)) themedPatch.radius = mapDimensionGroup(scanned.radius as Record<string, number>);
+    if (hasKeys(scanned.spacing)) themedPatch.spacing = mapDimensionGroup(scanned.spacing as Record<string, number>);
+    if (hasKeys(scanned.fontSize)) themedPatch.fontSize = mapDimensionGroup(scanned.fontSize as Record<string, number>);
+    if (hasKeys(scanned.shadows)) themedPatch.shadow = { ...(scanned.shadows as Record<string, string>) };
+    if (Object.keys(themedPatch).length > 0) patch[themeName] = themedPatch;
+  }
+
+  return patch;
+}
+
+function cloneTokens<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function buildTokensFromScanned(map: ScannedTokenMap, baseSnapshot: Tokens): Tokens {
+  const scannedPatch = buildTokenPatchFromScanned(map);
+  const out: Tokens = {};
+
+  // Keep core as-is (scanner currently maps fonts into theme blocks).
+  if (baseSnapshot.core) {
+    out.core = cloneTokens(baseSnapshot.core);
+  }
+
+  const basePrimary = (baseSnapshot.primary && typeof baseSnapshot.primary === 'object')
+    ? (baseSnapshot.primary as ThemeTokens)
+    : {};
+  const scannedPrimary = (scannedPatch.primary && typeof scannedPatch.primary === 'object')
+    ? (scannedPatch.primary as ThemeTokens)
+    : {};
+  const primaryTheme = mergeTokens(cloneTokens(basePrimary), scannedPrimary) as ThemeTokens;
+  out.primary = primaryTheme;
+
+  const scannedThemeNames = Object.keys(map.themes || {}).filter((name) => name && name !== 'primary');
+  for (let i = 0; i < scannedThemeNames.length; i++) {
+    const themeName = scannedThemeNames[i];
+    const scannedTheme = scannedPatch[themeName];
+    if (!scannedTheme || typeof scannedTheme !== 'object') continue;
+    // CSS theme blocks are often overrides; inherit from primary and apply overrides.
+    out[themeName] = mergeTokens(cloneTokens(primaryTheme), scannedTheme as ThemeTokens) as ThemeTokens;
+  }
+
+  return out;
+}
+
+export function applyScannedTokens(map: ScannedTokenMap | null | undefined): void {
+  if (!map || map.mode === 'embedded') {
+    TOKENS = cloneTokens(EMBEDDED_TOKENS_SNAPSHOT);
+    return;
+  }
+
+  const base = cloneTokens(EMBEDDED_TOKENS_SNAPSHOT) as Tokens;
+  TOKENS = buildTokensFromScanned(map, base);
+}
+
+export function maybeApplyVariableTokens(): boolean {
+  try {
+    const varTokens = readVariableTokens();
+    if (varTokens) {
+      TOKENS = mergeTokens(TOKENS, varTokens);
+      return true;
+    }
+  } catch (_err) {
+    // Variable reading failed - continue with embedded tokens
+  }
+  return false;
+}
+
+/**
+ * Merge only meaningful variable edits into TOKENS.
+ * Keeps original token formats (oklch/rem/font stacks) for unchanged values and
+ * ignores unknown keys that are not present in the current token schema.
+ */
+export function applyVariableTokenDiffs(): boolean {
+  return applyVariableTokenDiffsWithOptions({});
+}
+
+export function getVariableTokenDiffWithOptions(options: VariableTokenDiffOptions): Tokens | null {
+  try {
+    const varTokens = readVariableTokens();
+    if (!varTokens) return null;
+    const diffPatch = buildVariableDiffPatch(TOKENS as unknown, varTokens as unknown, [], options);
+    if (!diffPatch || !hasLeafValues(diffPatch) || !isPlainObject(diffPatch)) return null;
+    return diffPatch as Tokens;
+  } catch (_err) {
+    return null;
+  }
+}
+
+export function applyTokenPatch(patch: Tokens | null | undefined): boolean {
+  if (!patch || !hasLeafValues(patch)) return false;
+  TOKENS = deepMergeTokens(TOKENS as unknown, patch as unknown) as Tokens;
+  return true;
+}
+
+export function applyVariableTokenDiffsWithOptions(options: VariableTokenDiffOptions): boolean {
+  return applyTokenPatch(getVariableTokenDiffWithOptions(options));
+}
+
+// ---------------------------------------------------------------------------
+// Theme access helpers (safe type narrowing)
+// ---------------------------------------------------------------------------
+
+/** Get color tokens for a named theme, or empty object if not found. */
+export function getThemeColors(tokens: Tokens, theme: string): TokenGroup {
+  const block = tokens[theme];
+  if (block && 'color' in block) {
+    const themeBlock = block as ThemeTokens;
+    return themeBlock.color || {};
+  }
+  return {};
+}
+
+/** Get radius tokens for a named theme, or empty object if not found. */
+export function getThemeRadius(tokens: Tokens, theme: string): TokenGroup {
+  const block = tokens[theme];
+  if (block && 'radius' in block) {
+    const themeBlock = block as ThemeTokens;
+    return themeBlock.radius || {};
+  }
+  return {};
+}
+
+/** Get spacing tokens for a named theme, falling back to primary. */
+export function getThemeSpacing(tokens: Tokens, theme: string): TokenGroup {
+  const block = tokens[theme];
+  if (block && 'spacing' in block) {
+    const themeBlock = block as ThemeTokens;
+    if (themeBlock.spacing && Object.keys(themeBlock.spacing).length) return themeBlock.spacing;
+  }
+  if (theme !== 'primary') return getThemeSpacing(tokens, 'primary');
+  return {};
+}
+
+/** Get fontSize tokens for a named theme, falling back to primary. */
+export function getThemeFontSize(tokens: Tokens, theme: string): TokenGroup {
+  const block = tokens[theme];
+  if (block && 'fontSize' in block) {
+    const themeBlock = block as ThemeTokens;
+    if (themeBlock.fontSize && Object.keys(themeBlock.fontSize).length) return themeBlock.fontSize;
+  }
+  if (theme !== 'primary') return getThemeFontSize(tokens, 'primary');
+  return {};
+}
+
+/** Get named theme keys in declaration order, excluding the core block. */
+export function getThemeNames(tokens: Tokens): string[] {
+  return Object.keys(tokens).filter((key) => {
+    if (key === 'core') return false;
+    const block = tokens[key];
+    if (!block || typeof block !== 'object') return false;
+    return Boolean(
+      ('color' in block && (block as ThemeTokens).color && Object.keys((block as ThemeTokens).color || {}).length) ||
+      ('font' in block && (block as ThemeTokens).font && Object.keys((block as ThemeTokens).font || {}).length) ||
+      ('radius' in block && (block as ThemeTokens).radius && Object.keys((block as ThemeTokens).radius || {}).length)
+    );
+  });
+}
+
+/** Get a font family for a specific theme and role ('sans' | 'heading' | 'mono').
+ *  Falls back: theme+role → theme+sans → primary+role → primary+sans → null. */
+export function getThemeFontFamily(tokens: Tokens, theme: string, role: string = 'sans'): string | null {
+  const block = tokens[theme];
+  if (block && 'font' in block) {
+    const font = (block as ThemeTokens).font;
+    if (font) {
+      const raw = (font as TokenGroup)[role] || (role !== 'sans' ? (font as TokenGroup).sans : null) || Object.values(font as TokenGroup)[0];
+      if (raw) {
+        const first = String(raw).split(',')[0].trim().replace(/^["']|["']$/g, '');
+        if (first) return first;
+      }
+    }
+  }
+  if (theme !== 'primary') return getThemeFontFamily(tokens, 'primary', role);
+  return null;
+}
+
+/** Get the primary sans-serif font family. Checks core.font first, then primary.font. */
+export function getCoreFontFamily(tokens: Tokens): string | null {
+  const core = tokens.core;
+  if (core && core.font) {
+    const raw = (core.font as TokenGroup).sans || Object.values(core.font as TokenGroup)[0];
+    if (raw) {
+      const first = String(raw).split(',')[0].trim().replace(/^["']|["']$/g, '');
+      if (first) return first;
+    }
+  }
+  return getThemeFontFamily(tokens, 'primary');
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+/** Extract current tokens from Figma Variables for export. */
+export function extractTokensForExport(): DTCGTokens {
+  applyVariableTokenDiffs();
+  return tokensToDTCG(TOKENS);
+}
+
+/**
+ * Convert flat TOKENS object to DTCG format (tokens.dtcg.json structure).
+ * DTCG uses { "$type": "color", "$value": "..." } for each token leaf.
+ */
+export function tokensToDTCG(tokens: Tokens): DTCGTokens {
+  // Static descriptions for known tokens
+  const descriptions: Record<string, string> = {
+    'core.font.sans': 'Custom sans-serif font override for Inkhouse brand',
+    'primary.radius.base': 'Base radius - all other radii are derived from this',
+    'primary.color.primary': 'Primary brand color (green)',
+    'secondary.color.primary': 'Secondary brand color (blue)',
+    'tertiary.color.primary': 'Tertiary brand color (orange)',
+    'tertiary.font.sans': 'Tertiary theme sans-serif font override'
+  };
+
+  const dtcg: DTCGTokens = {
+    "$metadata": {
+      "description": "Inkhouse custom design tokens. Only includes tokens that override or extend Tailwind defaults.",
+      "note": "Standard Tailwind spacing, font-weights, tracking, and type scale are NOT included - those come from Tailwind itself."
+    }
+  };
+
+  // Core (font)
+  if (tokens.core) {
+    dtcg.core = {} as Record<string, any>;
+    if (tokens.core.font) {
+      dtcg.core.font = {} as Record<string, DTCGEntry>;
+      for (const fk in tokens.core.font) {
+        const fontEntry: DTCGEntry = {
+          "$type": "fontFamily",
+          "$value": tokens.core.font[fk]
+        };
+        const fontDesc = descriptions['core.font.' + fk];
+        if (fontDesc) fontEntry["$description"] = fontDesc;
+        dtcg.core.font[fk] = fontEntry;
+      }
+    }
+  }
+
+  // Theme groups (primary, secondary, etc.)
+  const themes = Object.keys(tokens).filter((key) => key !== 'core');
+  for (let ti = 0; ti < themes.length; ti++) {
+    const themeName = themes[ti];
+    if (!tokens[themeName]) continue;
+    dtcg[themeName] = {} as Record<string, any>;
+
+    const themeBlock = tokens[themeName] as ThemeTokens;
+
+    // Radius
+    if (themeBlock.radius) {
+      dtcg[themeName].radius = {} as Record<string, DTCGEntry>;
+      for (const rk in themeBlock.radius) {
+        const radiusEntry: DTCGEntry = {
+          "$type": "dimension",
+          "$value": themeBlock.radius[rk]
+        };
+        const radiusDesc = descriptions[themeName + '.radius.' + rk];
+        if (radiusDesc) radiusEntry["$description"] = radiusDesc;
+        dtcg[themeName].radius[rk] = radiusEntry;
+      }
+    }
+
+    // Font
+    if (themeBlock.font) {
+      dtcg[themeName].font = {} as Record<string, DTCGEntry>;
+      for (const fk in themeBlock.font) {
+        const fontEntry: DTCGEntry = {
+          "$type": "fontFamily",
+          "$value": themeBlock.font[fk]
+        };
+        const fontDesc = descriptions[themeName + '.font.' + fk];
+        if (fontDesc) fontEntry["$description"] = fontDesc;
+        dtcg[themeName].font[fk] = fontEntry;
+      }
+    }
+
+    // Color
+    if (themeBlock.color) {
+      dtcg[themeName].color = {} as Record<string, DTCGEntry>;
+      for (const ck in themeBlock.color) {
+        const colorEntry: DTCGEntry = {
+          "$type": "color",
+          "$value": themeBlock.color[ck]
+        };
+        const colorDesc = descriptions[themeName + '.color.' + ck];
+        if (colorDesc) colorEntry["$description"] = colorDesc;
+        dtcg[themeName].color[ck] = colorEntry;
+      }
+    }
+
+    // Spacing
+    if (themeBlock.spacing) {
+      dtcg[themeName].spacing = {} as Record<string, DTCGEntry>;
+      for (const sk in themeBlock.spacing) {
+        dtcg[themeName].spacing[sk] = { "$type": "dimension", "$value": themeBlock.spacing[sk] };
+      }
+    }
+
+    // FontSize
+    if (themeBlock.fontSize) {
+      dtcg[themeName].fontSize = {} as Record<string, DTCGEntry>;
+      for (const fk in themeBlock.fontSize) {
+        dtcg[themeName].fontSize[fk] = { "$type": "dimension", "$value": themeBlock.fontSize[fk] };
+      }
+    }
+
+    // Shadow
+    if (themeBlock.shadow) {
+      dtcg[themeName].shadow = {} as Record<string, DTCGEntry>;
+      for (const sk in themeBlock.shadow) {
+        dtcg[themeName].shadow[sk] = { "$type": "shadow", "$value": themeBlock.shadow[sk] };
+      }
+    }
+  }
+
+  return dtcg;
+}
+
+/**
+ * Build tokens.css content.
+ * Generates CSS custom properties for primary (:root) and additional theme
+ * overrides (:root[data-theme="<theme>"]).
+ */
+export function tokensToCSS(tokens: Tokens): string {
+  const lines: string[] = [];
+  lines.push('/* Auto-generated from design-tokens/tokens.dtcg.json */');
+  lines.push('/* Custom Inkhouse tokens only - standard Tailwind values come from Tailwind itself */');
+
+  const primaryTheme = (tokens.primary as ThemeTokens) || {};
+  const primaryColors = primaryTheme.color ? primaryTheme.color : {};
+  const primaryFonts = primaryTheme.font ? primaryTheme.font : {};
+  const core = tokens.core || {};
+  const primaryRadius = primaryTheme.radius ? primaryTheme.radius : {};
+  const primarySpacing = primaryTheme.spacing ? primaryTheme.spacing : {};
+  const primaryFontSize = primaryTheme.fontSize ? primaryTheme.fontSize : {};
+  const primaryShadow = primaryTheme.shadow ? primaryTheme.shadow : {};
+  const radiusBase = primaryRadius.base || '0.5rem';
+  const themeNames = Object.keys(tokens).filter((key) => key !== 'core');
+
+  lines.push('');
+  lines.push(':root {');
+  lines.push('  --radius: ' + radiusBase + ';');
+
+  // Named radius scale
+  for (const rk in primaryRadius) {
+    if (rk === 'base') continue;
+    lines.push('  --radius-' + rk + ': ' + primaryRadius[rk] + ';');
+  }
+
+  // Spacing scale
+  for (const sk in primarySpacing) {
+    lines.push('  --spacing-' + sk + ': ' + primarySpacing[sk] + ';');
+  }
+
+  // FontSize scale
+  for (const fk in primaryFontSize) {
+    lines.push('  --text-' + fk + ': ' + primaryFontSize[fk] + ';');
+  }
+
+  // Shadow scale
+  for (const sk in primaryShadow) {
+    const cssKey = sk === 'DEFAULT' ? 'shadow' : 'shadow-' + sk;
+    lines.push('  --' + cssKey + ': ' + primaryShadow[sk] + ';');
+  }
+
+  // Custom font family
+  const fonts = core.font || {};
+  for (const fname in fonts) {
+    lines.push('  --font-' + fname + ': ' + fonts[fname] + ';');
+  }
+  for (const fname in primaryFonts) {
+    lines.push('  --font-' + fname + ': ' + primaryFonts[fname] + ';');
+  }
+
+  // Primary theme colors
+  for (const cname in primaryColors) {
+    lines.push('  --' + cname + ': ' + primaryColors[cname] + ';');
+  }
+  lines.push('}');
+
+  for (let ti = 0; ti < themeNames.length; ti++) {
+    const themeName = themeNames[ti];
+    if (themeName === 'primary') continue;
+    const themeBlock = (tokens[themeName] as ThemeTokens) || {};
+    const themeColors = themeBlock.color || {};
+    const themeFonts = themeBlock.font || {};
+    const themeRadius = themeBlock.radius || {};
+    if (!Object.keys(themeColors).length && !Object.keys(themeFonts).length && !Object.keys(themeRadius).length) continue;
+    lines.push('');
+    lines.push(':root[data-theme="' + themeName + '"] {');
+    if (themeRadius.base) {
+      lines.push('  --radius: ' + themeRadius.base + ';');
+    }
+    for (const fname in themeFonts) {
+      lines.push('  --font-' + fname + ': ' + themeFonts[fname] + ';');
+    }
+    for (const sname in themeColors) {
+      lines.push('  --' + sname + ': ' + themeColors[sname] + ';');
+    }
+    lines.push('}');
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}