inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/src/{variables.ts → tokens/variables.ts}

@@ -5,16 +5,17 @@ import { parseColor, colorToLabel, debug, normalizeThemeName, normalizeGroupName
 // 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 _variableCollection: VariableCollection | null = null;       // Single-collection (paid) or default-theme collection (free)
+let _themeCollections: Record<string, VariableCollection> = {}; // 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 _colorVariables: Record<string, Variable> = {}; // default theme tokenKey -> Variable
+let _themeColorVariables: Record<string, Record<string, Variable>> = {}; // theme -> tokenKey -> Variable
+let _radiusVariables: Record<string, Variable> = {};            // key -> FLOAT Variable (radius/sm, radius/md …)
+let _fontVariables: Record<string, Variable> = {};              // key -> STRING Variable (font/sans …)
+let _spacingVariables: Record<string, Variable> = {};           // key -> FLOAT Variable (spacing/sm, spacing/lg …)
+let _fontSizeVariables: Record<string, Variable> = {};          // key -> FLOAT Variable (fontSize/sm, fontSize/xl …)
+let _breakpointVariables: Record<string, Variable> = {};        // key -> FLOAT Variable (breakpoint/sm, breakpoint/lg …)
 let _useMultiMode = false;            // true if paid plan (multi-mode available)
 
 // ---------------------------------------------------------------------------
@@ -46,12 +47,13 @@ function getThemeDisplayName(theme: string): string {
 }
 
 function getThemeNamesFromTokens(): string[] {
-  const names = Object.keys(TOKENS || {}).filter((key) => {
+  const tokensRecord = TOKENS as unknown as Record<string, Record<string, unknown> | undefined>;
+  const names = Object.keys(tokensRecord || {}).filter((key) => {
     if (key === 'core') return false;
-    const block = (TOKENS as any)[key];
+    const block = tokensRecord[key];
     if (!block || typeof block !== 'object') return false;
     return Boolean(
-      block.color || block.radius || block.font || block.spacing || block.fontSize || block.shadow
+      block.color || block.radius || block.font || block.spacing || block.fontSize || block.shadow || block.breakpoint
     );
   });
   if (names.length === 0) return ['primary'];
@@ -59,22 +61,23 @@ function getThemeNamesFromTokens(): string[] {
   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]
+function getThemeGroup(theme: string, group: string): Record<string, string> {
+  const tokensRecord = TOKENS as unknown as Record<string, Record<string, unknown> | undefined>;
+  const block = (tokensRecord[theme] && typeof tokensRecord[theme] === 'object')
+    ? tokensRecord[theme]!
     : {};
   const value = block[group];
-  return value && typeof value === 'object' ? value : {};
+  return value && typeof value === 'object' ? (value as Record<string, string>) : {};
 }
 
-function findCollectionByName(collections: any[], name: string): any {
+function findCollectionByName(collections: VariableCollection[], name: string): VariableCollection | null {
   const needle = String(name || '').toLowerCase();
-  return collections.find((c: any) => String(c.name || '').toLowerCase() === needle) || null;
+  return collections.find((c) => String(c.name || '').toLowerCase() === needle) || null;
 }
 
-export function resolveVariableValue(value: any, modeId?: string, visited?: Record<string, boolean>): any {
+export function resolveVariableValue(value: VariableValue | null | undefined, modeId?: string, visited?: Record<string, boolean>): VariableValue | null {
   if (!value) return null;
-  if (value.type === 'VARIABLE_ALIAS' && value.id) {
+  if (typeof value === 'object' && 'type' in value && value.type === 'VARIABLE_ALIAS' && value.id) {
     if (!visited) visited = {};
     if (visited[value.id]) return null;
     visited[value.id] = true;
@@ -88,7 +91,16 @@ export function resolveVariableValue(value: any, modeId?: string, visited?: Reco
   return value;
 }
 
-export function readVariableTokens(): any {
+type VariableTokenBlock = {
+  color?: Record<string, string>;
+  radius?: Record<string, string>;
+  font?: Record<string, string>;
+  spacing?: Record<string, string>;
+  fontSize?: Record<string, string>;
+};
+type VariableTokens = Record<string, VariableTokenBlock>;
+
+export function readVariableTokens(): VariableTokens | null {
   if (!figma.variables || !figma.variables.getLocalVariables) {
     debug('Variables API unavailable, using embedded tokens.');
     return null;
@@ -99,7 +111,7 @@ export function readVariableTokens(): any {
     return null;
   }
   const collections = figma.variables.getLocalVariableCollections ? figma.variables.getLocalVariableCollections() : [];
-  const collectionById: Record<string, any> = {};
+  const collectionById: Record<string, VariableCollection> = {};
   const modeNameById: Record<string, string> = {};
   for (const col of collections) {
     collectionById[col.id] = col;
@@ -112,36 +124,36 @@ export function readVariableTokens(): any {
 
   // 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> = {
+  const out: VariableTokens = {
     core: { font: {} },
     primary: { color: {}, radius: {}, font: {}, spacing: {}, fontSize: {} },
   };
   let wrote = false;
 
-  function ensureTheme(themeName: string): Record<string, any> {
+  function ensureTheme(themeName: string): Required<VariableTokenBlock> {
     if (!out[themeName] || typeof out[themeName] !== 'object') {
       out[themeName] = {};
     }
-    const block = out[themeName] as Record<string, any>;
+    const block = out[themeName];
     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;
+    return block as Required<VariableTokenBlock>;
   }
 
-  function assign(theme: string, group: string, parts: string[], value: any): void {
+  function assign(theme: string, group: string, parts: string[], value: VariableValue | null): 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>;
+    let target: Record<string, string>;
 
     if (group === 'color') {
       target = ensureTheme(resolvedTheme).color;
-      target[key] = value;
+      target[key] = String(value);
       wrote = true;
       return;
     }
@@ -153,7 +165,7 @@ export function readVariableTokens(): any {
     }
     if (group === 'font') {
       // Route unscoped fonts into core, scoped fonts into their theme block.
-      if (!theme || theme === 'core') target = out.core.font;
+      if (!theme || theme === 'core') target = out.core.font!;
       else target = ensureTheme(theme).font;
       target[key] = String(value);
       wrote = true;
@@ -187,7 +199,7 @@ export function readVariableTokens(): any {
     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') {
+      if (String(variable.resolvedType || '').toUpperCase() === 'COLOR') {
         group = 'color';
         if (cursor.length === 0) {
           theme = null;
@@ -232,9 +244,9 @@ export function readVariableTokens(): any {
   return wrote ? out : null;
 }
 
-export function upsertPaintStyle(name: string, color: { r: number; g: number; b: number; a?: number }): any {
+export function upsertPaintStyle(name: string, color: { r: number; g: number; b: number; a?: number }): PaintStyle {
   const styles = figma.getLocalPaintStyles();
-  const existing = styles.find((s: any) => s.name === name);
+  const existing = styles.find((s) => 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];
@@ -354,7 +366,7 @@ function upsertEffectStyle(name: string, cssValue: string): void {
   const layers = parseCssBoxShadow(cssValue);
   if (!layers.length) return;
 
-  const effects: any[] = [];
+  const effects: Effect[] = [];
   for (const l of layers) {
     effects.push({
       type: l.inset ? 'INNER_SHADOW' : 'DROP_SHADOW',
@@ -367,7 +379,7 @@ function upsertEffectStyle(name: string, cssValue: string): void {
     });
   }
 
-  const existing = figma.getLocalEffectStyles().find((s: any) => s.name === name);
+  const existing = figma.getLocalEffectStyles().find((s) => s.name === name);
   if (existing) {
     existing.effects = effects;
   } else {
@@ -403,10 +415,10 @@ export function removeStaleColorStyles(): void {
 /**
  * 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 {
+export function populateColorVariables(collection: VariableCollection, modeId: string, colorTokens: Record<string, string>, outMap: Record<string, Variable>): void {
   // Index existing variables in this collection
   const existingVars = figma.variables.getLocalVariables('COLOR');
-  const existingByName: Record<string, any> = {};
+  const existingByName: Record<string, Variable> = {};
   for (const v of existingVars) {
     if (v.variableCollectionId === collection.id) {
       existingByName[v.name] = v;
@@ -428,9 +440,9 @@ export function populateColorVariables(collection: any, modeId: string, colorTok
 /**
  * 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 {
+export function populateRadiusVariables(collection: VariableCollection, modeId: string, radiusTokens: Record<string, string>, outMap: Record<string, Variable>): void {
   const existingVars = figma.variables.getLocalVariables('FLOAT');
-  const existingByName: Record<string, any> = {};
+  const existingByName: Record<string, Variable> = {};
   for (const v of existingVars) {
     if (v.variableCollectionId === collection.id) {
       existingByName[v.name] = v;
@@ -450,9 +462,9 @@ export function populateRadiusVariables(collection: any, modeId: string, radiusT
 /**
  * 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 {
+export function populateFontVariables(collection: VariableCollection, modeId: string, fontTokens: Record<string, string>, outMap: Record<string, Variable>): void {
   const existingVars = figma.variables.getLocalVariables('STRING');
-  const existingByName: Record<string, any> = {};
+  const existingByName: Record<string, Variable> = {};
   for (const v of existingVars) {
     if (v.variableCollectionId === collection.id) {
       existingByName[v.name] = v;
@@ -474,9 +486,9 @@ export function populateFontVariables(collection: any, modeId: string, fontToken
 /**
  * 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 {
+export function populateSpacingVariables(collection: VariableCollection, modeId: string, spacingTokens: Record<string, string>, outMap: Record<string, Variable>): void {
   const existingVars = figma.variables.getLocalVariables('FLOAT');
-  const existingByName: Record<string, any> = {};
+  const existingByName: Record<string, Variable> = {};
   for (const v of existingVars) {
     if (v.variableCollectionId === collection.id) existingByName[v.name] = v;
   }
@@ -494,9 +506,9 @@ export function populateSpacingVariables(collection: any, modeId: string, spacin
 /**
  * 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 {
+export function populateFontSizeVariables(collection: VariableCollection, modeId: string, fontSizeTokens: Record<string, string>, outMap: Record<string, Variable>): void {
   const existingVars = figma.variables.getLocalVariables('FLOAT');
-  const existingByName: Record<string, any> = {};
+  const existingByName: Record<string, Variable> = {};
   for (const v of existingVars) {
     if (v.variableCollectionId === collection.id) existingByName[v.name] = v;
   }
@@ -511,6 +523,26 @@ export function populateFontSizeVariables(collection: any, modeId: string, fontS
   }
 }
 
+/**
+ * Populate FLOAT breakpoint variables in a collection for a given mode.
+ */
+export function populateBreakpointVariables(collection: VariableCollection, modeId: string, breakpointTokens: Record<string, string>, outMap: Record<string, Variable>): void {
+  const existingVars = figma.variables.getLocalVariables('FLOAT');
+  const existingByName: Record<string, Variable> = {};
+  for (const v of existingVars) {
+    if (v.variableCollectionId === collection.id) existingByName[v.name] = v;
+  }
+  for (const key in breakpointTokens) {
+    const varName = 'breakpoint/' + key;
+    let variable = existingByName[varName];
+    if (!variable) {
+      variable = figma.variables.createVariable(varName, collection, 'FLOAT');
+    }
+    variable.setValueForMode(modeId, pxFromSizeToken(breakpointTokens[key]));
+    outMap[key] = variable;
+  }
+}
+
 /**
  * Create or update color variables.
  * Tries multi-mode first (paid plans). Falls back to two collections (free plan).
@@ -527,17 +559,19 @@ export function createOrUpdateVariables(): void {
   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>> = {};
+  const themeColors: Record<string, Record<string, string>> = {};
+  const themeRadius: Record<string, Record<string, string>> = {};
+  const themeFont: Record<string, Record<string, string>> = {};
+  const themeSpacing: Record<string, Record<string, string>> = {};
+  const themeFontSize: Record<string, Record<string, string>> = {};
+  const themeBreakpoint: Record<string, Record<string, string>> = {};
   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');
+    themeBreakpoint[theme] = getThemeGroup(theme, 'breakpoint');
   }
 
   _themeCollections = {};
@@ -548,13 +582,14 @@ export function createOrUpdateVariables(): void {
   _fontVariables = {};
   _spacingVariables = {};
   _fontSizeVariables = {};
+  _breakpointVariables = {};
 
   const collections = figma.variables.getLocalVariableCollections();
 
-  function ensureThemeModes(collection: any): boolean {
+  function ensureThemeModes(collection: VariableCollection): 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 unclaimed: string[] = modes.map((mode) => mode.modeId);
     const removeUnclaimed = (modeId: string): void => {
       const idx = unclaimed.indexOf(modeId);
       if (idx >= 0) unclaimed.splice(idx, 1);
@@ -580,8 +615,8 @@ export function createOrUpdateVariables(): void {
       }
       try {
         map[theme] = collection.addMode(getThemeDisplayName(theme));
-      } catch (e: any) {
-        debug('Cannot add mode (free plan): ' + (e.message || e));
+      } catch (e) {
+        debug('Cannot add mode (free plan): ' + (e instanceof Error ? e.message : String(e)));
         return false;
       }
     }
@@ -625,16 +660,18 @@ export function createOrUpdateVariables(): void {
     const allFontKeys: Record<string, boolean> = {};
     const allSpacingKeys: Record<string, boolean> = {};
     const allFontSizeKeys: Record<string, boolean> = {};
+    const allBreakpointKeys: 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;
+      for (const key in themeBreakpoint[theme]) allBreakpointKeys[key] = true;
     }
 
     const existingColorVars = figma.variables.getLocalVariables('COLOR');
-    const existingColorByName: Record<string, any> = {};
+    const existingColorByName: Record<string, Variable> = {};
     for (const v of existingColorVars) {
       if (v.variableCollectionId === _variableCollection.id) {
         existingColorByName[v.name] = v;
@@ -642,7 +679,7 @@ export function createOrUpdateVariables(): void {
     }
 
     const existingFloatVars = figma.variables.getLocalVariables('FLOAT');
-    const existingFloatByName: Record<string, any> = {};
+    const existingFloatByName: Record<string, Variable> = {};
     for (const v of existingFloatVars) {
       if (v.variableCollectionId === _variableCollection.id) {
         existingFloatByName[v.name] = v;
@@ -650,7 +687,7 @@ export function createOrUpdateVariables(): void {
     }
 
     const existingStringVars = figma.variables.getLocalVariables('STRING');
-    const existingStringByName: Record<string, any> = {};
+    const existingStringByName: Record<string, Variable> = {};
     for (const v of existingStringVars) {
       if (v.variableCollectionId === _variableCollection.id) {
         existingStringByName[v.name] = v;
@@ -752,6 +789,24 @@ export function createOrUpdateVariables(): void {
       _fontSizeVariables[key] = variable;
     }
 
+    const defaultBreakpoint = themeBreakpoint[defaultTheme] || {};
+    for (const key in allBreakpointKeys) {
+      const varName = 'breakpoint/' + 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 = (themeBreakpoint[theme] && themeBreakpoint[theme][key] !== undefined)
+          ? themeBreakpoint[theme][key]
+          : defaultBreakpoint[key];
+        if (value === undefined) continue;
+        variable.setValueForMode(modeId, pxFromSizeToken(value));
+      }
+      _breakpointVariables[key] = variable;
+    }
+
     for (const col of collections) {
       if (!col || col.id === _variableCollection.id) continue;
       const mapped = normalizeThemeName(col.name) || normalizeCustomThemeName(col.name);
@@ -798,6 +853,7 @@ export function createOrUpdateVariables(): void {
       populateFontVariables(collection, modeId, themeFont[theme] || {}, _fontVariables);
       populateSpacingVariables(collection, modeId, themeSpacing[theme] || {}, _spacingVariables);
       populateFontSizeVariables(collection, modeId, themeFontSize[theme] || {}, _fontSizeVariables);
+      populateBreakpointVariables(collection, modeId, themeBreakpoint[theme] || {}, _breakpointVariables);
     }
   }
 
@@ -808,13 +864,14 @@ export function createOrUpdateVariables(): void {
     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) =>
+    const varsInCollection = figma.variables.getLocalVariables().filter((v) => v.variableCollectionId === collection.id);
+    const looksLikePluginThemeCollection = varsInCollection.some((v) =>
       /^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 || ''))
+      /^fontSize\//.test(String(v.name || '')) ||
+      /^breakpoint\//.test(String(v.name || ''))
     );
     if (!looksLikePluginThemeCollection) continue;
     try { collection.remove(); } catch (_e) {}
@@ -834,7 +891,7 @@ export function createOrUpdateVariables(): void {
 export function createOrUpdateStylesFallback(): void {
   const themes = getThemeNamesFromTokens();
   for (const theme of themes) {
-    const col: Record<string, any> = getThemeGroup(theme, 'color');
+    const col: Record<string, string> = getThemeGroup(theme, 'color');
     for (const [key, val] of Object.entries(col)) {
       const rgb = parseColor(val);
       upsertPaintStyle(`${theme.toUpperCase()}/Color/${key}`, rgb);
@@ -845,7 +902,7 @@ export function createOrUpdateStylesFallback(): void {
 /**
  * Bind a frame's fill to a color variable (semantic token).
  */
-export function bindColorVariable(node: any, tokenKey: string, fillOrStroke: string, theme?: string): boolean {
+export function bindColorVariable(node: SceneNode, tokenKey: string, fillOrStroke: string, theme?: string): boolean {
   const resolvedTheme =
     (theme && (_themeColorVariables[theme] || _variableModeIds[theme])) ? theme :
     _defaultThemeName;
@@ -857,24 +914,24 @@ export function bindColorVariable(node: any, tokenKey: string, fillOrStroke: str
   if (!variable) return false;
 
   try {
-    if (fillOrStroke === 'fill') {
-      const fills = JSON.parse(JSON.stringify(node.fills || []));
+    if (fillOrStroke === 'fill' && 'fills' in node) {
+      const fills: Paint[] = 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);
+      fills[0] = figma.variables.setBoundVariableForPaint(fills[0] as SolidPaint, 'color', variable);
       node.fills = fills;
-    } else if (fillOrStroke === 'stroke') {
-      const strokes = JSON.parse(JSON.stringify(node.strokes || []));
+    } else if (fillOrStroke === 'stroke' && 'strokes' in node) {
+      const strokes: Paint[] = 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);
+      strokes[0] = figma.variables.setBoundVariableForPaint(strokes[0] as SolidPaint, 'color', variable);
       node.strokes = strokes;
     }
     return true;
-  } catch (e: any) {
-    debug('Failed to bind variable ' + tokenKey + ': ' + (e.message || e));
+  } catch (e) {
+    debug('Failed to bind variable ' + tokenKey + ': ' + (e instanceof Error ? e.message : String(e)));
     return false;
   }
 }
@@ -883,7 +940,7 @@ export function bindColorVariable(node: any, tokenKey: string, fillOrStroke: str
  * 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 {
+export function setThemeMode(frame: SceneNode, theme: string): void {
   if (!_useMultiMode || !_variableCollection) return;
   const normalized = normalizeThemeName(theme) || normalizeCustomThemeName(theme);
   const resolvedTheme = (theme && _variableModeIds[theme]) ? theme :
@@ -892,8 +949,8 @@ export function setThemeMode(frame: any, theme: string): void {
   if (!modeId) return;
   try {
     frame.setExplicitVariableModeForCollection(_variableCollection, modeId);
-  } catch (e: any) {
-    debug('Failed to set theme mode: ' + (e.message || e));
+  } catch (e) {
+    debug('Failed to set theme mode: ' + (e instanceof Error ? e.message : String(e)));
   }
 }
 
@@ -940,17 +997,18 @@ export function pxFromSizeToken(v: unknown): number {
  * 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 {
+export function bindRadiusVariable(node: SceneNode, radiusKey: string, _theme?: string): boolean {
   const variable = _radiusVariables[radiusKey];
   if (!variable) return false;
+  if (!('setBoundVariable' in node)) 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));
+  } catch (e) {
+    debug('Failed to bind radius variable ' + radiusKey + ': ' + (e instanceof Error ? e.message : String(e)));
     return false;
   }
 }
@@ -967,8 +1025,8 @@ export function createOrUpdateStyles(): void {
   }
 }
 
-export function ensureTokensPage(): any {
-  let page = figma.root.children.find((p: any) => p.name === 'Design Tokens');
+export function ensureTokensPage(): PageNode {
+  let page = figma.root.children.find((p) => p.name === 'Design Tokens');
   if (!page) {
     page = figma.createPage();
     page.name = 'Design Tokens';
@@ -977,9 +1035,96 @@ export function ensureTokensPage(): any {
   return page;
 }
 
-export function demoFrameColors(theme: string): any {
+function makeSectionTitle(text: string): TextNode {
+  const node = figma.createText();
+  try {
+    node.fontName = { family: 'Inter', style: 'Bold' };
+  } catch (_e) {
+    // Bold not loaded; fall back to whatever style createText assigns.
+  }
+  node.characters = text;
+  node.fontSize = 14;
+  return node;
+}
+
+function makeCategoryHeading(text: string): TextNode {
+  const node = figma.createText();
+  try {
+    node.fontName = { family: 'Inter', style: 'Bold' };
+  } catch (_e) {
+    // Bold not loaded; fall back to whatever style createText assigns.
+  }
+  node.characters = text;
+  node.fontSize = 18;
+  return node;
+}
+
+// Equal-width column widths so the side-by-side theme frames don't drift in
+// width based on content (mirrors the per-story column treatment used in the
+// component grid).
+const TOKENS_THEME_COLUMN_WIDTH = 460;
+const TOKENS_THEME_COLUMN_GAP = 24;
+
+export function buildTokensCategorySection(label: string, frames: Array<FrameNode | null>): FrameNode | null {
+  const visible: FrameNode[] = frames.filter((f): f is FrameNode => !!f);
+  if (visible.length === 0) return null;
+
+  const section = figma.createFrame();
+  section.name = label;
+  section.layoutMode = 'VERTICAL';
+  section.primaryAxisSizingMode = 'AUTO';
+  section.counterAxisSizingMode = 'AUTO';
+  section.itemSpacing = 12;
+  section.fills = [];
+  section.strokes = [];
+  section.appendChild(makeCategoryHeading(label));
+
+  if (visible.length === 1) {
+    section.appendChild(visible[0]);
+    return section;
+  }
+
+  const row = figma.createFrame();
+  row.name = label + ' / themes';
+  row.layoutMode = 'HORIZONTAL';
+  row.primaryAxisSizingMode = 'AUTO';
+  row.counterAxisSizingMode = 'AUTO';
+  row.itemSpacing = TOKENS_THEME_COLUMN_GAP;
+  row.counterAxisAlignItems = 'MIN';
+  row.fills = [];
+  row.strokes = [];
+
+  for (const frame of visible) {
+    row.appendChild(frame);
+    // Lock each theme demo's width so Primary and Secondary columns stay
+    // identical regardless of label or swatch content. counterAxisSizingMode
+    // is the horizontal sizing for a vertical autolayout frame.
+    if ('counterAxisSizingMode' in frame) {
+      frame.counterAxisSizingMode = 'FIXED';
+    }
+    frame.resize(TOKENS_THEME_COLUMN_WIDTH, Math.max(frame.height || 1, 1));
+  }
+  section.appendChild(row);
+  return section;
+}
+
+function makeBodyText(text: string, options?: { family?: string; style?: string; size?: number }): TextNode {
+  const node = figma.createText();
+  const family = (options && options.family) || 'Inter';
+  const style = (options && options.style) || 'Regular';
+  try {
+    node.fontName = { family, style };
+  } catch (_e) {
+    // Requested font not loaded; fall back to default font.
+  }
+  node.characters = text;
+  if (options && options.size) node.fontSize = options.size;
+  return node;
+}
+
+function makeSectionFrame(name: string): FrameNode {
   const frame = figma.createFrame();
-  frame.name = theme.toUpperCase() + ' Colors';
+  frame.name = name;
   frame.layoutMode = 'VERTICAL';
   frame.primaryAxisSizingMode = 'AUTO';
   frame.counterAxisSizingMode = 'AUTO';
@@ -987,8 +1132,13 @@ export function demoFrameColors(theme: string): any {
   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;
+  return frame;
+}
+
+export function demoFrameColors(theme: string): FrameNode {
+  const frame = makeSectionFrame(theme.toUpperCase() + ' Colors');
+  frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
+  const col: Record<string, string> = getThemeGroup(theme, 'color');
   for (const [key, val] of Object.entries(col)) {
     const row = figma.createFrame();
     row.layoutMode = 'HORIZONTAL';
@@ -1001,42 +1151,237 @@ export function demoFrameColors(theme: string): any {
     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
+    const label = makeBodyText(key + ' \u2014 ' + colorToLabel(val));
     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) {
+export function demoFrameRadii(): FrameNode {
+  const frame = makeSectionFrame('Radii');
+
+  const row = figma.createFrame();
+  row.layoutMode = 'HORIZONTAL';
+  row.primaryAxisSizingMode = 'AUTO';
+  row.counterAxisSizingMode = 'AUTO';
+  row.itemSpacing = 16;
+  row.fills = [];
+  row.strokes = [];
+
+  const r: Record<string, string> = getThemeGroup(_defaultThemeName, 'radius');
+  for (const k of Object.keys(r)) {
+    const cell = figma.createFrame();
+    cell.layoutMode = 'VERTICAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.itemSpacing = 6;
+    cell.fills = [];
+    cell.strokes = [];
+    cell.name = 'radius/' + k;
+
     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);
+    rect.name = 'swatch';
+
+    cell.appendChild(rect);
+    cell.appendChild(makeBodyText(k, { size: 12 }));
+    row.appendChild(cell);
+  }
+  frame.appendChild(row);
+  return frame;
+}
+
+export function demoFrameFonts(theme: string): FrameNode | null {
+  const fonts: Record<string, string> = getThemeGroup(theme, 'font');
+  const keys = Object.keys(fonts);
+  if (keys.length === 0) return null;
+
+  const frame = makeSectionFrame(theme.toUpperCase() + ' Fonts');
+  frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
+
+  for (const key of keys) {
+    const family = (function () {
+      const raw = String(fonts[key] || '');
+      const parts = raw.split(',');
+      for (const part of parts) {
+        const trimmed = part.trim();
+        const varMatch = trimmed.match(/^var\(--font-([a-z0-9-]+)\)/i);
+        if (varMatch) {
+          return varMatch[1].split('-').map((w: string) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+        }
+        const lower = trimmed.toLowerCase().replace(/^["']|["']$/g, '');
+        if (lower === 'ui-sans-serif' || lower === 'system-ui' || lower === 'sans-serif' || lower === 'serif' || lower === 'monospace' || lower === 'ui-monospace') continue;
+        const cleaned = trimmed.replace(/^["']|["']$/g, '');
+        if (cleaned) return cleaned;
+      }
+      return 'Inter';
+    })();
+
+    const cell = figma.createFrame();
+    cell.layoutMode = 'VERTICAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.itemSpacing = 4;
+    cell.fills = [];
+    cell.strokes = [];
+    cell.name = 'font/' + key;
+
+    cell.appendChild(makeBodyText(key + ' \u2014 ' + family, { size: 12 }));
+    cell.appendChild(makeBodyText('The quick brown fox jumps over the lazy dog', { family, size: 18 }));
+    frame.appendChild(cell);
+  }
+  return frame;
+}
+
+export function demoFrameSpacing(): FrameNode | null {
+  const spacing: Record<string, string> = getThemeGroup(_defaultThemeName, 'spacing');
+  const keys = Object.keys(spacing);
+  if (keys.length === 0) return null;
+
+  const frame = makeSectionFrame('Spacing');
+
+  for (const k of keys) {
+    const px = pxFromSizeToken(spacing[k]);
+    const row = figma.createFrame();
+    row.layoutMode = 'HORIZONTAL';
+    row.primaryAxisSizingMode = 'AUTO';
+    row.counterAxisSizingMode = 'AUTO';
+    row.itemSpacing = 12;
+    row.counterAxisAlignItems = 'CENTER';
+    row.fills = [];
+    row.strokes = [];
+    row.name = 'spacing/' + k;
+
+    const bar = figma.createRectangle();
+    bar.resize(Math.max(1, px), 16);
+    bar.fills = [{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } }];
+    bar.strokes = [];
+
+    row.appendChild(bar);
+    row.appendChild(makeBodyText(k + ' \u2014 ' + Math.round(px) + 'px', { size: 12 }));
+    frame.appendChild(row);
+  }
+  return frame;
+}
+
+export function demoFrameFontSizes(): FrameNode | null {
+  const sizes: Record<string, string> = getThemeGroup(_defaultThemeName, 'fontSize');
+  const keys = Object.keys(sizes);
+  if (keys.length === 0) return null;
+
+  const frame = makeSectionFrame('Font sizes');
+
+  for (const k of keys) {
+    const px = pxFromSizeToken(sizes[k]);
+    frame.appendChild(makeBodyText(k + ' \u2014 ' + Math.round(px) + 'px sample', { size: px }));
+  }
+  return frame;
+}
+
+export function demoFrameBreakpoints(): FrameNode | null {
+  const breakpoints: Record<string, string> = getThemeGroup(_defaultThemeName, 'breakpoint');
+  const keys = Object.keys(breakpoints);
+  if (keys.length === 0) return null;
+
+  const sorted = keys
+    .map((k) => ({ key: k, px: pxFromSizeToken(breakpoints[k]) }))
+    .filter((entry) => Number.isFinite(entry.px))
+    .sort((a, b) => a.px - b.px);
+  if (sorted.length === 0) return null;
+
+  const frame = makeSectionFrame('Breakpoints');
+  const maxPx = sorted[sorted.length - 1].px;
+  // Cap the visualization width so a 96rem breakpoint doesn't blow out the
+  // canvas; everything scales relative to the largest breakpoint.
+  const maxBarWidth = 480;
+  const scale = maxPx > 0 ? maxBarWidth / maxPx : 0;
+
+  for (const entry of sorted) {
+    const row = figma.createFrame();
+    row.layoutMode = 'HORIZONTAL';
+    row.primaryAxisSizingMode = 'AUTO';
+    row.counterAxisSizingMode = 'AUTO';
+    row.itemSpacing = 12;
+    row.counterAxisAlignItems = 'CENTER';
+    row.fills = [];
+    row.strokes = [];
+    row.name = 'breakpoint/' + entry.key;
+
+    const bar = figma.createRectangle();
+    bar.resize(Math.max(1, Math.round(entry.px * scale)), 12);
+    bar.fills = [{ type: 'SOLID', color: { r: 0.5, g: 0.5, b: 0.5 } }];
+    bar.strokes = [];
+
+    row.appendChild(bar);
+    row.appendChild(makeBodyText(entry.key + ' \u2014 ' + Math.round(entry.px) + 'px', { size: 12 }));
+    frame.appendChild(row);
+  }
+  return frame;
+}
+
+// Sized scale we want to surface in the design tokens overview, in ascending
+// visual weight. Anything else (DEFAULT alias, inner/drop/text variants) is
+// skipped — they pollute the order and inset shadows render nothing on a
+// solid-fill rect.
+const SHADOW_SIZE_ORDER = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+export function demoFrameShadows(theme: string): FrameNode | null {
+  const shadows: Record<string, string> = getThemeGroup(theme, 'shadow');
+  const ordered = SHADOW_SIZE_ORDER.filter((k) => shadows[k]);
+  if (ordered.length === 0) return null;
+
+  const frame = makeSectionFrame(theme.toUpperCase() + ' Shadows');
+  // Larger gap so big shadows (shadow-xl, shadow-2xl) don't visually overlap
+  // the next swatch — the default itemSpacing is too tight for shadow-2xl
+  // which extends ~38px below its rect.
+  frame.itemSpacing = 56;
+  // Keep shadows from being clipped by the wrapper's bounds.
+  frame.clipsContent = false;
+  frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
+
+  for (const k of ordered) {
+    const cell = figma.createFrame();
+    cell.layoutMode = 'VERTICAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.itemSpacing = 8;
+    cell.fills = [];
+    cell.strokes = [];
+    cell.clipsContent = false;
+    cell.name = 'shadow/' + k;
+
+    const swatch = figma.createRectangle();
+    swatch.resize(96, 48);
+    swatch.cornerRadius = 6;
+    swatch.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }];
+    swatch.strokes = [];
+
+    const layers = parseCssBoxShadow(String(shadows[k] || ''));
+    if (layers.length > 0) {
+      swatch.effects = layers
+        .filter((l) => !l.inset)
+        .map((l) => ({
+          type: 'DROP_SHADOW' as const,
+          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' as const,
+        }));
+    }
+
+    cell.appendChild(swatch);
+    cell.appendChild(makeBodyText(k, { size: 12 }));
+    frame.appendChild(cell);
   }
   return frame;
 }