@servicetitan/hammer-token 2.5.1 → 3.0.0

package/src/utils/figma/sync-components.js

@@ -0,0 +1,909 @@
+#!/usr/bin/env node
+
+/**
+ * Component Token Sync
+ *
+ * Functions for building variable requests for component tokens.
+ */
+
+const { isComponentToken } = require("./token-parsing");
+const {
+  isReference,
+  isCompositeColorWithReference,
+  extractReferencePath,
+  resolveMultipleReferences,
+  resolveReferencePath,
+  resolveValue,
+  topologicalSortSemanticTokens,
+  getTokenDescription,
+  buildReferenceChain,
+} = require("./token-resolution");
+const {
+  convertColorValue,
+  convertTokenValueToFigma,
+  getFigmaVariableType,
+  isGradientToken,
+  parseGradientStops,
+} = require("./token-conversion");
+const {
+  valuesEqual,
+  getVariableIdByName,
+  determineVariableName: determineVariableNameHelper,
+} = require("./figma-api");
+/**
+ * Get Figma variable scopes from token $extensions["com.figma.scopes"]. Missing or empty = ["ALL_SCOPES"].
+ * @param {Object} [token] - Leaf token object
+ * @returns {string[]} Scopes array
+ */
+function getScopesForVariable(token) {
+  const fromToken = token?.$extensions?.["com.figma.scopes"];
+  return Array.isArray(fromToken) && fromToken.length > 0
+    ? fromToken
+    : ["ALL_SCOPES"];
+}
+
+/**
+ * Determine the variable name for a token path (wrapper that includes isComponentToken)
+ * @param {string} targetPath - Token path (e.g., "color/neutral/0")
+ * @param {Map} resolvedTokensForRefs - Map of resolved tokens for reference resolution
+ * @param {Array} existingVariables - Array of existing Figma variables
+ * @param {Map} tempIdMap - Temporary ID map for tracking created variables
+ * @returns {string} Variable name with correct prefix (primitive/, semantic/, or component/)
+ */
+function determineVariableName(
+  targetPath,
+  resolvedTokensForRefs,
+  existingVariables,
+  tempIdMap,
+) {
+  return determineVariableNameHelper(
+    targetPath,
+    resolvedTokensForRefs,
+    existingVariables,
+    tempIdMap,
+    isComponentToken,
+  );
+}
+
+/**
+ * Build bulk request for component variable changes only
+ * Similar to buildSemanticVariableRequest but for component tokens
+ * Returns an object with variables array and variableModeValues array
+ * @param {Map} tokensToSync - Map of tokens to sync (may be filtered for extended themes)
+ * @param {Array} existingVariables - Array of existing variables
+ * @param {string} collectionId - Collection ID
+ * @param {Object} modes - Modes object with light and dark
+ * @param {Map} tempIdMap - Temporary ID map for tracking created variables
+ * @param {Map} [allResolvedTokens] - Optional full map of all resolved tokens for reference resolution
+ * @returns {Object} Object with variableChanges, variableModeValues, stats, errors, and tempIdMap
+ */
+function buildComponentVariableRequest(
+  tokensToSync,
+  existingVariables,
+  collectionId,
+  modes,
+  tempIdMap = new Map(),
+  allResolvedTokens = null,
+) {
+  const variableChanges = [];
+  const variableModeValues = [];
+  const stats = { created: 0, updated: 0, skipped: 0, deleted: 0, errors: 0 };
+  const errors = [];
+
+  // Use allResolvedTokens for reference resolution if provided, otherwise use tokensToSync
+  const resolvedTokensForRefs = allResolvedTokens || tokensToSync;
+
+  // Filter to only component tokens (exclude primitives and semantic tokens)
+  const componentTokens = [];
+  for (const [tokenPath, tokenData] of tokensToSync.entries()) {
+    if (!tokenData.isPrimitive && isComponentToken(tokenData.sourceFilePath)) {
+      componentTokens.push([tokenPath, tokenData]);
+    }
+  }
+
+  const keptComponentNames = new Set();
+  for (const [path, tokenData] of componentTokens) {
+    const tokenType = tokenData.token.$type || "string";
+    if (isGradientToken(tokenType)) {
+      // Gradient tokens expand to per-stop variables; don't keep the composite name
+      const gradRefValue = tokenData.token.$value;
+      const refPath =
+        typeof gradRefValue === "string" && gradRefValue.includes("{")
+          ? gradRefValue.match(/\{([^{}]+)\}/)?.[1]?.replace(/\./g, "/")
+          : null;
+      const semToken = refPath ? resolvedTokensForRefs.get(refPath) : null;
+      const gradientValue =
+        semToken && typeof semToken.token.$value === "object"
+          ? semToken.token.$value
+          : typeof gradRefValue === "object"
+            ? gradRefValue
+            : null;
+      const stops = parseGradientStops(gradientValue);
+      if (stops) {
+        for (let i = 0; i < stops.length; i++) {
+          keptComponentNames.add(`component/${path}/stop-${i}`);
+        }
+      } else {
+        keptComponentNames.add(`component/${path}`);
+      }
+    } else {
+      keptComponentNames.add(`component/${path}`);
+    }
+  }
+
+  // Topologically sort component tokens to process dependencies first
+  const sortedComponentTokens = topologicalSortSemanticTokens(
+    componentTokens,
+    resolvedTokensForRefs,
+  );
+
+  // Validate modes before processing
+  if (!modes?.light || !modes?.dark) {
+    const errorMsg = `Modes are missing: light=${!!modes?.light}, dark=${!!modes?.dark}`;
+    errors.push(errorMsg);
+    stats.errors++;
+  }
+  if (!modes?.light?.id || !modes?.dark?.id) {
+    const errorMsg = `Mode IDs are missing: light.id=${modes?.light?.id}, dark.id=${modes?.dark?.id}`;
+    errors.push(errorMsg);
+    stats.errors++;
+  }
+
+  // Process component tokens in dependency order
+  for (const [tokenPath, tokenData] of sortedComponentTokens) {
+    try {
+      const { token, resolvedLight, resolvedDark } = tokenData;
+      const tokenType = token.$type || "string";
+
+      // Add "component/" prefix to variable name for organization
+      const variableName = `component/${tokenPath}`;
+
+      // Special handling for gradient tokens: unpack each stop into a COLOR variable
+      // that aliases the corresponding semantic stop variable.
+      if (isGradientToken(tokenType)) {
+        const gradRefValue = token.$value;
+        const refPath =
+          typeof gradRefValue === "string" && gradRefValue.includes("{")
+            ? gradRefValue.match(/\{([^{}]+)\}/)?.[1]?.replace(/\./g, "/")
+            : null;
+
+        // Case 1: reference to semantic gradient token (e.g., "{gradient.primary}")
+        // Case 2: inline gradient object (e.g., toast-specific gradients)
+        const isInlineGradient = !refPath && typeof gradRefValue === "object";
+
+        if (!refPath && !isInlineGradient) {
+          errors.push(`Could not extract gradient reference from ${tokenPath}`);
+          stats.errors++;
+          continue;
+        }
+
+        let gradientValue = null;
+
+        if (refPath) {
+          const semTokenData = resolvedTokensForRefs.get(refPath);
+          if (!semTokenData) {
+            errors.push(
+              `Could not find semantic gradient token ${refPath} for ${tokenPath}`,
+            );
+            stats.errors++;
+            continue;
+          }
+          gradientValue =
+            typeof semTokenData.token.$value === "object"
+              ? semTokenData.token.$value
+              : null;
+        } else {
+          gradientValue = gradRefValue;
+        }
+
+        const stops = parseGradientStops(gradientValue);
+
+        if (!stops) {
+          errors.push(`Could not parse gradient stops for ${tokenPath}`);
+          stats.errors++;
+          continue;
+        }
+
+        const gradientDescription = getTokenDescription(
+          token,
+          resolvedTokensForRefs,
+        );
+
+        for (let i = 0; i < stops.length; i++) {
+          const stopVariableName = `${variableName}/stop-${i}`;
+          const stopTokenPath = `${tokenPath}/stop-${i}`;
+          const { lightRef: stopLightRef, darkRef: stopDarkRef } = stops[i];
+          const lightChain =
+            buildReferenceChain(stopLightRef, resolvedTokensForRefs) ||
+            stopLightRef;
+          const darkChain =
+            buildReferenceChain(stopDarkRef, resolvedTokensForRefs) ||
+            stopDarkRef;
+          const stopColorDetail =
+            stopLightRef === stopDarkRef
+              ? lightChain
+              : `light: ${lightChain}, dark: ${darkChain}`;
+          const rawPosition = gradientValue.stops[i]?.position;
+          const stopPosition =
+            typeof rawPosition === "number"
+              ? `${rawPosition * 100}%`
+              : String(rawPosition ?? i);
+          const stopDescription = gradientDescription
+            ? `${gradientDescription}\nstop ${i} at ${stopPosition}: ${stopColorDetail}`
+            : `stop ${i} at ${stopPosition}: ${stopColorDetail}`;
+
+          let lightAliasId, darkAliasId;
+
+          if (refPath) {
+            // Reference case: alias both modes to the same semantic stop variable
+            // (the semantic stop variable already encodes light/dark per-mode)
+            const semanticStopVariableName = `semantic/${refPath}/stop-${i}`;
+            const semanticStopTokenPath = `${refPath}/stop-${i}`;
+            const aliasId =
+              tempIdMap.get(semanticStopTokenPath) ||
+              tempIdMap.get(semanticStopVariableName) ||
+              getVariableIdByName(
+                semanticStopVariableName,
+                existingVariables,
+              ) ||
+              getVariableIdByName(semanticStopTokenPath, existingVariables);
+
+            if (!aliasId) {
+              errors.push(
+                `Could not resolve alias for ${stopTokenPath} -> ${semanticStopVariableName}`,
+              );
+              stats.errors++;
+              continue;
+            }
+            lightAliasId = aliasId;
+            darkAliasId = aliasId;
+          } else {
+            // Inline case: resolve each stop's color reference to a semantic variable
+            const { lightRef, darkRef } = stops[i];
+            const lightRefPath = extractReferencePath(lightRef) ?? lightRef;
+            const lightTargetPath = resolveReferencePath(
+              lightRefPath,
+              resolvedTokensForRefs,
+            );
+            const lightTargetVariableName = determineVariableName(
+              lightTargetPath,
+              resolvedTokensForRefs,
+              existingVariables,
+              tempIdMap,
+            );
+            lightAliasId =
+              tempIdMap.get(lightTargetPath) ||
+              tempIdMap.get(lightTargetVariableName) ||
+              getVariableIdByName(lightTargetVariableName, existingVariables) ||
+              getVariableIdByName(lightTargetPath, existingVariables);
+
+            if (!lightAliasId) {
+              errors.push(
+                `Could not resolve light alias for ${stopTokenPath} -> ${lightTargetPath}`,
+              );
+              stats.errors++;
+              continue;
+            }
+
+            const darkRefPath = extractReferencePath(darkRef) ?? darkRef;
+            const darkTargetPath = resolveReferencePath(
+              darkRefPath,
+              resolvedTokensForRefs,
+            );
+            const darkTargetVariableName = determineVariableName(
+              darkTargetPath,
+              resolvedTokensForRefs,
+              existingVariables,
+              tempIdMap,
+            );
+            darkAliasId =
+              tempIdMap.get(darkTargetPath) ||
+              tempIdMap.get(darkTargetVariableName) ||
+              getVariableIdByName(darkTargetVariableName, existingVariables) ||
+              getVariableIdByName(darkTargetPath, existingVariables);
+
+            if (!darkAliasId) {
+              errors.push(
+                `Could not resolve dark alias for ${stopTokenPath} -> ${darkTargetPath}`,
+              );
+              stats.errors++;
+              continue;
+            }
+          }
+
+          const lightFigmaValue = { type: "VARIABLE_ALIAS", id: lightAliasId };
+          const darkFigmaValue = { type: "VARIABLE_ALIAS", id: darkAliasId };
+
+          // Get scopes from the stop color's extensions on the semantic token
+          const stopColor = gradientValue.stops[i]?.color;
+          const stopScopes =
+            Array.isArray(stopColor?.$extensions?.["com.figma.scopes"]) &&
+            stopColor.$extensions["com.figma.scopes"].length > 0
+              ? stopColor.$extensions["com.figma.scopes"]
+              : ["ALL_SCOPES"];
+
+          const existingId = getVariableIdByName(
+            stopVariableName,
+            existingVariables,
+          );
+          let existing = null;
+          if (existingId) {
+            existing =
+              existingVariables.length > 100
+                ? (() => {
+                    const m = new Map(
+                      existingVariables
+                        .filter((v) => v.id)
+                        .map((v) => [v.id, v]),
+                    );
+                    return m.get(existingId) || null;
+                  })()
+                : existingVariables.find((v) => v.id === existingId) || null;
+          }
+
+          if (existing) {
+            const existingValues = existing.valuesByMode || {};
+            const lightSame = valuesEqual(
+              existingValues[modes.light.id],
+              lightFigmaValue,
+            );
+            const darkSame = valuesEqual(
+              existingValues[modes.dark.id],
+              darkFigmaValue,
+            );
+            const sortedUpdate = [...stopScopes].sort();
+            const sortedExisting = [...(existing.scopes ?? [])].sort();
+            const scopesEqual =
+              sortedUpdate.length === sortedExisting.length &&
+              sortedUpdate.every((s, idx) => s === sortedExisting[idx]);
+
+            const stopDescriptionSame =
+              (existing.description || "") === stopDescription;
+            if (lightSame && darkSame && scopesEqual && stopDescriptionSame) {
+              tempIdMap.set(stopTokenPath, existing.id);
+              tempIdMap.set(stopVariableName, existing.id);
+              stats.skipped++;
+              continue;
+            }
+
+            variableChanges.push({
+              action: "UPDATE",
+              id: existing.id,
+              name: stopVariableName,
+              scopes: stopScopes,
+              description: stopDescription,
+            });
+            variableModeValues.push(
+              {
+                variableId: existing.id,
+                modeId: modes.light.id,
+                value: lightFigmaValue,
+              },
+              {
+                variableId: existing.id,
+                modeId: modes.dark.id,
+                value: darkFigmaValue,
+              },
+            );
+            tempIdMap.set(stopTokenPath, existing.id);
+            tempIdMap.set(stopVariableName, existing.id);
+            stats.updated++;
+          } else {
+            const tempIdCounter = tempIdMap.size + variableChanges.length + 1;
+            const tempId = `temp_var_${tempIdCounter}_${stopVariableName.replace(/\//g, "_").replace(/[^a-zA-Z0-9_]/g, "_")}`;
+            tempIdMap.set(stopTokenPath, tempId);
+            tempIdMap.set(stopVariableName, tempId);
+
+            variableChanges.push({
+              action: "CREATE",
+              id: tempId,
+              name: stopVariableName,
+              variableCollectionId: collectionId,
+              resolvedType: "COLOR",
+              scopes: stopScopes,
+              description: stopDescription,
+            });
+            variableModeValues.push(
+              {
+                variableId: tempId,
+                modeId: modes.light.id,
+                value: lightFigmaValue,
+              },
+              {
+                variableId: tempId,
+                modeId: modes.dark.id,
+                value: darkFigmaValue,
+              },
+            );
+            stats.created++;
+          }
+        }
+
+        // Skip normal processing — the gradient composite token has no Figma variable
+        continue;
+      }
+
+      // Check if this should be an alias (only for direct string references, not composite colors)
+      const isLightReference = isReference(resolvedLight);
+      const isDarkReference = isReference(resolvedDark);
+      const isLightCompositeWithRef =
+        isCompositeColorWithReference(resolvedLight);
+      const isDarkCompositeWithRef =
+        isCompositeColorWithReference(resolvedDark);
+
+      let lightFigmaValue;
+      let darkFigmaValue;
+      let lightAliasId = null;
+      let darkAliasId = null;
+
+      // Handle composite colors with references - resolve the color and apply alpha
+      if (isLightCompositeWithRef) {
+        const refString = resolvedLight.color;
+        const refPath = extractReferencePath(refString);
+        if (!refPath) {
+          errors.push(
+            `Could not extract reference path from ${refString} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        const targetPath = resolveReferencePath(refPath, resolvedTokensForRefs);
+        const targetTokenData = resolvedTokensForRefs.get(targetPath);
+        if (!targetTokenData) {
+          errors.push(
+            `Could not find target token ${targetPath} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        let resolvedColorValue = targetTokenData.resolvedLight;
+        if (!resolvedColorValue) {
+          errors.push(
+            `Target token ${targetPath} has no resolved light value for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Semantic tokens may have resolvedLight still as a reference (e.g. "{color.neutral.950}"); resolve to literal
+        if (isReference(resolvedColorValue)) {
+          resolvedColorValue = resolveValue(
+            resolvedColorValue,
+            resolvedTokensForRefs,
+            false,
+          );
+        }
+
+        const baseColor = convertColorValue(resolvedColorValue);
+        if (baseColor === null) {
+          errors.push(
+            `Could not convert resolved color value for ${tokenPath}: ${JSON.stringify(resolvedColorValue)}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        lightFigmaValue = {
+          ...baseColor,
+          a: resolvedLight.alpha ?? resolvedLight.a ?? baseColor.a,
+        };
+      } else if (isLightReference) {
+        // Direct string reference - create alias
+        const refPath = extractReferencePath(resolvedLight);
+        if (!refPath) {
+          errors.push(
+            `Could not extract reference path from ${resolvedLight} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        const targetPath = resolveReferencePath(refPath, resolvedTokensForRefs);
+        // Determine the correct variable name based on token type
+        const targetVariableName = determineVariableName(
+          targetPath,
+          resolvedTokensForRefs,
+          existingVariables,
+          tempIdMap,
+        );
+        lightAliasId =
+          tempIdMap.get(targetPath) ||
+          tempIdMap.get(targetVariableName) ||
+          getVariableIdByName(targetVariableName, existingVariables) ||
+          getVariableIdByName(targetPath, existingVariables);
+
+        if (!lightAliasId) {
+          const errorMsg = `Could not resolve light alias for ${tokenPath} -> ${targetPath}`;
+          errors.push(errorMsg);
+          stats.errors++;
+          continue;
+        }
+
+        lightFigmaValue = { type: "VARIABLE_ALIAS", id: lightAliasId };
+      } else {
+        // Check if the value is a string with multiple references
+        let valueToConvert = resolvedLight;
+        if (
+          typeof resolvedLight === "string" &&
+          resolvedLight.includes("{") &&
+          resolvedLight.includes("}") &&
+          !isReference(resolvedLight)
+        ) {
+          valueToConvert = resolveMultipleReferences(
+            resolvedLight,
+            resolvedTokensForRefs,
+            false,
+          );
+        }
+
+        // When value is currentColor, use com.figma.alternateValue.mode if present
+        if (valueToConvert === "currentColor") {
+          const altMode = token.$extensions?.["com.figma.alternateValue"]?.mode;
+          if (altMode?.light != null) {
+            let altLight = altMode.light;
+            if (isReference(altLight)) {
+              altLight = resolveValue(altLight, resolvedTokensForRefs, false);
+            }
+            const converted = convertColorValue(altLight);
+            if (converted !== null) {
+              lightFigmaValue = converted;
+            } else {
+              errors.push(
+                `Could not convert com.figma.alternateValue.mode.light for ${tokenPath}: ${JSON.stringify(altMode.light)}`,
+              );
+              stats.errors++;
+              continue;
+            }
+          } else {
+            errors.push(
+              `Token ${tokenPath} uses currentColor but has no com.figma.alternateValue.mode (required for Figma sync)`,
+            );
+            stats.errors++;
+            continue;
+          }
+        } else {
+          const converted = convertTokenValueToFigma(
+            tokenType,
+            valueToConvert,
+            {
+              tokenPath,
+              scopes: getScopesForVariable(token),
+            },
+          );
+          if (converted === null) {
+            errors.push(`Could not convert light value for ${tokenPath}`);
+            stats.errors++;
+            continue;
+          }
+          lightFigmaValue = converted;
+        }
+      }
+
+      // Handle dark mode values (same logic as light)
+      if (isDarkCompositeWithRef) {
+        const refString = resolvedDark.color;
+        const refPath = extractReferencePath(refString);
+        if (!refPath) {
+          errors.push(
+            `Could not extract reference path from ${refString} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        const targetPath = resolveReferencePath(refPath, resolvedTokensForRefs);
+        const targetTokenData = resolvedTokensForRefs.get(targetPath);
+        if (!targetTokenData) {
+          errors.push(
+            `Could not find target token ${targetPath} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        let resolvedColorValueDark = targetTokenData.resolvedDark;
+        if (!resolvedColorValueDark) {
+          errors.push(
+            `Target token ${targetPath} has no resolved dark value for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        if (isReference(resolvedColorValueDark)) {
+          resolvedColorValueDark = resolveValue(
+            resolvedColorValueDark,
+            resolvedTokensForRefs,
+            true,
+          );
+        }
+
+        const baseColorDark = convertColorValue(resolvedColorValueDark);
+        if (baseColorDark === null) {
+          errors.push(
+            `Could not convert resolved color value for ${tokenPath}: ${JSON.stringify(resolvedColorValueDark)}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        darkFigmaValue = {
+          ...baseColorDark,
+          a: resolvedDark.alpha ?? resolvedDark.a ?? baseColorDark.a,
+        };
+      } else if (isDarkReference) {
+        const refPath = extractReferencePath(resolvedDark);
+        if (!refPath) {
+          errors.push(
+            `Could not extract reference path from ${resolvedDark} for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        const targetPath = resolveReferencePath(refPath, resolvedTokensForRefs);
+        // Determine the correct variable name based on token type
+        const targetVariableName = determineVariableName(
+          targetPath,
+          resolvedTokensForRefs,
+          existingVariables,
+          tempIdMap,
+        );
+        darkAliasId =
+          tempIdMap.get(targetPath) ||
+          tempIdMap.get(targetVariableName) ||
+          getVariableIdByName(targetVariableName, existingVariables) ||
+          getVariableIdByName(targetPath, existingVariables);
+
+        if (!darkAliasId) {
+          const errorMsg = `Could not resolve dark alias for ${tokenPath} -> ${targetPath}`;
+          errors.push(errorMsg);
+          stats.errors++;
+          continue;
+        }
+
+        darkFigmaValue = { type: "VARIABLE_ALIAS", id: darkAliasId };
+      } else {
+        let valueToConvert = resolvedDark;
+        if (
+          typeof resolvedDark === "string" &&
+          resolvedDark.includes("{") &&
+          resolvedDark.includes("}") &&
+          !isReference(resolvedDark)
+        ) {
+          valueToConvert = resolveMultipleReferences(
+            resolvedDark,
+            resolvedTokensForRefs,
+            true,
+          );
+        }
+
+        // When value is currentColor, use com.figma.alternateValue.mode if present
+        if (valueToConvert === "currentColor") {
+          const altMode = token.$extensions?.["com.figma.alternateValue"]?.mode;
+          if (altMode?.dark != null) {
+            let altDark = altMode.dark;
+            if (isReference(altDark)) {
+              altDark = resolveValue(altDark, resolvedTokensForRefs, true);
+            }
+            const converted = convertColorValue(altDark);
+            if (converted !== null) {
+              darkFigmaValue = converted;
+            } else {
+              errors.push(
+                `Could not convert com.figma.alternateValue.mode.dark for ${tokenPath}: ${JSON.stringify(altMode.dark)}`,
+              );
+              stats.errors++;
+              continue;
+            }
+          } else if (lightFigmaValue != null) {
+            // No dark alternate; reuse light value so the variable has both modes
+            darkFigmaValue = lightFigmaValue;
+          } else {
+            errors.push(
+              `Token ${tokenPath} uses currentColor but has no com.figma.alternateValue.mode (required for Figma sync)`,
+            );
+            stats.errors++;
+            continue;
+          }
+        } else {
+          const converted = convertTokenValueToFigma(
+            tokenType,
+            valueToConvert,
+            {
+              tokenPath,
+              scopes: getScopesForVariable(token),
+            },
+          );
+          if (converted === null) {
+            errors.push(`Could not convert dark value for ${tokenPath}`);
+            stats.errors++;
+            continue;
+          }
+          darkFigmaValue = converted;
+        }
+      }
+
+      // Get existing variable - optimize with getVariableIdByName
+      const existingId =
+        getVariableIdByName(variableName, existingVariables) ||
+        getVariableIdByName(tokenPath, existingVariables);
+      // Optimize: Use Map for O(1) lookup if we have many variables
+      let existing = null;
+      if (existingId) {
+        if (existingVariables.length > 100) {
+          const variableIdMap = new Map();
+          for (const v of existingVariables) {
+            if (v.id) variableIdMap.set(v.id, v);
+          }
+          existing = variableIdMap.get(existingId) || null;
+        } else {
+          existing = existingVariables.find((v) => v.id === existingId);
+        }
+      }
+
+      if (existing) {
+        if (!existing.id) {
+          const errorMsg = `Existing variable for ${tokenPath} has no ID`;
+          errors.push(errorMsg);
+          stats.errors++;
+          continue;
+        }
+
+        if (!modes.light?.id || !modes.dark?.id) {
+          errors.push(
+            `Mode IDs are missing: light=${modes.light?.id}, dark=${modes.dark?.id}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Check if values are the same
+        const existingValues = existing.valuesByMode || {};
+        const existingLight = existingValues[modes.light.id];
+        const existingDark = existingValues[modes.dark.id];
+
+        const lightSame = valuesEqual(existingLight, lightFigmaValue);
+        const darkSame = valuesEqual(existingDark, darkFigmaValue);
+
+        const updateScopes = getScopesForVariable(tokenData.token);
+        const existingScopes = existing.scopes || [];
+        const sortedUpdate = [...updateScopes].sort();
+        const sortedExisting = [...existingScopes].sort();
+        const scopesEqual =
+          sortedUpdate.length === sortedExisting.length &&
+          sortedUpdate.every((s, i) => s === sortedExisting[i]);
+
+        const tokenDescription = getTokenDescription(
+          token,
+          resolvedTokensForRefs,
+        );
+        const descriptionSame =
+          (existing.description || "") === tokenDescription;
+
+        if (lightSame && darkSame) {
+          // Values unchanged: still send UPDATE if scopes or description need to be applied/updated
+          if (!scopesEqual || !descriptionSame) {
+            variableChanges.push({
+              action: "UPDATE",
+              id: existing.id,
+              name: variableName,
+              scopes: updateScopes,
+              description: tokenDescription,
+            });
+            stats.updated++;
+          } else {
+            stats.skipped++;
+          }
+          tempIdMap.set(tokenPath, existing.id);
+          tempIdMap.set(variableName, existing.id);
+          continue;
+        }
+
+        // Update variable (values changed) — always send our scopes so Figma matches code
+        const updatePayload = {
+          action: "UPDATE",
+          id: existing.id,
+          name: variableName,
+          scopes: updateScopes,
+          description: tokenDescription,
+        };
+        variableChanges.push(updatePayload);
+
+        variableModeValues.push(
+          {
+            variableId: existing.id,
+            modeId: modes.light.id,
+            value: lightFigmaValue,
+          },
+          {
+            variableId: existing.id,
+            modeId: modes.dark.id,
+            value: darkFigmaValue,
+          },
+        );
+
+        tempIdMap.set(tokenPath, existing.id);
+        tempIdMap.set(variableName, existing.id);
+        stats.updated++;
+      } else {
+        // Validate mode IDs before creating new variable
+        if (!modes.light?.id || !modes.dark?.id) {
+          errors.push(
+            `Mode IDs are missing: light.id=${modes.light?.id}, dark.id=${modes.dark?.id}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Create new variable with temporary ID
+        const tempIdCounter = tempIdMap.size + variableChanges.length + 1;
+        const tempId = `temp_var_${tempIdCounter}_${variableName.replace(/\//g, "_").replace(/[^a-zA-Z0-9_]/g, "_")}`;
+        tempIdMap.set(tokenPath, tempId);
+        tempIdMap.set(variableName, tempId);
+
+        // Determine variable type based on the actual resolved value
+        let variableType = getFigmaVariableType(tokenType);
+        if (
+          variableType === "FLOAT" &&
+          typeof lightFigmaValue === "string" &&
+          lightFigmaValue.includes(" ")
+        ) {
+          variableType = "STRING";
+        }
+
+        const createScopes = getScopesForVariable(tokenData.token);
+        const createPayload = {
+          action: "CREATE",
+          id: tempId,
+          name: variableName,
+          variableCollectionId: collectionId,
+          resolvedType: variableType,
+          description: getTokenDescription(token, resolvedTokensForRefs),
+        };
+        createPayload.scopes = createScopes;
+        variableChanges.push(createPayload);
+
+        variableModeValues.push(
+          {
+            variableId: tempId,
+            modeId: modes.light.id,
+            value: lightFigmaValue,
+          },
+          {
+            variableId: tempId,
+            modeId: modes.dark.id,
+            value: darkFigmaValue,
+          },
+        );
+
+        stats.created++;
+      }
+    } catch (error) {
+      errors.push(`${tokenPath}: ${error.message}`);
+      stats.errors++;
+    }
+  }
+
+  // Delete component variables that are no longer in token source
+  for (const v of existingVariables) {
+    if (v.name?.startsWith("component/") && !keptComponentNames.has(v.name)) {
+      variableChanges.push({ action: "DELETE", id: v.id });
+      stats.deleted++;
+    }
+  }
+
+  return {
+    variableChanges,
+    variableModeValues,
+    stats,
+    errors,
+    tempIdMap,
+  };
+}
+
+module.exports = {
+  buildComponentVariableRequest,
+};