@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/shared/token-binder.ts

@@ -0,0 +1,505 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Token Binder
+// Central module that generates Figma Plugin API scripts to bind design-system
+// variables to node properties. Used by Page Architect, Component Archaeologist,
+// DS Scaffolder, and Intent Translator to enforce token binding.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { Token } from "./types.js";
+import { getDesignSystemTokens } from "./design-system-tokens.js";
+import { getConceptForComponent, getRequiredTokenPaths } from "./concept-taxonomy.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TokenBinding {
+  nodeVar: string;       // JS variable name referencing the node in the script
+  field: string;         // Figma field: "fills" | "strokes" | "paddingLeft" | "cornerRadius" etc.
+  fillIndex?: number;    // For paint bindings (fills/strokes), the array index
+  variableId: string;    // Figma variable ID (e.g. "VariableID:123:456")
+}
+
+export interface SemanticTokenMap {
+  [semanticRole: string]: string; // role → variable ID
+}
+
+// Semantic roles that map component types to the token groups they need
+const COMPONENT_TOKEN_ROLES: Record<string, string[]> = {
+  Button:     ["color/semantic/actions/primary/bg/default", "color/semantic/text/on-color", "radius/semantic/control/default", "space/semantic/inset/control/md", "opacity/semantic/disabled"],
+  Modal:      ["color/semantic/surface/overlay", "color/semantic/border/default", "radius/semantic/surface/default", "color/semantic/text/primary", "elevation/semantic/shadow/lg", "z-index/semantic/modal"],
+  Card:       ["color/semantic/surface/raised", "color/semantic/border/default", "radius/semantic/surface/default", "color/semantic/text/primary", "color/semantic/text/secondary", "elevation/semantic/shadow/sm"],
+  Input:      ["color/semantic/field/bg/default", "color/semantic/field/border/default", "radius/semantic/field/default", "color/semantic/text/primary", "color/semantic/text/disabled", "border-width/semantic/thin"],
+  Select:     ["color/semantic/field/bg/default", "color/semantic/field/border/default", "radius/semantic/field/default", "color/semantic/text/primary", "border-width/semantic/thin"],
+  Checkbox:   ["color/semantic/field/bg/default", "color/semantic/border/default", "color/semantic/text/primary"],
+  Toggle:     ["color/semantic/border/default", "color/semantic/surface/default", "color/semantic/actions/primary/bg/default"],
+  Radio:      ["color/semantic/field/bg/default", "color/semantic/border/default", "color/semantic/text/primary"],
+  Toast:      ["color/semantic/feedback/success/bg", "color/semantic/feedback/success/text", "radius/semantic/control/default", "elevation/semantic/shadow/md", "z-index/semantic/toast"],
+  NavBar:     ["color/semantic/surface/default", "color/semantic/border/subtle", "color/semantic/text/primary", "elevation/semantic/shadow/xs"],
+  Table:      ["color/semantic/surface/default", "color/semantic/border/default", "color/semantic/text/primary", "color/semantic/surface/subtle"],
+  Avatar:     ["color/semantic/surface/subtle", "radius/semantic/pill"],
+  Badge:      ["color/semantic/actions/primary/bg/default", "color/semantic/text/on-color", "radius/semantic/pill"],
+  Tooltip:    ["color/semantic/surface/inverse", "color/semantic/text/inverse", "elevation/semantic/shadow/md", "z-index/semantic/tooltip"],
+  Tabs:       ["color/semantic/border/subtle", "color/semantic/text/primary", "color/semantic/actions/primary/bg/default"],
+  Breadcrumb: ["color/semantic/text/primary", "color/semantic/text/tertiary", "color/semantic/actions/primary/bg/default"],
+  Tag:        ["color/semantic/surface/subtle", "color/semantic/border/default", "color/semantic/text/primary"],
+  Heading:    ["color/semantic/text/primary"],
+  Link:       ["color/semantic/actions/primary/bg/default"],
+};
+
+// ─── Token resolution ────────────────────────────────────────────────────────
+
+/**
+ * Look up a Figma variable ID by token name from the available tokens.
+ * Supports partial matching: "color/semantic/primary" matches token named
+ * "color/semantic/primary" or "Brand Tokens/color/semantic/primary".
+ */
+export function resolveTokenId(tokenName: string, tokens: Token[]): string | null {
+  // Exact match first
+  const exact = tokens.find((t) => t.name === tokenName);
+  if (exact) return exact.id;
+
+  // Suffix match (token name ends with the requested name)
+  const suffix = tokens.find((t) => t.name.endsWith(`/${tokenName}`) || t.name.endsWith(tokenName));
+  if (suffix) return suffix.id;
+
+  // Normalized comparison (strip slashes and compare lowercase)
+  const normalizedTarget = tokenName.toLowerCase().replace(/[\/\-_]/g, "");
+  const normalized = tokens.find((t) => {
+    const n = t.name.toLowerCase().replace(/[\/\-_]/g, "");
+    return n === normalizedTarget || n.endsWith(normalizedTarget);
+  });
+  if (normalized) return normalized.id;
+
+  return null;
+}
+
+/**
+ * Build a map of semantic role → variable ID from the available tokens.
+ * Used by tools that need to resolve multiple token references at once.
+ */
+export function buildTokenIdMap(tokens: Token[]): SemanticTokenMap {
+  const map: SemanticTokenMap = {};
+
+  for (const token of tokens) {
+    // Index by full name
+    map[token.name] = token.id;
+
+    // Also index by the last segment for quick lookup
+    const parts = token.name.split("/");
+    if (parts.length > 1) {
+      const shortName = parts.slice(-2).join("/");
+      if (!map[shortName]) {
+        map[shortName] = token.id;
+      }
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Resolve which token names are relevant for a given component type.
+ * Tries static map first, then concept taxonomy, then defaults.
+ */
+export function getTokenRolesForComponent(componentType: string): string[] {
+  // Try exact match in static map first (hand-tuned, highest quality)
+  if (COMPONENT_TOKEN_ROLES[componentType]) {
+    return COMPONENT_TOKEN_ROLES[componentType];
+  }
+
+  // Try case-insensitive match in static map
+  const lower = componentType.toLowerCase();
+  for (const [key, roles] of Object.entries(COMPONENT_TOKEN_ROLES)) {
+    if (key.toLowerCase() === lower) return roles;
+  }
+
+  // Try concept taxonomy (covers all components via typicalForms mapping)
+  const concept = getConceptForComponent(componentType);
+  if (concept) {
+    return getRequiredTokenPaths(concept.id);
+  }
+
+  // Default roles for unknown components
+  return ["color/surface/default", "color/text/primary", "color/border/default"];
+}
+
+/**
+ * Given a component type and available tokens, resolve the relevant token names
+ * to their variable IDs.
+ */
+export function resolveTokenRefsForComponent(
+  componentType: string,
+  tokens: Token[]
+): string[] {
+  const roles = getTokenRolesForComponent(componentType);
+  const resolved: string[] = [];
+
+  for (const role of roles) {
+    const id = resolveTokenId(role, tokens);
+    if (id) {
+      // Return the token name (not the ID) for the tokenRefs field
+      const token = tokens.find((t) => t.id === id);
+      if (token) resolved.push(token.name);
+    }
+  }
+
+  return resolved;
+}
+
+// ─── Script generators ───────────────────────────────────────────────────────
+
+/**
+ * Generate a Figma Plugin API script line that binds a color variable
+ * to a paint fill on a node.
+ *
+ * Example output:
+ *   const v = await figma.variables.getVariableByIdAsync("VariableID:1:2");
+ *   if (v) node.setBoundVariable('fills', 0, v.id);
+ */
+export function bindColorScript(
+  nodeVar: string,
+  fillIndex: number,
+  variableId: string,
+  paintType: "fills" | "strokes" = "fills"
+): string {
+  const varName = `__v_${fillIndex}_${paintType}`;
+  return `
+  {
+    const ${varName} = await figma.variables.getVariableByIdAsync(${JSON.stringify(variableId)});
+    if (${varName} && ${nodeVar}.${paintType} && ${nodeVar}.${paintType}.length > ${fillIndex}) {
+      const paints = [...${nodeVar}.${paintType}];
+      paints[${fillIndex}] = figma.variables.setBoundVariableForPaint(paints[${fillIndex}], 'color', ${varName});
+      ${nodeVar}.${paintType} = paints;
+    }
+  }`;
+}
+
+/**
+ * Generate a Figma Plugin API script line that binds a float variable
+ * to a node property (spacing, radius, etc.).
+ *
+ * Example output:
+ *   const v = await figma.variables.getVariableByIdAsync("VariableID:1:2");
+ *   if (v) node.setBoundVariable('paddingLeft', v.id);
+ */
+export function bindFloatScript(
+  nodeVar: string,
+  field: string,
+  variableId: string
+): string {
+  const safeField = field.replace(/[^a-zA-Z0-9_]/g, "");
+  const varName = `__v_${safeField}`;
+  return `
+  {
+    const ${varName} = await figma.variables.getVariableByIdAsync(${JSON.stringify(variableId)});
+    if (${varName}) ${nodeVar}.setBoundVariable('${field}', ${varName}.id);
+  }`;
+}
+
+/**
+ * Build a complete binding script for a single node, applying multiple
+ * token bindings. Returns empty string if no bindings.
+ */
+export function buildBindingScript(
+  nodeId: string,
+  bindings: TokenBinding[]
+): string {
+  if (bindings.length === 0) return "";
+
+  const lines: string[] = [];
+
+  for (const binding of bindings) {
+    if (binding.field === "fills" || binding.field === "strokes") {
+      lines.push(
+        bindColorScript(
+          binding.nodeVar,
+          binding.fillIndex ?? 0,
+          binding.variableId,
+          binding.field as "fills" | "strokes"
+        )
+      );
+    } else {
+      lines.push(
+        bindFloatScript(binding.nodeVar, binding.field, binding.variableId)
+      );
+    }
+  }
+
+  return `
+// ── Token bindings ──
+{
+  const __bindTarget = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+  if (__bindTarget) {
+    const ${bindings[0]?.nodeVar ?? "node"} = __bindTarget;
+    ${lines.join("\n    ")}
+  }
+}`;
+}
+
+/**
+ * Build a batch binding script that binds variables to multiple nodes
+ * in a single execute call. Designed for use via bridge.execute().
+ */
+export function buildBatchBindingScript(
+  bindings: Array<{ nodeId: string; field: string; variableId: string; fillIndex?: number }>
+): string {
+  if (bindings.length === 0) return "";
+
+  const bindingData = JSON.stringify(bindings);
+
+  return `
+(async () => {
+  const bindings = ${bindingData};
+  let bound = 0;
+
+  for (const b of bindings) {
+    const node = await figma.getNodeByIdAsync(b.nodeId);
+    if (!node) continue;
+
+    const variable = await figma.variables.getVariableByIdAsync(b.variableId);
+    if (!variable) continue;
+
+    if (b.field === 'fills' || b.field === 'strokes') {
+      const idx = b.fillIndex ?? 0;
+      if (node[b.field] && node[b.field].length > idx) {
+        const paints = [...node[b.field]];
+        paints[idx] = figma.variables.setBoundVariableForPaint(paints[idx], 'color', variable);
+        node[b.field] = paints;
+        bound++;
+      }
+    } else {
+      try {
+        node.setBoundVariable(b.field, variable.id);
+        bound++;
+      } catch (e) { /* skip unsupported fields */ }
+    }
+  }
+
+  return { bound, total: bindings.length };
+})();
+`.trim();
+}
+
+// ─── Palette resolution ──────────────────────────────────────────────────────
+
+/**
+ * Resolve a design palette from tokens, returning both the RGB values (for
+ * immediate use in fills) and the variable IDs (for binding). Falls back to
+ * hardcoded values if no tokens are found.
+ */
+export interface ResolvedPalette {
+  primary:     { rgb: string; variableId: string | null };
+  primaryText: { rgb: string; variableId: string | null };
+  surface:     { rgb: string; variableId: string | null };
+  border:      { rgb: string; variableId: string | null };
+  muted:       { rgb: string; variableId: string | null };
+  accent:      { rgb: string; variableId: string | null };
+}
+
+interface PaletteMapping {
+  role: keyof ResolvedPalette;
+  tokenNames: string[];    // Try these token names in order
+  fallbackRgb: string;     // Figma RGB object literal as string
+}
+
+const PALETTE_MAPPINGS: PaletteMapping[] = [
+  { role: "primary",     tokenNames: ["color/semantic/actions/primary/bg/default", "color/semantic/primary", "color/primary/500"],  fallbackRgb: "{ r: 0.09, g: 0.09, b: 0.09 }" },
+  { role: "primaryText", tokenNames: ["color/semantic/text/on-color", "color/text/on-primary", "color/semantic/primary-on"],       fallbackRgb: "{ r: 1, g: 1, b: 1 }" },
+  { role: "surface",     tokenNames: ["color/semantic/surface/default", "color/surface/default", "color/neutral/50"],               fallbackRgb: "{ r: 0.98, g: 0.98, b: 0.99 }" },
+  { role: "border",      tokenNames: ["color/semantic/border/default", "color/border/default", "color/neutral/200"],                fallbackRgb: "{ r: 0.90, g: 0.91, b: 0.93 }" },
+  { role: "muted",       tokenNames: ["color/semantic/text/secondary", "color/text/secondary", "color/text/disabled"],              fallbackRgb: "{ r: 0.45, g: 0.45, b: 0.50 }" },
+  { role: "accent",      tokenNames: ["color/semantic/actions/primary/bg/default", "color/semantic/primary", "color/primary/500"],  fallbackRgb: "{ r: 0.22, g: 0.35, b: 0.96 }" },
+];
+
+/**
+ * Convert a Figma color value (from a token) to an RGB string literal
+ * for use in generated scripts.
+ */
+function tokenValueToRgbString(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, number>;
+  if (typeof v.r !== "number" || typeof v.g !== "number" || typeof v.b !== "number") return null;
+  return `{ r: ${v.r.toFixed(3)}, g: ${v.g.toFixed(3)}, b: ${v.b.toFixed(3)} }`;
+}
+
+/**
+ * Resolve a design palette.
+ *
+ * When a design system is selected (dsId is provided), its tokens are the
+ * **authoritative** source — Figma file tokens are ignored entirely.
+ * When no DS is selected (dsId is null), file tokens are used as before.
+ */
+export function resolveDesignPalette(tokens: Token[], dsId?: string | null): ResolvedPalette {
+  // DS tokens are authoritative when a design system is selected
+  const effectiveTokens = dsId ? getDesignSystemTokens(dsId) : tokens;
+
+  const palette = {} as ResolvedPalette;
+
+  for (const mapping of PALETTE_MAPPINGS) {
+    let resolved = false;
+
+    for (const tokenName of mapping.tokenNames) {
+      const token = effectiveTokens.find(
+        (t) => t.type === "COLOR" && (t.name === tokenName || t.name.endsWith(`/${tokenName}`))
+      );
+      if (token) {
+        const rgb = tokenValueToRgbString(token.value) ?? mapping.fallbackRgb;
+        palette[mapping.role] = { rgb, variableId: token.id };
+        resolved = true;
+        break;
+      }
+    }
+
+    if (!resolved) {
+      palette[mapping.role] = { rgb: mapping.fallbackRgb, variableId: null };
+    }
+  }
+
+  return palette;
+}
+
+/**
+ * Resolve a float token (spacing, radius) value and variable ID.
+ * Returns the numeric value and optionally the variable ID for binding.
+ */
+export function resolveFloatToken(
+  tokenName: string,
+  tokens: Token[],
+  fallback: number
+): { value: number; variableId: string | null } {
+  const token = tokens.find(
+    (t) => t.type === "FLOAT" && (t.name === tokenName || t.name.endsWith(`/${tokenName}`))
+  );
+  if (token && typeof token.value === "number") {
+    return { value: token.value, variableId: token.id };
+  }
+  return { value: fallback, variableId: null };
+}
+
+// ─── Multi-mode variable binding ────────────────────────────────────────────
+
+export interface MultiModeBinding {
+  nodeId: string;
+  field: string;         // "fills" | "strokes" | "paddingLeft" | "cornerRadius" etc.
+  fillIndex?: number;
+  /** Variable ID of a semantic alias variable that already has Light/Dark values */
+  semanticVariableId: string;
+}
+
+/**
+ * Build a script that explicitly sets the *variable* mode on a frame and its
+ * descendants, ensuring components switch between Light/Dark (or any modes).
+ *
+ * Figma's mode switching works at the frame level via `setExplicitVariableModeForCollection`.
+ * This function:
+ *   1. Binds semantic variables to node properties (same as single-mode binding)
+ *   2. Sets the explicit variable mode on a container frame so all children
+ *      resolve the correct mode values automatically
+ *
+ * Usage: Call this after creating variables with ds-variables (which creates
+ * Light/Dark mode values). The semantic variable already has mode-specific
+ * values — this script binds it to nodes and sets which mode is active.
+ */
+export function buildMultiModeBindingScript(
+  bindings: MultiModeBinding[],
+  /** Frame node ID to set the explicit mode on (typically the root component frame) */
+  targetFrameId: string,
+  /** Collection ID the semantic variables belong to */
+  collectionId: string,
+  /** Mode ID to activate (e.g. the Dark mode ID) */
+  activeModeId: string
+): string {
+  if (bindings.length === 0 && !targetFrameId) return "";
+
+  const bindingData = JSON.stringify(bindings);
+
+  return `
+(async () => {
+  const bindings = ${bindingData};
+  let bound = 0;
+  const errors = [];
+
+  // Step 1: Bind semantic variables to node properties
+  for (const b of bindings) {
+    try {
+      const node = await figma.getNodeByIdAsync(b.nodeId);
+      if (!node) { errors.push('Node not found: ' + b.nodeId); continue; }
+
+      const variable = await figma.variables.getVariableByIdAsync(b.semanticVariableId);
+      if (!variable) { errors.push('Variable not found: ' + b.semanticVariableId); continue; }
+
+      if (b.field === 'fills' || b.field === 'strokes') {
+        const idx = b.fillIndex ?? 0;
+        if (node[b.field] && node[b.field].length > idx) {
+          const paints = [...node[b.field]];
+          paints[idx] = figma.variables.setBoundVariableForPaint(paints[idx], 'color', variable);
+          node[b.field] = paints;
+          bound++;
+        }
+      } else {
+        node.setBoundVariable(b.field, variable.id);
+        bound++;
+      }
+    } catch (e) {
+      errors.push('Bind error: ' + (e.message || e));
+    }
+  }
+
+  // Step 2: Set the explicit variable mode on the target frame
+  let modeSet = false;
+  if (${JSON.stringify(targetFrameId)} && ${JSON.stringify(collectionId)} && ${JSON.stringify(activeModeId)}) {
+    try {
+      const frame = await figma.getNodeByIdAsync(${JSON.stringify(targetFrameId)});
+      if (frame && 'setExplicitVariableModeForCollection' in frame) {
+        frame.setExplicitVariableModeForCollection(${JSON.stringify(collectionId)}, ${JSON.stringify(activeModeId)});
+        modeSet = true;
+      }
+    } catch (e) {
+      errors.push('Mode set error: ' + (e.message || e));
+    }
+  }
+
+  return { bound, total: bindings.length, modeSet, errors: errors.length > 0 ? errors : undefined };
+})();
+`.trim();
+}
+
+/**
+ * Build a script that resolves ALL modes for a collection and returns them,
+ * so callers can pick which mode ID to use for switching.
+ */
+export function buildListModesScript(collectionId: string): string {
+  return `
+(async () => {
+  const col = await figma.variables.getVariableCollectionByIdAsync(${JSON.stringify(collectionId)});
+  if (!col) return { error: 'Collection not found' };
+  return {
+    collectionId: col.id,
+    collectionName: col.name,
+    modes: col.modes.map(m => ({ modeId: m.modeId, name: m.name })),
+    variableCount: col.variableIds.length,
+  };
+})();
+`.trim();
+}
+
+/**
+ * Build a script that switches a frame (and all its children) to a different
+ * variable mode. This is the simplest "theme switch" operation.
+ */
+export function buildModeSwitchScript(
+  frameId: string,
+  collectionId: string,
+  modeId: string
+): string {
+  return `
+(async () => {
+  const frame = await figma.getNodeByIdAsync(${JSON.stringify(frameId)});
+  if (!frame) return { error: 'Frame not found: ${frameId}' };
+  if (!('setExplicitVariableModeForCollection' in frame)) {
+    return { error: 'Node does not support explicit variable modes (must be a frame-like node)' };
+  }
+  frame.setExplicitVariableModeForCollection(${JSON.stringify(collectionId)}, ${JSON.stringify(modeId)});
+  return { success: true, frameId: frame.id, frameName: frame.name, collectionId: ${JSON.stringify(collectionId)}, modeId: ${JSON.stringify(modeId)} };
+})();
+`.trim();
+}