@servicetitan/hammer-token 2.5.0 → 3.0.0

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

@@ -0,0 +1,1056 @@
+#!/usr/bin/env node
+
+/**
+ * Semantic Token Sync
+ *
+ * Functions for building variable requests for semantic (non-component) tokens.
+ */
+
+const { isComponentToken } = require("./token-parsing");
+const {
+  isReference,
+  isCompositeColorWithReference,
+  extractReferencePath,
+  resolveMultipleReferences,
+  resolveReferencePath,
+  topologicalSortSemanticTokens,
+  getTokenDescription,
+  buildReferenceChain,
+} = require("./token-resolution");
+const {
+  convertColorValue,
+  convertTokenValueToFigma,
+  getFigmaVariableType,
+  isShadowSizeToken,
+  parseShadowSizeValue,
+  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 semantic variable changes only
+ * 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 buildSemanticVariableRequest(
+  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 = [];
+  const keptSemanticNames = new Set();
+
+  // Use allResolvedTokens for reference resolution if provided, otherwise use tokensToSync
+  const resolvedTokensForRefs = allResolvedTokens || tokensToSync;
+
+  // Filter to only semantic tokens (exclude primitives and component tokens)
+  const semanticTokens = [];
+  for (const [tokenPath, tokenData] of tokensToSync.entries()) {
+    if (!tokenData.isPrimitive && !isComponentToken(tokenData.sourceFilePath)) {
+      semanticTokens.push([tokenPath, tokenData]);
+    }
+  }
+
+  // Topologically sort semantic tokens to process dependencies first
+  const sortedSemanticTokens = topologicalSortSemanticTokens(
+    semanticTokens,
+    resolvedTokensForRefs,
+  );
+
+  // Validate modes before processing
+  if (!modes?.light || !modes?.dark) {
+    errors.push(
+      `Modes are missing: light=${!!modes?.light}, dark=${!!modes?.dark}`,
+    );
+    stats.errors++;
+  }
+  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++;
+  }
+
+  // Process semantic tokens in dependency order
+  for (const [tokenPath, tokenData] of sortedSemanticTokens) {
+    try {
+      const { token, resolvedLight, resolvedDark } = tokenData;
+      const tokenType = token.$type || "string";
+
+      // Add "semantic/" prefix to variable name for organization
+      const variableName = `semantic/${tokenPath}`;
+
+      // Track kept variable names for delete detection (remove vars no longer in token source)
+      if (
+        isShadowSizeToken(tokenPath) &&
+        typeof resolvedLight === "string" &&
+        typeof resolvedDark === "string"
+      ) {
+        const lightComponents = parseShadowSizeValue(resolvedLight);
+        const darkComponents = parseShadowSizeValue(resolvedDark);
+        if (lightComponents && darkComponents) {
+          keptSemanticNames.add(`${variableName}/x`);
+          keptSemanticNames.add(`${variableName}/y`);
+          keptSemanticNames.add(`${variableName}/blur`);
+        } else {
+          keptSemanticNames.add(variableName);
+        }
+      } else if (isGradientToken(tokenType)) {
+        const gradientValue =
+          typeof token.$value === "object" ? token.$value : null;
+        const stops = parseGradientStops(gradientValue);
+        if (stops) {
+          for (let i = 0; i < stops.length; i++) {
+            keptSemanticNames.add(`${variableName}/stop-${i}`);
+          }
+        } else {
+          keptSemanticNames.add(variableName);
+        }
+      } else {
+        keptSemanticNames.add(variableName);
+      }
+
+      // Special handling for shadow size tokens: split into x, y, blur variables
+      if (
+        isShadowSizeToken(tokenPath) &&
+        typeof resolvedLight === "string" &&
+        typeof resolvedDark === "string"
+      ) {
+        const lightComponents = parseShadowSizeValue(resolvedLight);
+        const darkComponents = parseShadowSizeValue(resolvedDark);
+
+        if (lightComponents && darkComponents) {
+          // Create three separate variables: x, y, blur
+          const components = [
+            {
+              suffix: "x",
+              lightRef: lightComponents.x,
+              darkRef: darkComponents.x,
+            },
+            {
+              suffix: "y",
+              lightRef: lightComponents.y,
+              darkRef: darkComponents.y,
+            },
+            {
+              suffix: "blur",
+              lightRef: lightComponents.blur,
+              darkRef: darkComponents.blur,
+            },
+          ];
+
+          for (const component of components) {
+            const componentVariableName = `${variableName}/${component.suffix}`;
+            const componentTokenPath = `${tokenPath}/${component.suffix}`;
+
+            // Per-component description: follow the component's own ref to its resolved value
+            // component.lightRef is a dot-path (e.g. "size.0"), wrap in braces for buildReferenceChain
+            const componentChain = buildReferenceChain(
+              `{${component.lightRef}}`,
+              resolvedTokensForRefs,
+            );
+            const baseDesc = token.$description || "";
+            const componentDescription =
+              baseDesc && componentChain
+                ? `${baseDesc}\n${componentChain}`
+                : componentChain || baseDesc;
+
+            // Resolve light reference
+            const lightTargetPath = resolveReferencePath(
+              component.lightRef,
+              resolvedTokensForRefs,
+            );
+            const lightTargetTokenData =
+              resolvedTokensForRefs.get(lightTargetPath);
+            if (!lightTargetTokenData) {
+              const errorMsg = `Could not find light target token ${lightTargetPath} for ${componentTokenPath}`;
+              errors.push(errorMsg);
+              stats.errors++;
+              continue;
+            }
+            const lightTargetVariableName = determineVariableName(
+              lightTargetPath,
+              resolvedTokensForRefs,
+              existingVariables,
+              tempIdMap,
+            );
+            const lightAliasId =
+              tempIdMap.get(lightTargetPath) ||
+              tempIdMap.get(lightTargetVariableName) ||
+              getVariableIdByName(lightTargetVariableName, existingVariables) ||
+              getVariableIdByName(lightTargetPath, existingVariables);
+
+            if (!lightAliasId) {
+              const errorMsg = `Could not resolve light alias for ${componentTokenPath} -> ${lightTargetPath}`;
+              errors.push(errorMsg);
+              stats.errors++;
+              continue;
+            }
+
+            // Resolve dark reference
+            const darkTargetPath = resolveReferencePath(
+              component.darkRef,
+              resolvedTokensForRefs,
+            );
+            const darkTargetTokenData =
+              resolvedTokensForRefs.get(darkTargetPath);
+            if (!darkTargetTokenData) {
+              errors.push(
+                `Could not find dark target token ${darkTargetPath} for ${componentTokenPath}`,
+              );
+              stats.errors++;
+              continue;
+            }
+            const darkTargetVariableName = determineVariableName(
+              darkTargetPath,
+              resolvedTokensForRefs,
+              existingVariables,
+              tempIdMap,
+            );
+            const darkAliasId =
+              tempIdMap.get(darkTargetPath) ||
+              tempIdMap.get(darkTargetVariableName) ||
+              getVariableIdByName(darkTargetVariableName, existingVariables) ||
+              getVariableIdByName(darkTargetPath, existingVariables);
+
+            if (!darkAliasId) {
+              errors.push(
+                `Could not resolve dark alias for ${componentTokenPath} -> ${darkTargetPath}`,
+              );
+              stats.errors++;
+              continue;
+            }
+
+            // Check if variable already exists - optimize with getVariableIdByName
+            const existingId = getVariableIdByName(
+              componentVariableName,
+              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) {
+              // Update existing variable
+              if (!existing.id) {
+                errors.push(
+                  `Existing variable ${componentVariableName} has no ID`,
+                );
+                stats.errors++;
+                continue;
+              }
+
+              const lightFigmaValue = {
+                type: "VARIABLE_ALIAS",
+                id: lightAliasId,
+              };
+              const darkFigmaValue = {
+                type: "VARIABLE_ALIAS",
+                id: darkAliasId,
+              };
+              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 componentScopes = getScopesForVariable(tokenData.token);
+              const sortedUpdate = [...componentScopes].sort();
+              const sortedExisting = [...(existing.scopes ?? [])].sort();
+              const scopesEqual =
+                sortedUpdate.length === sortedExisting.length &&
+                sortedUpdate.every((s, i) => s === sortedExisting[i]);
+
+              const shadowDescriptionSame =
+                (existing.description || "") === componentDescription;
+
+              if (
+                lightSame &&
+                darkSame &&
+                (scopesEqual || componentScopes.length === 0) &&
+                shadowDescriptionSame
+              ) {
+                tempIdMap.set(componentTokenPath, existing.id);
+                tempIdMap.set(componentVariableName, existing.id);
+                stats.skipped++;
+                continue;
+              }
+
+              const updatePayload = {
+                action: "UPDATE",
+                id: existing.id,
+                name: componentVariableName,
+                scopes: componentScopes,
+                description: componentDescription,
+              };
+              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(componentTokenPath, existing.id);
+              tempIdMap.set(componentVariableName, existing.id);
+              stats.updated++;
+            } else {
+              // Create new variable
+              const tempIdCounter = tempIdMap.size + variableChanges.length + 1;
+              const tempId = `temp_var_${tempIdCounter}_${componentVariableName.replace(/\//g, "_").replace(/[^a-zA-Z0-9_]/g, "_")}`;
+              tempIdMap.set(componentTokenPath, tempId);
+              tempIdMap.set(componentVariableName, tempId);
+
+              const componentScopes = getScopesForVariable(tokenData.token);
+              const createPayload = {
+                action: "CREATE",
+                id: tempId,
+                name: componentVariableName,
+                variableCollectionId: collectionId,
+                resolvedType: "FLOAT", // Shadow size components are always FLOAT (dimension values)
+                description: componentDescription,
+              };
+              createPayload.scopes = componentScopes;
+              variableChanges.push(createPayload);
+
+              variableModeValues.push(
+                {
+                  variableId: tempId,
+                  modeId: modes.light.id,
+                  value: { type: "VARIABLE_ALIAS", id: lightAliasId },
+                },
+                {
+                  variableId: tempId,
+                  modeId: modes.dark.id,
+                  value: { type: "VARIABLE_ALIAS", id: darkAliasId },
+                },
+              );
+
+              stats.created++;
+            }
+          }
+
+          // Skip normal processing for shadow size tokens (we've already handled them)
+          continue;
+        }
+      }
+
+      // Special handling for gradient tokens: unpack each stop into a COLOR variable
+      // Figma does not support a gradient variable type; stops are individual COLOR variables.
+      if (isGradientToken(tokenType)) {
+        const gradientValue =
+          typeof token.$value === "object" ? token.$value : null;
+        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 { lightRef, darkRef } = stops[i];
+          const stopVariableName = `${variableName}/stop-${i}`;
+          const stopTokenPath = `${tokenPath}/stop-${i}`;
+          const lightChain =
+            buildReferenceChain(lightRef, resolvedTokensForRefs) || lightRef;
+          const darkChain =
+            buildReferenceChain(darkRef, resolvedTokensForRefs) || darkRef;
+          const stopColorDetail =
+            lightRef === darkRef
+              ? 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}`;
+
+          // Resolve light color reference to a primitive variable alias
+          // lightRef may be a reference string like "{color.blue.600}" — extract path first
+          const lightRefPath = extractReferencePath(lightRef) ?? lightRef;
+          const lightTargetPath = resolveReferencePath(
+            lightRefPath,
+            resolvedTokensForRefs,
+          );
+          const lightTargetVariableName = determineVariableName(
+            lightTargetPath,
+            resolvedTokensForRefs,
+            existingVariables,
+            tempIdMap,
+          );
+          const 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;
+          }
+
+          // Resolve dark color reference to a primitive variable alias
+          // darkRef may be a reference string like "{color.cyan.300}" — extract path first
+          const darkRefPath = extractReferencePath(darkRef) ?? darkRef;
+          const darkTargetPath = resolveReferencePath(
+            darkRefPath,
+            resolvedTokensForRefs,
+          );
+          const darkTargetVariableName = determineVariableName(
+            darkTargetPath,
+            resolvedTokensForRefs,
+            existingVariables,
+            tempIdMap,
+          );
+          const 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
+          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 — gradient token itself has no Figma variable
+        continue;
+      }
+
+      // Check if this should be an alias (only for direct string references, not composite colors)
+      // For composite colors with references, we need to resolve the color value and apply alpha
+      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) {
+        // Resolve the color reference to its actual value
+        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;
+        }
+
+        // Get the resolved color value (use light value for light mode)
+        const resolvedColorValue = targetTokenData.resolvedLight;
+        if (!resolvedColorValue) {
+          errors.push(
+            `Target token ${targetPath} has no resolved light value for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Convert the resolved color to Figma format and apply alpha
+        const baseColor = convertColorValue(resolvedColorValue);
+        if (baseColor === null) {
+          errors.push(
+            `Could not convert resolved color value for ${tokenPath}: ${JSON.stringify(resolvedColorValue)}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Apply the alpha from the composite color
+        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 (e.g., "{size.0} {size.0} {size.0}")
+        // If so, resolve all references to their actual values
+        let valueToConvert = resolvedLight;
+        if (
+          typeof resolvedLight === "string" &&
+          resolvedLight.includes("{") &&
+          resolvedLight.includes("}") &&
+          !isReference(resolvedLight)
+        ) {
+          valueToConvert = resolveMultipleReferences(
+            resolvedLight,
+            resolvedTokensForRefs,
+            false,
+          );
+        }
+
+        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 composite colors with references - resolve the color and apply alpha
+      if (isDarkCompositeWithRef) {
+        // Resolve the color reference to its actual value
+        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;
+        }
+
+        // Get the resolved color value (use dark value for dark mode)
+        const resolvedColorValue = targetTokenData.resolvedDark;
+        if (!resolvedColorValue) {
+          errors.push(
+            `Target token ${targetPath} has no resolved dark value for ${tokenPath}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Convert the resolved color to Figma format and apply alpha
+        const baseColor = convertColorValue(resolvedColorValue);
+        if (baseColor === null) {
+          errors.push(
+            `Could not convert resolved color value for ${tokenPath}: ${JSON.stringify(resolvedColorValue)}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Apply the alpha from the composite color
+        darkFigmaValue = {
+          ...baseColor,
+          a: resolvedDark.alpha ?? resolvedDark.a ?? baseColor.a,
+        };
+      } else if (isDarkReference) {
+        // Direct string reference - create alias
+        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 {
+        // Check if the value is a string with multiple references (e.g., "{size.0} {size.0} {size.0}")
+        // If so, resolve all references to their actual values
+        let valueToConvert = resolvedDark;
+        if (
+          typeof resolvedDark === "string" &&
+          resolvedDark.includes("{") &&
+          resolvedDark.includes("}") &&
+          !isReference(resolvedDark)
+        ) {
+          valueToConvert = resolveMultipleReferences(
+            resolvedDark,
+            resolvedTokensForRefs,
+            true,
+          );
+        }
+
+        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 (check both with and without prefix for backward compatibility)
+      // Optimize: Use getVariableIdByName for better performance
+      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) {
+        // Validate that existing variable has an ID
+        if (!existing.id) {
+          const errorMsg = `Existing variable for ${tokenPath} has no ID`;
+          errors.push(errorMsg);
+          stats.errors++;
+          continue;
+        }
+
+        // Validate mode IDs
+        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);
+
+        // Validate IDs before pushing
+        if (!existing.id || !modes.light.id || !modes.dark.id) {
+          const errorMsg = `Invalid IDs for ${tokenPath}: existing.id=${existing.id}, light.id=${modes.light.id}, dark.id=${modes.dark.id}`;
+          errors.push(errorMsg);
+          stats.errors++;
+          continue;
+        }
+
+        variableModeValues.push(
+          {
+            variableId: existing.id,
+            modeId: modes.light.id,
+            value: lightFigmaValue,
+          },
+          {
+            variableId: existing.id,
+            modeId: modes.dark.id,
+            value: darkFigmaValue,
+          },
+        );
+
+        stats.updated++;
+        tempIdMap.set(tokenPath, existing.id);
+        tempIdMap.set(variableName, existing.id);
+      } else {
+        // Validate mode IDs before creating new variable
+        if (!modes.light?.id || !modes.dark?.id) {
+          errors.push(
+            `Mode IDs are missing: light=${modes.light?.id}, dark=${modes.dark?.id}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        // Create new variable with temporary ID (use a counter to ensure uniqueness)
+        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
+        // If the value is a space-separated string (like "0rem 0rem 0rem"), it must be STRING type
+        // Line-height is sent as % string (e.g. "150%") - must be STRING
+        // Otherwise, use the token type to determine the Figma variable type
+        let variableType = getFigmaVariableType(tokenType);
+        if (
+          variableType === "FLOAT" &&
+          typeof lightFigmaValue === "string" &&
+          lightFigmaValue.includes(" ")
+        ) {
+          // Space-separated strings can't be FLOAT - must be STRING
+          variableType = "STRING";
+        }
+        if (
+          tokenPath.includes("line-height") &&
+          typeof lightFigmaValue === "string"
+        ) {
+          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);
+
+        // Validate IDs before pushing
+        if (!tempId || !modes.light.id || !modes.dark.id) {
+          errors.push(
+            `Invalid IDs for ${tokenPath}: tempId=${tempId}, light.id=${modes.light.id}, dark.id=${modes.dark.id}`,
+          );
+          stats.errors++;
+          continue;
+        }
+
+        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 semantic variables that are no longer in token source
+  for (const v of existingVariables) {
+    if (v.name?.startsWith("semantic/") && !keptSemanticNames.has(v.name)) {
+      variableChanges.push({ action: "DELETE", id: v.id });
+      stats.deleted++;
+    }
+  }
+
+  return {
+    variableChanges,
+    variableModeValues,
+    stats,
+    errors,
+    tempIdMap,
+  };
+}
+
+module.exports = {
+  buildSemanticVariableRequest,
+};