inkhouse 0.1.0-beta.0

package/src/variables.ts

@@ -0,0 +1,1042 @@
+import { TOKENS } from './tokens';
+import { parseColor, colorToLabel, debug, normalizeThemeName, normalizeGroupName, normalizeSizeValue } from './colors';
+
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+
+let _variableCollection: any = null;       // Single-collection (paid) or default-theme collection (free)
+let _themeCollections: Record<string, any> = {}; // Free-plan: one collection per theme
+let _variableModeIds: Record<string, string> = {}; // Multi-mode: theme -> modeId
+let _defaultThemeName = 'primary';
+let _colorVariables: Record<string, any> = {}; // default theme tokenKey -> Variable
+let _themeColorVariables: Record<string, Record<string, any>> = {}; // theme -> tokenKey -> Variable
+let _radiusVariables: Record<string, any> = {};            // key -> FLOAT Variable (radius/sm, radius/md …)
+let _fontVariables: Record<string, any> = {};              // key -> STRING Variable (font/sans …)
+let _spacingVariables: Record<string, any> = {};           // key -> FLOAT Variable (spacing/sm, spacing/lg …)
+let _fontSizeVariables: Record<string, any> = {};          // key -> FLOAT Variable (fontSize/sm, fontSize/xl …)
+let _useMultiMode = false;            // true if paid plan (multi-mode available)
+
+// ---------------------------------------------------------------------------
+// Functions
+// ---------------------------------------------------------------------------
+
+function normalizeCustomThemeName(value: unknown): string | null {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  const known = normalizeThemeName(raw);
+  if (known) return known;
+  const slug = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!slug) return null;
+  if (/^mode[-_ ]?\d+$/i.test(slug)) return null;
+  if (slug === 'default') return 'primary';
+  return slug;
+}
+
+function getThemeDisplayName(theme: string): string {
+  return String(theme || '')
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function getThemeNamesFromTokens(): string[] {
+  const names = Object.keys(TOKENS || {}).filter((key) => {
+    if (key === 'core') return false;
+    const block = (TOKENS as any)[key];
+    if (!block || typeof block !== 'object') return false;
+    return Boolean(
+      block.color || block.radius || block.font || block.spacing || block.fontSize || block.shadow
+    );
+  });
+  if (names.length === 0) return ['primary'];
+  if (!names.includes('primary')) return names;
+  return ['primary'].concat(names.filter((name) => name !== 'primary'));
+}
+
+function getThemeGroup(theme: string, group: string): Record<string, any> {
+  const block = ((TOKENS as any)[theme] && typeof (TOKENS as any)[theme] === 'object')
+    ? (TOKENS as any)[theme]
+    : {};
+  const value = block[group];
+  return value && typeof value === 'object' ? value : {};
+}
+
+function findCollectionByName(collections: any[], name: string): any {
+  const needle = String(name || '').toLowerCase();
+  return collections.find((c: any) => String(c.name || '').toLowerCase() === needle) || null;
+}
+
+export function resolveVariableValue(value: any, modeId?: string, visited?: Record<string, boolean>): any {
+  if (!value) return null;
+  if (value.type === 'VARIABLE_ALIAS' && value.id) {
+    if (!visited) visited = {};
+    if (visited[value.id]) return null;
+    visited[value.id] = true;
+    if (!figma.variables || !figma.variables.getVariableById) return null;
+    const target = figma.variables.getVariableById(value.id);
+    if (!target || !target.valuesByMode) return null;
+    const vbm = target.valuesByMode;
+    const direct = (modeId && vbm[modeId] !== undefined) ? vbm[modeId] : vbm[Object.keys(vbm)[0]];
+    return resolveVariableValue(direct, modeId, visited);
+  }
+  return value;
+}
+
+export function readVariableTokens(): any {
+  if (!figma.variables || !figma.variables.getLocalVariables) {
+    debug('Variables API unavailable, using embedded tokens.');
+    return null;
+  }
+  const vars = figma.variables.getLocalVariables();
+  if (!vars || !vars.length) {
+    debug('No local variables found, using embedded tokens.');
+    return null;
+  }
+  const collections = figma.variables.getLocalVariableCollections ? figma.variables.getLocalVariableCollections() : [];
+  const collectionById: Record<string, any> = {};
+  const modeNameById: Record<string, string> = {};
+  for (const col of collections) {
+    collectionById[col.id] = col;
+    if (col.modes) {
+      for (const mode of col.modes) {
+        modeNameById[mode.modeId] = mode.name;
+      }
+    }
+  }
+
+  // Full token structure read back from Figma Variables.
+  // Keep this dynamic: theme keys can be arbitrary (not just primary/secondary).
+  const out: Record<string, any> = {
+    core: { font: {} },
+    primary: { color: {}, radius: {}, font: {}, spacing: {}, fontSize: {} },
+  };
+  let wrote = false;
+
+  function ensureTheme(themeName: string): Record<string, any> {
+    if (!out[themeName] || typeof out[themeName] !== 'object') {
+      out[themeName] = {};
+    }
+    const block = out[themeName] as Record<string, any>;
+    if (!block.color || typeof block.color !== 'object') block.color = {};
+    if (!block.radius || typeof block.radius !== 'object') block.radius = {};
+    if (!block.font || typeof block.font !== 'object') block.font = {};
+    if (!block.spacing || typeof block.spacing !== 'object') block.spacing = {};
+    if (!block.fontSize || typeof block.fontSize !== 'object') block.fontSize = {};
+    return block;
+  }
+
+  function assign(theme: string, group: string, parts: string[], value: any): void {
+    if (!value) return;
+    const key = parts && parts.length ? parts.join('-') : null;
+    if (!key) return;
+
+    const resolvedTheme = theme && theme !== 'core' ? theme : 'primary';
+    let target: Record<string, any>;
+
+    if (group === 'color') {
+      target = ensureTheme(resolvedTheme).color;
+      target[key] = value;
+      wrote = true;
+      return;
+    }
+    if (group === 'radius') {
+      target = ensureTheme(resolvedTheme).radius;
+      target[key] = normalizeSizeValue(value);
+      wrote = true;
+      return;
+    }
+    if (group === 'font') {
+      // Route unscoped fonts into core, scoped fonts into their theme block.
+      if (!theme || theme === 'core') target = out.core.font;
+      else target = ensureTheme(theme).font;
+      target[key] = String(value);
+      wrote = true;
+      return;
+    }
+    if (group === 'spacing') {
+      target = ensureTheme(resolvedTheme).spacing;
+      target[key] = normalizeSizeValue(value);
+      wrote = true;
+      return;
+    }
+    if (group === 'fontsize') {
+      target = ensureTheme(resolvedTheme).fontSize;
+      target[key] = normalizeSizeValue(value);
+      wrote = true;
+      return;
+    }
+    // Ignore fontWeight, tracking, typography - these come from Tailwind
+  }
+
+  for (const variable of vars) {
+    const rawName = String(variable.name || '');
+    if (!rawName) continue;
+    const parts = rawName.split(/[./]/).filter(Boolean);
+    if (!parts.length) continue;
+    const firstPartIsGroup = !!normalizeGroupName(parts[0]);
+    let theme = firstPartIsGroup ? null : (normalizeThemeName(parts[0]) || normalizeCustomThemeName(parts[0]));
+    let cursor = parts.slice(theme ? 1 : 0);
+    let group = normalizeGroupName(cursor[0]);
+
+    if (!group) {
+      // Backward compatibility: older variable sets used flat color names like
+      // `primary`, `foreground` (without `color/` prefix). Infer group by type.
+      if (String((variable as any).resolvedType || '').toUpperCase() === 'COLOR') {
+        group = 'color';
+        if (cursor.length === 0) {
+          theme = null;
+          cursor = parts.slice(0);
+        }
+      } else {
+        continue;
+      }
+    } else {
+      cursor = cursor.slice(1);
+    }
+
+    const valuesByMode = variable.valuesByMode || {};
+    const modeIds = Object.keys(valuesByMode);
+    if (!modeIds.length) continue;
+
+    const collection = collectionById[variable.variableCollectionId];
+    const isSingleModeCollection = !!(collection && Array.isArray(collection.modes) && collection.modes.length === 1);
+    for (const modeId of modeIds) {
+      const modeName = modeNameById[modeId];
+      const modeTheme =
+        theme ||
+        normalizeThemeName(modeName) ||
+        normalizeCustomThemeName(modeName) ||
+        (isSingleModeCollection
+          ? (
+              normalizeThemeName(collection && collection.name) ||
+              normalizeCustomThemeName(collection && collection.name)
+            )
+          : null);
+      if (!modeTheme && !isSingleModeCollection) {
+        // Ignore unknown/legacy extra modes in multi-mode collections.
+        continue;
+      }
+      const value = resolveVariableValue(valuesByMode[modeId], modeId);
+      const finalTheme = modeTheme || (group === 'font' ? 'core' : 'primary');
+      assign(finalTheme, group, cursor, value);
+      if (theme) break;
+    }
+  }
+
+  return wrote ? out : null;
+}
+
+export function upsertPaintStyle(name: string, color: { r: number; g: number; b: number; a?: number }): any {
+  const styles = figma.getLocalPaintStyles();
+  const existing = styles.find((s: any) => s.name === name);
+  const paint = { type: 'SOLID' as const, color: { r: color.r, g: color.g, b: color.b }, opacity: (color.a == null ? 1 : color.a) };
+  if (existing) {
+    existing.paints = [paint];
+    return existing;
+  } else {
+    const s = figma.createPaintStyle();
+    s.name = name;
+    s.paints = [paint];
+    return s;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shadow Effect Styles
+// ---------------------------------------------------------------------------
+
+interface ShadowLayer {
+  inset: boolean;
+  x: number;
+  y: number;
+  blur: number;
+  spread: number;
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/**
+ * Parse a CSS `rgb(r g b / a)` or `rgba(r, g, b, a)` color string into 0–1 floats.
+ */
+function parseCssShadowColor(raw: string): { r: number; g: number; b: number; a: number } {
+  // rgb(r g b / a) — CSS Color Level 4
+  const lvl4 = raw.match(/^rgb\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\/\s*([\d.]+)\s*\)$/);
+  if (lvl4) {
+    return {
+      r: parseFloat(lvl4[1]) / 255,
+      g: parseFloat(lvl4[2]) / 255,
+      b: parseFloat(lvl4[3]) / 255,
+      a: parseFloat(lvl4[4]),
+    };
+  }
+  // rgba(r, g, b, a)
+  const legacy = raw.match(/^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)$/);
+  if (legacy) {
+    return {
+      r: parseFloat(legacy[1]) / 255,
+      g: parseFloat(legacy[2]) / 255,
+      b: parseFloat(legacy[3]) / 255,
+      a: legacy[4] != null ? parseFloat(legacy[4]) : 1,
+    };
+  }
+  return { r: 0, g: 0, b: 0, a: 0.1 };
+}
+
+/**
+ * Parse a CSS box-shadow value string (possibly multi-layer, comma-separated)
+ * into an array of ShadowLayer objects.
+ * Format per layer: [inset] <offset-x> <offset-y> [blur] [spread] <color>
+ */
+function parseCssBoxShadow(value: string): ShadowLayer[] {
+  // Split on commas that are NOT inside parentheses
+  const layers: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < value.length; i++) {
+    if (value[i] === '(') depth++;
+    else if (value[i] === ')') depth--;
+    else if (value[i] === ',' && depth === 0) {
+      layers.push(value.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  layers.push(value.slice(start).trim());
+
+  const result: ShadowLayer[] = [];
+  for (const layer of layers) {
+    if (!layer) continue;
+    const inset = /\binset\b/.test(layer);
+    const withoutInset = layer.replace(/\binset\b/, '').trim();
+
+    // Extract color: find rgb/rgba(...) or hex
+    const colorMatch = withoutInset.match(/(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8})/);
+    const colorStr = colorMatch ? colorMatch[1] : 'rgb(0 0 0 / 0.1)';
+    const withoutColor = withoutInset.replace(colorStr, '').trim();
+
+    const lengths = withoutColor.split(/\s+/).filter(Boolean);
+    const px = (s: string): number => {
+      if (!s) return 0;
+      if (s.endsWith('px')) return parseFloat(s);
+      if (s === '0') return 0;
+      return parseFloat(s) || 0;
+    };
+
+    const color = parseCssShadowColor(colorStr);
+    result.push({
+      inset,
+      x: px(lengths[0] || '0'),
+      y: px(lengths[1] || '0'),
+      blur: px(lengths[2] || '0'),
+      spread: px(lengths[3] || '0'),
+      r: color.r,
+      g: color.g,
+      b: color.b,
+      a: color.a,
+    });
+  }
+  return result;
+}
+
+/**
+ * Create or update a Figma Effect Style for a shadow token.
+ * Name format: "shadow/sm", "shadow/DEFAULT" → "shadow", etc.
+ */
+function upsertEffectStyle(name: string, cssValue: string): void {
+  if (!figma.getLocalEffectStyles) return;
+  const layers = parseCssBoxShadow(cssValue);
+  if (!layers.length) return;
+
+  const effects: any[] = [];
+  for (const l of layers) {
+    effects.push({
+      type: l.inset ? 'INNER_SHADOW' : 'DROP_SHADOW',
+      color: { r: l.r, g: l.g, b: l.b, a: l.a },
+      offset: { x: l.x, y: l.y },
+      radius: l.blur,
+      spread: l.spread,
+      visible: true,
+      blendMode: 'NORMAL',
+    });
+  }
+
+  const existing = figma.getLocalEffectStyles().find((s: any) => s.name === name);
+  if (existing) {
+    existing.effects = effects;
+  } else {
+    const s = figma.createEffectStyle();
+    s.name = name;
+    s.effects = effects;
+  }
+}
+
+/**
+ * Create/update Figma Effect Styles for all shadow tokens.
+ */
+export function populateShadowStyles(shadowTokens: Record<string, string>): void {
+  for (const key in shadowTokens) {
+    const styleName = key === 'DEFAULT' ? 'shadow' : 'shadow/' + key;
+    upsertEffectStyle(styleName, shadowTokens[key]);
+  }
+}
+
+/**
+ * Remove stale paint styles from previous runs (LIGHT, DARK, PRIMARY, SECONDARY groups)
+ */
+export function removeStaleColorStyles(): void {
+  const styles = figma.getLocalPaintStyles();
+  const stalePrefix = ['LIGHT/', 'DARK/', 'PRIMARY/', 'SECONDARY/'];
+  for (const s of styles) {
+    if (stalePrefix.some(p => s.name.startsWith(p))) {
+      s.remove();
+    }
+  }
+}
+
+/**
+ * Populate variables in a collection for a given theme's color tokens.
+ */
+export function populateColorVariables(collection: any, modeId: string, colorTokens: Record<string, any>, outMap: Record<string, any>): void {
+  // Index existing variables in this collection
+  const existingVars = figma.variables.getLocalVariables('COLOR');
+  const existingByName: Record<string, any> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) {
+      existingByName[v.name] = v;
+    }
+  }
+
+  for (const key in colorTokens) {
+    const varName = 'color/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'COLOR');
+    }
+    const rgb = parseColor(colorTokens[key]);
+    variable.setValueForMode(modeId, { r: rgb.r, g: rgb.g, b: rgb.b, a: rgb.a == null ? 1 : rgb.a });
+    outMap[key] = variable;
+  }
+}
+
+/**
+ * Populate FLOAT radius variables in a collection for a given mode.
+ */
+export function populateRadiusVariables(collection: any, modeId: string, radiusTokens: Record<string, string>, outMap: Record<string, any>): void {
+  const existingVars = figma.variables.getLocalVariables('FLOAT');
+  const existingByName: Record<string, any> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) {
+      existingByName[v.name] = v;
+    }
+  }
+  for (const key in radiusTokens) {
+    const varName = 'radius/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'FLOAT');
+    }
+    variable.setValueForMode(modeId, pxFromSizeToken(radiusTokens[key]));
+    outMap[key] = variable;
+  }
+}
+
+/**
+ * Populate STRING font-family variables in a collection for a given mode.
+ */
+export function populateFontVariables(collection: any, modeId: string, fontTokens: Record<string, string>, outMap: Record<string, any>): void {
+  const existingVars = figma.variables.getLocalVariables('STRING');
+  const existingByName: Record<string, any> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) {
+      existingByName[v.name] = v;
+    }
+  }
+  for (const key in fontTokens) {
+    const varName = 'font/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'STRING');
+    }
+    // Store the first family name only (no fallback stack in Figma)
+    const first = String(fontTokens[key]).split(',')[0].trim().replace(/^["']|["']$/g, '');
+    variable.setValueForMode(modeId, first);
+    outMap[key] = variable;
+  }
+}
+
+/**
+ * Populate FLOAT spacing variables in a collection for a given mode.
+ */
+export function populateSpacingVariables(collection: any, modeId: string, spacingTokens: Record<string, string>, outMap: Record<string, any>): void {
+  const existingVars = figma.variables.getLocalVariables('FLOAT');
+  const existingByName: Record<string, any> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) existingByName[v.name] = v;
+  }
+  for (const key in spacingTokens) {
+    const varName = 'spacing/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'FLOAT');
+    }
+    variable.setValueForMode(modeId, pxFromSizeToken(spacingTokens[key]));
+    outMap[key] = variable;
+  }
+}
+
+/**
+ * Populate FLOAT font-size variables in a collection for a given mode.
+ */
+export function populateFontSizeVariables(collection: any, modeId: string, fontSizeTokens: Record<string, string>, outMap: Record<string, any>): void {
+  const existingVars = figma.variables.getLocalVariables('FLOAT');
+  const existingByName: Record<string, any> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) existingByName[v.name] = v;
+  }
+  for (const key in fontSizeTokens) {
+    const varName = 'fontSize/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'FLOAT');
+    }
+    variable.setValueForMode(modeId, pxFromSizeToken(fontSizeTokens[key]));
+    outMap[key] = variable;
+  }
+}
+
+/**
+ * Create or update color variables.
+ * Tries multi-mode first (paid plans). Falls back to two collections (free plan).
+ */
+export function createOrUpdateVariables(): void {
+  if (!figma.variables || !figma.variables.createVariableCollection) {
+    debug('Variables API not available, falling back to paint styles');
+    createOrUpdateStylesFallback();
+    return;
+  }
+
+  const themeNames = getThemeNamesFromTokens();
+  _defaultThemeName = themeNames.includes('primary') ? 'primary' : themeNames[0];
+  const defaultTheme = _defaultThemeName;
+  const defaultDisplayName = getThemeDisplayName(defaultTheme);
+
+  const themeColors: Record<string, Record<string, any>> = {};
+  const themeRadius: Record<string, Record<string, any>> = {};
+  const themeFont: Record<string, Record<string, any>> = {};
+  const themeSpacing: Record<string, Record<string, any>> = {};
+  const themeFontSize: Record<string, Record<string, any>> = {};
+  for (const theme of themeNames) {
+    themeColors[theme] = getThemeGroup(theme, 'color');
+    themeRadius[theme] = getThemeGroup(theme, 'radius');
+    themeFont[theme] = getThemeGroup(theme, 'font');
+    themeSpacing[theme] = getThemeGroup(theme, 'spacing');
+    themeFontSize[theme] = getThemeGroup(theme, 'fontSize');
+  }
+
+  _themeCollections = {};
+  _themeColorVariables = {};
+  _variableModeIds = {};
+  _colorVariables = {};
+  _radiusVariables = {};
+  _fontVariables = {};
+  _spacingVariables = {};
+  _fontSizeVariables = {};
+
+  const collections = figma.variables.getLocalVariableCollections();
+
+  function ensureThemeModes(collection: any): boolean {
+    const map: Record<string, string> = {};
+    const modes = Array.isArray(collection.modes) ? collection.modes.slice() : [];
+    const unclaimed: string[] = modes.map((mode: any) => mode.modeId);
+    const removeUnclaimed = (modeId: string): void => {
+      const idx = unclaimed.indexOf(modeId);
+      if (idx >= 0) unclaimed.splice(idx, 1);
+    };
+
+    for (const mode of modes) {
+      const mapped = normalizeThemeName(mode.name) || normalizeCustomThemeName(mode.name);
+      if (mapped && themeNames.includes(mapped) && !map[mapped]) {
+        map[mapped] = mode.modeId;
+        removeUnclaimed(mode.modeId);
+      }
+    }
+
+    for (const theme of themeNames) {
+      if (map[theme]) continue;
+      if (unclaimed.length > 0) {
+        const modeId = unclaimed.shift() as string;
+        try {
+          collection.renameMode(modeId, getThemeDisplayName(theme));
+        } catch (_e) {}
+        map[theme] = modeId;
+        continue;
+      }
+      try {
+        map[theme] = collection.addMode(getThemeDisplayName(theme));
+      } catch (e: any) {
+        debug('Cannot add mode (free plan): ' + (e.message || e));
+        return false;
+      }
+    }
+
+    for (const theme of themeNames) {
+      const modeId = map[theme];
+      if (!modeId) continue;
+      try {
+        collection.renameMode(modeId, getThemeDisplayName(theme));
+      } catch (_e) {}
+    }
+
+    // Rename leftover modes to neutral names so they don't map to semantic themes.
+    let legacyIndex = 1;
+    for (const modeId of unclaimed) {
+      try {
+        collection.renameMode(modeId, 'Mode ' + legacyIndex++);
+      } catch (_e) {}
+    }
+
+    _variableModeIds = map;
+    return true;
+  }
+
+  _variableCollection =
+    findCollectionByName(collections, 'Design Tokens') ||
+    findCollectionByName(collections, defaultDisplayName) ||
+    findCollectionByName(collections, 'Primary');
+
+  _useMultiMode = false;
+  if (_variableCollection) {
+    _useMultiMode = ensureThemeModes(_variableCollection);
+  } else {
+    _variableCollection = figma.variables.createVariableCollection('Design Tokens');
+    _useMultiMode = ensureThemeModes(_variableCollection);
+  }
+
+  if (_useMultiMode) {
+    const allColorKeys: Record<string, boolean> = {};
+    const allRadiusKeys: Record<string, boolean> = {};
+    const allFontKeys: Record<string, boolean> = {};
+    const allSpacingKeys: Record<string, boolean> = {};
+    const allFontSizeKeys: Record<string, boolean> = {};
+    for (const theme of themeNames) {
+      for (const key in themeColors[theme]) allColorKeys[key] = true;
+      for (const key in themeRadius[theme]) allRadiusKeys[key] = true;
+      for (const key in themeFont[theme]) allFontKeys[key] = true;
+      for (const key in themeSpacing[theme]) allSpacingKeys[key] = true;
+      for (const key in themeFontSize[theme]) allFontSizeKeys[key] = true;
+    }
+
+    const existingColorVars = figma.variables.getLocalVariables('COLOR');
+    const existingColorByName: Record<string, any> = {};
+    for (const v of existingColorVars) {
+      if (v.variableCollectionId === _variableCollection.id) {
+        existingColorByName[v.name] = v;
+      }
+    }
+
+    const existingFloatVars = figma.variables.getLocalVariables('FLOAT');
+    const existingFloatByName: Record<string, any> = {};
+    for (const v of existingFloatVars) {
+      if (v.variableCollectionId === _variableCollection.id) {
+        existingFloatByName[v.name] = v;
+      }
+    }
+
+    const existingStringVars = figma.variables.getLocalVariables('STRING');
+    const existingStringByName: Record<string, any> = {};
+    for (const v of existingStringVars) {
+      if (v.variableCollectionId === _variableCollection.id) {
+        existingStringByName[v.name] = v;
+      }
+    }
+
+    for (const theme of themeNames) _themeColorVariables[theme] = {};
+
+    const defaultColors = themeColors[defaultTheme] || {};
+    for (const key in allColorKeys) {
+      const varName = 'color/' + key;
+      let variable = existingColorByName[varName];
+      if (!variable) variable = figma.variables.createVariable(varName, _variableCollection, 'COLOR');
+
+      for (const theme of themeNames) {
+        const modeId = _variableModeIds[theme];
+        if (!modeId) continue;
+        const value = (themeColors[theme] && themeColors[theme][key] !== undefined)
+          ? themeColors[theme][key]
+          : defaultColors[key];
+        if (value === undefined) continue;
+        const rgb = parseColor(value);
+        variable.setValueForMode(modeId, { r: rgb.r, g: rgb.g, b: rgb.b, a: rgb.a == null ? 1 : rgb.a });
+        _themeColorVariables[theme][key] = variable;
+      }
+    }
+    _colorVariables = _themeColorVariables[defaultTheme] || {};
+
+    const defaultRadius = themeRadius[defaultTheme] || {};
+    for (const key in allRadiusKeys) {
+      const varName = 'radius/' + key;
+      let variable = existingFloatByName[varName];
+      if (!variable) variable = figma.variables.createVariable(varName, _variableCollection, 'FLOAT');
+
+      for (const theme of themeNames) {
+        const modeId = _variableModeIds[theme];
+        if (!modeId) continue;
+        const value = (themeRadius[theme] && themeRadius[theme][key] !== undefined)
+          ? themeRadius[theme][key]
+          : defaultRadius[key];
+        if (value === undefined) continue;
+        variable.setValueForMode(modeId, pxFromSizeToken(value));
+      }
+      _radiusVariables[key] = variable;
+    }
+
+    const defaultFont = themeFont[defaultTheme] || {};
+    for (const key in allFontKeys) {
+      const varName = 'font/' + key;
+      let variable = existingStringByName[varName];
+      if (!variable) variable = figma.variables.createVariable(varName, _variableCollection, 'STRING');
+
+      for (const theme of themeNames) {
+        const modeId = _variableModeIds[theme];
+        if (!modeId) continue;
+        const value = (themeFont[theme] && themeFont[theme][key] !== undefined)
+          ? themeFont[theme][key]
+          : defaultFont[key];
+        if (value === undefined) continue;
+        const first = String(value).split(',')[0].trim().replace(/^["']|["']$/g, '');
+        variable.setValueForMode(modeId, first);
+      }
+      _fontVariables[key] = variable;
+    }
+
+    const defaultSpacing = themeSpacing[defaultTheme] || {};
+    for (const key in allSpacingKeys) {
+      const varName = 'spacing/' + key;
+      let variable = existingFloatByName[varName];
+      if (!variable) variable = figma.variables.createVariable(varName, _variableCollection, 'FLOAT');
+
+      for (const theme of themeNames) {
+        const modeId = _variableModeIds[theme];
+        if (!modeId) continue;
+        const value = (themeSpacing[theme] && themeSpacing[theme][key] !== undefined)
+          ? themeSpacing[theme][key]
+          : defaultSpacing[key];
+        if (value === undefined) continue;
+        variable.setValueForMode(modeId, pxFromSizeToken(value));
+      }
+      _spacingVariables[key] = variable;
+    }
+
+    const defaultFontSize = themeFontSize[defaultTheme] || {};
+    for (const key in allFontSizeKeys) {
+      const varName = 'fontSize/' + key;
+      let variable = existingFloatByName[varName];
+      if (!variable) variable = figma.variables.createVariable(varName, _variableCollection, 'FLOAT');
+
+      for (const theme of themeNames) {
+        const modeId = _variableModeIds[theme];
+        if (!modeId) continue;
+        const value = (themeFontSize[theme] && themeFontSize[theme][key] !== undefined)
+          ? themeFontSize[theme][key]
+          : defaultFontSize[key];
+        if (value === undefined) continue;
+        variable.setValueForMode(modeId, pxFromSizeToken(value));
+      }
+      _fontSizeVariables[key] = variable;
+    }
+
+    for (const col of collections) {
+      if (!col || col.id === _variableCollection.id) continue;
+      const mapped = normalizeThemeName(col.name) || normalizeCustomThemeName(col.name);
+      if (mapped && themeNames.includes(mapped)) {
+        try { col.remove(); } catch (_e) {}
+      }
+    }
+
+    debug(
+      'Multi-mode: ' +
+      themeNames.length +
+      ' themes, ' +
+      Object.keys(_colorVariables).length + ' color + ' +
+      Object.keys(_radiusVariables).length + ' radius + ' +
+      Object.keys(_fontVariables).length + ' font variables'
+    );
+    return;
+  }
+
+  // --- Free plan fallback: one collection per theme (color), default theme for shared scales ---
+  const existingCollections = figma.variables.getLocalVariableCollections();
+  for (const theme of themeNames) {
+    const displayName = getThemeDisplayName(theme);
+    let collection = findCollectionByName(existingCollections, displayName);
+    if (!collection && theme === defaultTheme && _variableCollection) {
+      collection = _variableCollection;
+    }
+    if (!collection) {
+      collection = figma.variables.createVariableCollection(displayName);
+    } else if (collection.name !== displayName) {
+      collection.name = displayName;
+    }
+    _themeCollections[theme] = collection;
+    _themeColorVariables[theme] = {};
+
+    const modeId = collection.modes[0].modeId;
+    populateColorVariables(collection, modeId, themeColors[theme] || {}, _themeColorVariables[theme]);
+
+    if (theme === defaultTheme) {
+      _variableCollection = collection;
+      _variableModeIds[theme] = modeId;
+      _colorVariables = _themeColorVariables[theme];
+      populateRadiusVariables(collection, modeId, themeRadius[theme] || {}, _radiusVariables);
+      populateFontVariables(collection, modeId, themeFont[theme] || {}, _fontVariables);
+      populateSpacingVariables(collection, modeId, themeSpacing[theme] || {}, _spacingVariables);
+      populateFontSizeVariables(collection, modeId, themeFontSize[theme] || {}, _fontSizeVariables);
+    }
+  }
+
+  // Remove stale plugin theme collections no longer present in tokens.
+  for (const collection of existingCollections) {
+    if (!collection) continue;
+    const mapped = normalizeThemeName(collection.name) || normalizeCustomThemeName(collection.name);
+    if (!mapped) continue;
+    if (themeNames.includes(mapped)) continue;
+    if (collection.id === (_variableCollection && _variableCollection.id)) continue;
+    const varsInCollection = figma.variables.getLocalVariables().filter((v: any) => v.variableCollectionId === collection.id);
+    const looksLikePluginThemeCollection = varsInCollection.some((v: any) =>
+      /^color\//.test(String(v.name || '')) ||
+      /^radius\//.test(String(v.name || '')) ||
+      /^font\//.test(String(v.name || '')) ||
+      /^spacing\//.test(String(v.name || '')) ||
+      /^fontSize\//.test(String(v.name || ''))
+    );
+    if (!looksLikePluginThemeCollection) continue;
+    try { collection.remove(); } catch (_e) {}
+  }
+
+  debug(
+    'Free plan: ' +
+    themeNames.length +
+    ' theme collections, ' +
+    Object.keys(_colorVariables).length + ' default-theme colors'
+  );
+}
+
+/**
+ * Fallback: create paint styles if Variables API isn't available
+ */
+export function createOrUpdateStylesFallback(): void {
+  const themes = getThemeNamesFromTokens();
+  for (const theme of themes) {
+    const col: Record<string, any> = getThemeGroup(theme, 'color');
+    for (const [key, val] of Object.entries(col)) {
+      const rgb = parseColor(val);
+      upsertPaintStyle(`${theme.toUpperCase()}/Color/${key}`, rgb);
+    }
+  }
+}
+
+/**
+ * Bind a frame's fill to a color variable (semantic token).
+ */
+export function bindColorVariable(node: any, tokenKey: string, fillOrStroke: string, theme?: string): boolean {
+  const resolvedTheme =
+    (theme && (_themeColorVariables[theme] || _variableModeIds[theme])) ? theme :
+    _defaultThemeName;
+  const variable =
+    (_themeColorVariables[resolvedTheme] && _themeColorVariables[resolvedTheme][tokenKey]) ||
+    (_themeColorVariables[_defaultThemeName] && _themeColorVariables[_defaultThemeName][tokenKey]) ||
+    _colorVariables[tokenKey] ||
+    null;
+  if (!variable) return false;
+
+  try {
+    if (fillOrStroke === 'fill') {
+      const fills = JSON.parse(JSON.stringify(node.fills || []));
+      if (fills.length === 0) {
+        fills.push({ type: 'SOLID', color: { r: 1, g: 1, b: 1 }, opacity: 1 });
+      }
+      fills[0] = figma.variables.setBoundVariableForPaint(fills[0], 'color', variable);
+      node.fills = fills;
+    } else if (fillOrStroke === 'stroke') {
+      const strokes = JSON.parse(JSON.stringify(node.strokes || []));
+      if (strokes.length === 0) {
+        strokes.push({ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } });
+      }
+      strokes[0] = figma.variables.setBoundVariableForPaint(strokes[0], 'color', variable);
+      node.strokes = strokes;
+    }
+    return true;
+  } catch (e: any) {
+    debug('Failed to bind variable ' + tokenKey + ': ' + (e.message || e));
+    return false;
+  }
+}
+
+/**
+ * Set the theme mode on a frame (only works on paid plans with multi-mode).
+ * On free plan this is a no-op (themes are separate collections instead).
+ */
+export function setThemeMode(frame: any, theme: string): void {
+  if (!_useMultiMode || !_variableCollection) return;
+  const normalized = normalizeThemeName(theme) || normalizeCustomThemeName(theme);
+  const resolvedTheme = (theme && _variableModeIds[theme]) ? theme :
+    ((normalized && _variableModeIds[normalized]) ? normalized : _defaultThemeName);
+  const modeId = _variableModeIds[resolvedTheme];
+  if (!modeId) return;
+  try {
+    frame.setExplicitVariableModeForCollection(_variableCollection, modeId);
+  } catch (e: any) {
+    debug('Failed to set theme mode: ' + (e.message || e));
+  }
+}
+
+export function isMultiModeEnabled(): boolean {
+  return _useMultiMode;
+}
+
+export function pxFromSizeToken(v: unknown): number {
+  const baseRem = 16;
+  const toPx = (t: string): number => {
+    t = String(t).trim();
+    if (t.endsWith('rem')) return parseFloat(t) * baseRem;
+    if (t.endsWith('px')) return parseFloat(t);
+    return parseFloat(t);
+  };
+  const sv = String(v || '').trim();
+  if (sv.startsWith('calc(') && sv.endsWith(')')) {
+    const inner = sv.slice(5, -1);
+    let total = 0;
+    let cur = '';
+    let op = '+';
+    for (const ch of inner) {
+      if (ch === '+' || ch === '-') {
+        if (cur.trim()) {
+          const val = toPx(cur);
+          total = op === '+' ? total + val : total - val;
+          cur = '';
+        }
+        op = ch;
+      } else {
+        cur += ch;
+      }
+    }
+    if (cur.trim()) {
+      const val = toPx(cur);
+      total = op === '+' ? total + val : total - val;
+    }
+    return Math.max(0, Math.round(total));
+  }
+  return Math.max(0, Math.round(toPx(sv)));
+}
+
+/**
+ * Bind a frame's cornerRadius corners to a radius variable.
+ * radiusKey is a token key like 'md', 'lg', 'base', etc.
+ */
+export function bindRadiusVariable(node: any, radiusKey: string, _theme?: string): boolean {
+  const variable = _radiusVariables[radiusKey];
+  if (!variable) return false;
+  try {
+    node.setBoundVariable('topLeftRadius', variable);
+    node.setBoundVariable('topRightRadius', variable);
+    node.setBoundVariable('bottomLeftRadius', variable);
+    node.setBoundVariable('bottomRightRadius', variable);
+    return true;
+  } catch (e: any) {
+    debug('Failed to bind radius variable ' + radiusKey + ': ' + (e.message || e));
+    return false;
+  }
+}
+
+export function createOrUpdateStyles(): void {
+  // Remove stale paint styles (LIGHT/DARK/PRIMARY/SECONDARY)
+  removeStaleColorStyles();
+  // Create Figma Variables with dynamic theme modes/collections.
+  createOrUpdateVariables();
+  // Create Figma Effect Styles for shadow tokens
+  const shadowTokens = getThemeGroup(_defaultThemeName, 'shadow');
+  if (Object.keys(shadowTokens).length) {
+    populateShadowStyles(shadowTokens as Record<string, string>);
+  }
+}
+
+export function ensureTokensPage(): any {
+  let page = figma.root.children.find((p: any) => p.name === 'Design Tokens');
+  if (!page) {
+    page = figma.createPage();
+    page.name = 'Design Tokens';
+  }
+  figma.currentPage = page;
+  return page;
+}
+
+export function demoFrameColors(theme: string): any {
+  const frame = figma.createFrame();
+  frame.name = theme.toUpperCase() + ' Colors';
+  frame.layoutMode = 'VERTICAL';
+  frame.primaryAxisSizingMode = 'AUTO';
+  frame.counterAxisSizingMode = 'AUTO';
+  frame.itemSpacing = 12;
+  frame.paddingLeft = frame.paddingRight = frame.paddingTop = frame.paddingBottom = 16;
+  frame.fills = [];
+  frame.strokes = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
+  const col: Record<string, any> = ((TOKENS as any)[theme] && (TOKENS as any)[theme].color) ? (TOKENS as any)[theme].color : {};
+  let idx = 0;
+  for (const [key, val] of Object.entries(col)) {
+    const row = figma.createFrame();
+    row.layoutMode = 'HORIZONTAL';
+    row.primaryAxisSizingMode = 'AUTO';
+    row.counterAxisSizingMode = 'AUTO';
+    row.itemSpacing = 12;
+    row.name = key;
+
+    const swatch = figma.createRectangle();
+    swatch.resize(48, 32);
+    const rgb = parseColor(val);
+    swatch.fills = [{ type: 'SOLID', color: { r: rgb.r, g: rgb.g, b: rgb.b }, opacity: (rgb.a == null ? 1 : rgb.a) }];
+    // Bind to Figma Variable so swatch updates when variable changes
+    bindColorVariable(swatch, key, 'fill', theme);
+    swatch.strokes = [];
+
+    const label = figma.createText();
+    label.characters = key + ' \u2014 ' + colorToLabel(val);
+    // Load default font for text placement
+    // Note: plugin will await font load asynchronously below
+    row.appendChild(swatch);
+    row.appendChild(label);
+    frame.appendChild(row);
+    idx++;
+  }
+  return frame;
+}
+
+export function demoFrameRadii(): any {
+  const frame = figma.createFrame();
+  frame.name = 'Radii';
+  frame.layoutMode = 'HORIZONTAL';
+  frame.primaryAxisSizingMode = 'AUTO';
+  frame.counterAxisSizingMode = 'AUTO';
+  frame.itemSpacing = 16;
+  frame.paddingLeft = frame.paddingRight = frame.paddingTop = frame.paddingBottom = 16;
+  frame.fills = [];
+  frame.strokes = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
+  const r: Record<string, any> = getThemeGroup(_defaultThemeName, 'radius');
+  const keys = Object.keys(r);
+  for (const k of keys) {
+    const rect = figma.createRectangle();
+    rect.resize(96, 64);
+    rect.cornerRadius = pxFromSizeToken(r[k]);
+    rect.fills = [{ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } }];
+    rect.strokes = [{ type: 'SOLID', color: { r: 0.75, g: 0.75, b: 0.75 } }];
+    rect.name = 'radius/' + k;
+    frame.appendChild(rect);
+  }
+  return frame;
+}