@servicetitan/hammer-token 2.5.2 → 3.0.1

package/src/utils/token-helpers.js

@@ -0,0 +1,848 @@
+/**
+ * Token helper functions for Style Dictionary DTCG format
+ * These functions handle token value extraction, resolution, and CSS variable chain building
+ */
+
+/**
+ * Extracts the DTCG value from a token
+ * @param {Object} token - The token object
+ * @returns {*} The token's $value property
+ */
+const getDtcgValue = (token) => token.$value;
+
+/**
+ * Extracts the DTCG token type
+ * @param {Object} token - The token object
+ * @returns {string|undefined} The token's $type property
+ */
+const getTokenType = (token) => token.$type;
+
+/**
+ * Extracts the DTCG description from a token
+ * @param {Object} token - The token object
+ * @returns {string|undefined} The token's $description property
+ */
+const getDtcgDescription = (token) => token.$description;
+
+/**
+ * Checks if a token has a dark mode value
+ * @param {Object} token - The token object
+ * @returns {boolean} True if the token has a dark mode value defined
+ */
+const hasDarkValue = (token) =>
+  token.$extensions?.appearance?.dark?.$value !== undefined;
+
+/**
+ * Gets the dark mode value from a token
+ * @param {Object} token - The token object
+ * @returns {*} The dark mode value, or undefined if not present
+ */
+const getDarkValue = (token) => token.$extensions?.appearance?.dark?.$value;
+
+/**
+ * Checks if a value is a composite color object (contains color and alpha properties)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a composite color object
+ * @example
+ * isCompositeColor({ color: '#fff', alpha: 0.5 }) // true
+ * isCompositeColor('#fff') // false
+ */
+const isCompositeColor = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  value.color !== undefined &&
+  value.alpha !== undefined;
+
+/**
+ * Checks if a value is a dimension object (contains value and unit properties)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a dimension object
+ * @example
+ * isDimensionValue({ value: 16, unit: 'px' }) // true
+ * isDimensionValue('16px') // false
+ */
+const isDimensionValue = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  value.value !== undefined &&
+  value.unit !== undefined;
+
+/**
+ * Checks if a value is a DTCG gradient object ({ type, angle, stops })
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a gradient object
+ * @example
+ * isGradientValue({ type: 'linear', angle: 90, stops: [...] }) // true
+ * isGradientValue('#fff') // false
+ */
+const isGradientValue = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  typeof value.type === "string" &&
+  typeof value.angle === "number" &&
+  Array.isArray(value.stops);
+
+/**
+ * Resolves a gradient token's $value to the actual gradient object ({ type, angle, stops }),
+ * following reference strings (e.g. "{gradient.primary}") through the tokenMap if needed.
+ * @param {Object} token - The token object
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @returns {Object|null} The resolved gradient value object, or null if not resolvable
+ */
+const resolveGradientValue = (token, tokenMap) => {
+  const originalValue = token.original?.$value;
+  if (isGradientValue(originalValue)) return originalValue;
+  if (typeof originalValue === "string" && originalValue.includes("{")) {
+    const refPath = originalValue.match(/\{([^{}]+)\}/)?.[1];
+    if (refPath) {
+      const refToken = tokenMap.get(refPath.replace(/\./g, "-"));
+      if (refToken) return resolveGradientValue(refToken, tokenMap);
+    }
+  }
+  return null;
+};
+
+/**
+ * Builds a CSS gradient string from a DTCG gradient value object, preserving CSS custom
+ * property references for each color stop. Uses the per-stop appearance extension to
+ * resolve light/dark color values.
+ * @param {Object} gradientValue - The gradient value object ({ type, angle, stops })
+ * @param {boolean} isDark - Whether to use dark mode stop colors
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {string} cssVarPrefix - Prefix for CSS variable names (e.g., 'a2-')
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string} CSS gradient string with var() chains for stop colors
+ * @example
+ * buildGradientValue({ type: 'linear', angle: 90, stops }, false, tokenMap, dictionary, 'a2-', usesReferences, resolveReferences)
+ * // → 'linear-gradient(90deg, var(--a2-color-blue-600, #0265dc) 0%, var(--a2-color-cyan-300, #45d8f2) 100%)'
+ */
+const buildGradientValue = (
+  gradientValue,
+  isDark,
+  tokenMap,
+  dictionary,
+  cssVarPrefix,
+  usesReferences,
+  resolveReferences,
+) => {
+  const { type, angle, stops } = gradientValue;
+  const stopStrings = stops.map((stop) => {
+    const pct =
+      typeof stop.position === "number"
+        ? `${stop.position * 100}%`
+        : stop.position.replace(/\{([^{}]+)\}/g, (match) =>
+            buildRecursiveVarChainWithLightDark(
+              match,
+              tokenMap,
+              dictionary,
+              false,
+              usesReferences,
+              resolveReferences,
+              cssVarPrefix,
+            ),
+          );
+    const colorRef = isDark
+      ? (stop.color.$extensions?.appearance?.dark?.$value ?? stop.color.$value)
+      : (stop.color.$extensions?.appearance?.light?.$value ??
+        stop.color.$value);
+    if (typeof colorRef === "string" && usesReferences(colorRef)) {
+      const varChain = buildRecursiveVarChainWithLightDark(
+        colorRef,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+      );
+      return `${varChain} ${pct}`;
+    }
+    return `${colorRef} ${pct}`;
+  });
+  return `${type}-gradient(${angle}deg, ${stopStrings.join(", ")})`;
+};
+
+/**
+ * Wraps values containing commas in double quotes for SCSS map compatibility.
+ * SCSS maps use commas as entry separators, so values with commas need quoting.
+ * @param {*} value - The value to potentially wrap
+ * @returns {*} The wrapped value if it contains commas, otherwise the original value
+ * @example
+ * wrapScssValue('Arial, sans-serif') // '"Arial, sans-serif"'
+ * wrapScssValue('Arial') // 'Arial'
+ */
+const wrapScssValue = (value) => {
+  if (typeof value !== "string") return value;
+  if (value.includes(",")) {
+    return `"${value}"`;
+  }
+  return value;
+};
+
+/**
+ * Gets the token name from its path, filtering out $schema and other $-prefixed segments
+ * @param {Object} token - The token object
+ * @returns {string} The token name as a hyphen-separated string
+ * @example
+ * getTokenName({ path: ['color', 'primary', '500'] }) // 'color-primary-500'
+ */
+const getTokenName = (token) => {
+  const tokenPath = token.path;
+  if (Array.isArray(tokenPath) && tokenPath.length > 0) {
+    const filteredPath = tokenPath.filter(
+      (segment) => segment !== "$schema" && !String(segment).startsWith("$"),
+    );
+    if (filteredPath.length > 0) {
+      return filteredPath.join("-");
+    }
+  }
+  return "unknown";
+};
+
+/**
+ * Builds a Map of tokens keyed by their names for O(1) lookups.
+ * Result is memoized per dictionary instance to avoid redundant construction
+ * across multiple format calls that share the same dictionary.
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @returns {Map<string, Object>} A Map where keys are token names and values are token objects
+ */
+const _tokenMapCache = new WeakMap();
+const buildTokenMap = (dictionary) => {
+  if (_tokenMapCache.has(dictionary)) return _tokenMapCache.get(dictionary);
+  const map = new Map(
+    (dictionary.unfilteredAllTokens || dictionary.allTokens).map((t) => [
+      getTokenName(t),
+      t,
+    ]),
+  );
+  _tokenMapCache.set(dictionary, map);
+  return map;
+};
+
+/**
+ * Converts a hex color to hex8 format (with alpha channel)
+ * @param {string} hexColor - The hex color to convert (e.g., '#ff0000' or '#f00')
+ * @param {number} alpha - The alpha value between 0 and 1
+ * @returns {string} The hex8 color string (e.g., '#ff000080')
+ * @example
+ * convertToHex8('#ff0000', 0.5) // '#ff000080'
+ * convertToHex8('#f00', 1) // '#ff0000FF'
+ */
+const convertToHex8 = (hexColor, alpha) => {
+  if (!hexColor || typeof hexColor !== "string" || !hexColor.startsWith("#")) {
+    return hexColor;
+  }
+
+  // Remove # and normalize to 6-digit hex
+  let hex = hexColor.replace("#", "");
+  if (hex.length === 3) {
+    // Expand shorthand: #RGB -> #RRGGBB
+    hex = hex
+      .split("")
+      .map((char) => char + char)
+      .join("");
+  } else if (hex.length !== 6) {
+    return hexColor; // Invalid hex format
+  }
+
+  // Convert alpha (0-1) to hex (00-FF)
+  const alphaHex = Math.round(alpha * 255)
+    .toString(16)
+    .padStart(2, "0")
+    .toUpperCase();
+
+  return `#${hex}${alphaHex}`;
+};
+
+/**
+ * Converts a composite color { color, alpha } to a CSS color-mix() expression,
+ * preserving the primitive CSS custom property reference.
+ *
+ * Example output:
+ *   color-mix(in srgb, var(--a2-color-neutral-0, #ffffff) 8%, transparent)
+ *
+ * This keeps the live link to the primitive token so runtime theme overrides
+ * (e.g. changing --a2-color-neutral-0) automatically update the alpha color too.
+ *
+ * Browser support: Chrome 111+, Firefox 113+, Safari 16.2+ (as of 2024).
+ *
+ * ---
+ * FUTURE: CSS Relative Color Syntax (Option 3)
+ * When browser support matures (Chrome 119+, Safari 17.5+, Firefox 128+),
+ * this can be simplified to:
+ *   rgb(from var(--a2-color-neutral-0, #ffffff) r g b / 0.08)
+ * Change the return statement below to that template and remove the alpha→percentage
+ * conversion. The `from` keyword extracts r/g/b channels from the referenced color,
+ * so no color-space conversion is needed. Switch when your minimum browser targets
+ * include the versions listed above.
+ * ---
+ *
+ * @param {string} refTokenName - The token name (hyphen-separated, e.g. 'color-neutral-0')
+ * @param {string} hexFallback - The resolved hex color as a fallback (e.g. '#ffffff')
+ * @param {number} alpha - The alpha value between 0 and 1
+ * @param {string} [cssVarPrefix=''] - Prefix for CSS variable names (e.g. 'a2-')
+ * @returns {string} CSS color-mix() expression
+ * @example
+ * compositeColorToCssMix('color-neutral-0', '#ffffff', 0.08, 'a2-')
+ * // → 'color-mix(in srgb, var(--a2-color-neutral-0, #ffffff) 8%, transparent)'
+ */
+const compositeColorToCssMix = (
+  refTokenName,
+  hexFallback,
+  alpha,
+  cssVarPrefix = "",
+) => {
+  const pct = Math.round(alpha * 10000) / 100; // avoid floating point drift, e.g. 0.06 → 6
+  return `color-mix(in srgb, var(--${cssVarPrefix}${refTokenName}, ${hexFallback}) ${pct}%, transparent)`;
+};
+
+/**
+ * Resolves a reference string using Style Dictionary utilities.
+ * @param {string} refString - The reference string to resolve (e.g., '{color.primary.500}')
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {*} The resolved value, or the original string if resolution fails
+ */
+const resolveReference = (refString, dictionary, resolveReferences) => {
+  if (typeof refString !== "string") {
+    return refString;
+  }
+  // Use unfiltered tokens when available so references to theme/primitive tokens
+  // resolve correctly in filtered builds (e.g. component.js only has component tokens).
+  const tokensForResolution = dictionary.unfilteredTokens ?? dictionary.tokens;
+  try {
+    return resolveReferences(refString, tokensForResolution, {
+      usesDtcg: true,
+    });
+  } catch {
+    return refString;
+  }
+};
+
+/**
+ * Resolves a composite color object (with color and alpha properties) to a CSS value.
+ *
+ * When a tokenMap and cssVarPrefix are provided and the color references a known primitive
+ * token, emits a color-mix() expression that preserves the CSS custom property reference:
+ *   color-mix(in srgb, var(--a2-color-neutral-0, #ffffff) 8%, transparent)
+ *
+ * Falls back to a hex8 string (#rrggbbAA) when the primitive token is not in tokenMap
+ * or when tokenMap is not provided (e.g. in SCSS map / JS export contexts where a
+ * static value is needed).
+ *
+ * @param {Object} colorObj - The composite color object with color and alpha properties
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @param {Map<string, Object>} [tokenMap] - Optional token map for CSS var name lookup
+ * @param {string} [cssVarPrefix=''] - Optional prefix for CSS variable names (e.g. 'a2-')
+ * @returns {string|null} CSS color value string, or null if not a composite color
+ */
+const resolveCompositeColor = (
+  colorObj,
+  dictionary,
+  resolveReferences,
+  tokenMap,
+  cssVarPrefix = "",
+) => {
+  if (!isCompositeColor(colorObj)) {
+    return null;
+  }
+  const colorValue = resolveReference(
+    colorObj.color,
+    dictionary,
+    resolveReferences,
+  );
+  if (typeof colorValue === "string" && colorValue.startsWith("#")) {
+    // When a tokenMap is available, emit color-mix() to preserve the primitive var reference.
+    if (tokenMap && typeof colorObj.color === "string") {
+      const refMatch = colorObj.color.match(/\{([^{}]+)\}/);
+      if (refMatch) {
+        const refTokenName = refMatch[1].replace(/\./g, "-");
+        if (tokenMap.has(refTokenName)) {
+          return compositeColorToCssMix(
+            refTokenName,
+            colorValue,
+            colorObj.alpha,
+            cssVarPrefix,
+          );
+        }
+      }
+    }
+    return convertToHex8(colorValue, colorObj.alpha);
+  }
+  return colorValue;
+};
+
+/**
+ * Gets the resolved token value, handling dark mode, composite colors, and references
+ * @param {Object} token - The token object
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Object} [options] - Options for value resolution
+ * @param {boolean} [options.isDark=false] - Whether to get the dark mode value
+ * @param {boolean} [options.forScssMap=false] - Whether to format for SCSS map (quotes commas)
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string} The resolved token value as a string
+ */
+const getTokenValue = (
+  token,
+  dictionary,
+  { isDark = false, forScssMap = false } = {},
+  resolveReferences,
+) => {
+  let value = getDtcgValue(token);
+
+  // Handle dark mode
+  if (isDark && hasDarkValue(token)) {
+    value = getDarkValue(token);
+  }
+
+  // Handle composite colors
+  if (isCompositeColor(value)) {
+    const resolved = resolveCompositeColor(
+      value,
+      dictionary,
+      resolveReferences,
+    );
+    if (resolved) {
+      value = resolved;
+    }
+  }
+
+  // Handle dimension values { value, unit }
+  if (isDimensionValue(value)) {
+    value = `${value.value}${value.unit}`;
+  }
+
+  // Resolve references; SD5 resolveReferences may return a token object, so extract value and loop until primitive
+  for (;;) {
+    if (
+      typeof value === "string" &&
+      value.includes("{") &&
+      value.includes("}")
+    ) {
+      value = resolveReference(value, dictionary, resolveReferences);
+    }
+    // SD5 can return the full token object; extract value
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      if (value.$value !== undefined || value.value !== undefined) {
+        value =
+          isDark && value.$extensions?.appearance?.dark?.$value !== undefined
+            ? value.$extensions.appearance.dark.$value
+            : (value.$value ?? value.value);
+        continue;
+      }
+    }
+    if (isCompositeColor(value)) {
+      const resolved = resolveCompositeColor(
+        value,
+        dictionary,
+        resolveReferences,
+      );
+      if (resolved) {
+        value = resolved;
+      }
+    }
+    if (isDimensionValue(value)) {
+      value = `${value.value}${value.unit}`;
+    }
+    break;
+  }
+
+  // Convert to string and clean up
+  if (value === undefined || value === null) {
+    return "";
+  }
+  const valueStr = typeof value === "string" ? value : JSON.stringify(value);
+
+  // Normalize transparent to rgba for consistency
+  const cleaned = valueStr.replaceAll('"', "");
+  if (cleaned === "transparent") {
+    return "rgba(0, 0, 0, 0)";
+  }
+
+  // Wrap values with commas in quotes for SCSS map compatibility
+  if (forScssMap) {
+    return wrapScssValue(cleaned);
+  }
+  return cleaned;
+};
+
+/**
+ * Checks if a value is a reference string using the usesReferences function
+ * @param {*} value - The value to check
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @returns {boolean} True if the value is a reference string
+ */
+const isReferenceString = (value, usesReferences) =>
+  typeof value === "string" && usesReferences(value);
+
+/**
+ * Builds a recursive CSS var chain with light-dark() at the level where light/dark values differ.
+ * Creates nested var() fallbacks that ultimately resolve to light-dark() at the primitive level.
+ * @param {string} originalValue - The original reference string (e.g., '{status.color.danger}')
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {boolean} [useLightDark=false] - Whether to include light-dark() for color variants
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @param {string} [cssVarPrefix=''] - Prefix for CSS variable names (e.g., 'a2-')
+ * @param {boolean} [forScssMap=false] - Whether to format for SCSS map
+ * @returns {string} The CSS var chain string
+ * @example
+ * // Returns: 'var(--a2-status-color-danger, light-dark(var(--a2-color-red-500, #e13212), var(--a2-color-red-100, #ff745f)))'
+ * buildRecursiveVarChainWithLightDark('{status.color.danger}', tokenMap, dictionary, true, usesReferences, resolveReferences, 'a2-')
+ */
+const buildRecursiveVarChainWithLightDark = (
+  originalValue,
+  tokenMap,
+  dictionary,
+  useLightDark = false,
+  usesReferences,
+  resolveReferences,
+  cssVarPrefix = "",
+  forScssMap = false,
+) => {
+  // If not a reference string, return the value as-is
+  if (
+    !originalValue ||
+    typeof originalValue !== "string" ||
+    !usesReferences(originalValue)
+  ) {
+    return originalValue;
+  }
+
+  // Replace each {reference} with var(--name, recursiveResult)
+  return originalValue.replace(/\{([^{}]+)\}/g, (_, refPath) => {
+    const refTokenName = refPath.replace(/\./g, "-");
+    const refToken = tokenMap.get(refTokenName);
+    if (!refToken) return `var(--${cssVarPrefix}${refTokenName})`;
+
+    const refOriginalLight = refToken.original?.$value;
+    const refOriginalDark =
+      refToken.original?.$extensions?.appearance?.dark?.$value;
+    const refHasDarkVariant = refOriginalDark !== undefined;
+
+    // Check if light and dark values are DIFFERENT - this is where light-dark() should go
+    const lightDarkDiffer =
+      refHasDarkVariant && refOriginalLight !== refOriginalDark;
+
+    if (useLightDark && lightDarkDiffer) {
+      // Light and dark values differ - insert light-dark() here
+      const lightResult = buildRecursiveVarChainWithLightDark(
+        refOriginalLight,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      // Same fix as darkFinal: ensure lightResult is a string before using it
+      const lightFinal =
+        typeof lightResult === "string" && usesReferences(refOriginalLight)
+          ? lightResult
+          : getTokenValue(
+              refToken,
+              dictionary,
+              { isDark: false, forScssMap },
+              resolveReferences,
+            );
+
+      const darkResult = buildRecursiveVarChainWithLightDark(
+        refOriginalDark,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      // Ensure darkResult is a string (resolved var chain), not just truthy.
+      // Composite color objects pass through buildRecursiveVarChainWithLightDark unchanged,
+      // but usesReferences() returns true for them (checks nested properties).
+      const darkFinal =
+        typeof darkResult === "string" && usesReferences(refOriginalDark)
+          ? darkResult
+          : getTokenValue(
+              refToken,
+              dictionary,
+              { isDark: true, forScssMap },
+              resolveReferences,
+            );
+
+      return `var(--${cssVarPrefix}${refTokenName}, light-dark(${lightFinal}, ${darkFinal}))`;
+    }
+
+    // Light and dark are same (or no dark) - continue recursing, propagate useLightDark
+    if (
+      refOriginalLight &&
+      typeof refOriginalLight === "string" &&
+      usesReferences(refOriginalLight)
+    ) {
+      const nestedResult = buildRecursiveVarChainWithLightDark(
+        refOriginalLight,
+        tokenMap,
+        dictionary,
+        useLightDark,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+      return `var(--${cssVarPrefix}${refTokenName}, ${nestedResult})`;
+    }
+
+    // Final value (primitive) - get resolved value
+    const finalValue = getTokenValue(
+      refToken,
+      dictionary,
+      { isDark: false, forScssMap },
+      resolveReferences,
+    );
+    return `var(--${cssVarPrefix}${refTokenName}, ${finalValue})`;
+  });
+};
+
+/**
+ * Builds a fallback value with recursive refs and light-dark() at the appropriate level.
+ * This is the main entry point for generating CSS fallback values with dark mode support.
+ * @param {Object} token - The token object
+ * @param {Object} dictionary - The Style Dictionary dictionary object
+ * @param {Map<string, Object>} tokenMap - Map of token names to token objects
+ * @param {Object} [options] - Options for fallback building
+ * @param {boolean} [options.isDark=false] - Whether to get the dark mode value
+ * @param {boolean} [options.useLightDark=false] - Whether to include light-dark() for color variants
+ * @param {string} [options.cssVarPrefix=''] - Prefix for CSS variable names
+ * @param {boolean} [options.forScssMap=false] - Whether to format for SCSS map
+ * @param {Function} usesReferences - The SD5 usesReferences function
+ * @param {Function} resolveReferences - The SD5 resolveReferences function
+ * @returns {string} The fallback value string with CSS var chains and/or light-dark()
+ */
+const buildFallbackWithRefs = (
+  token,
+  dictionary,
+  tokenMap,
+  {
+    isDark = false,
+    useLightDark = false,
+    cssVarPrefix = "",
+    forScssMap = false,
+  } = {},
+  usesReferences,
+  resolveReferences,
+) => {
+  const originalValue = token.original?.$value;
+  const originalDark = token.original?.$extensions?.appearance?.dark?.$value;
+  const hasDark = originalDark !== undefined;
+
+  // Check if this token's light/dark values are different at top level
+  // Use JSON.stringify for object comparison (composite colors)
+  const lightDarkDifferAtTop =
+    hasDark && JSON.stringify(originalValue) !== JSON.stringify(originalDark);
+
+  // If useLightDark and light/dark differ at this level, insert light-dark() here
+  if (useLightDark && lightDarkDifferAtTop) {
+    // Handle light value - could be a string reference or composite object
+    let lightFinal;
+    if (isReferenceString(originalValue, usesReferences)) {
+      lightFinal = buildRecursiveVarChainWithLightDark(
+        originalValue,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+    } else {
+      // Composite color or plain value - resolve directly.
+      // Pass tokenMap + cssVarPrefix so composite colors emit color-mix() in CSS contexts.
+      if (isCompositeColor(originalValue)) {
+        lightFinal =
+          resolveCompositeColor(
+            originalValue,
+            dictionary,
+            resolveReferences,
+            tokenMap,
+            cssVarPrefix,
+          ) ??
+          getTokenValue(
+            token,
+            dictionary,
+            { isDark: false, forScssMap },
+            resolveReferences,
+          );
+      } else {
+        lightFinal = getTokenValue(
+          token,
+          dictionary,
+          { isDark: false, forScssMap },
+          resolveReferences,
+        );
+      }
+    }
+
+    // Handle dark value - could be a string reference or composite object
+    let darkFinal;
+    if (isReferenceString(originalDark, usesReferences)) {
+      darkFinal = buildRecursiveVarChainWithLightDark(
+        originalDark,
+        tokenMap,
+        dictionary,
+        false,
+        usesReferences,
+        resolveReferences,
+        cssVarPrefix,
+        forScssMap,
+      );
+    } else {
+      // Composite color or plain value - resolve directly.
+      // Pass tokenMap + cssVarPrefix so composite colors emit color-mix() in CSS contexts.
+      if (isCompositeColor(originalDark)) {
+        darkFinal =
+          resolveCompositeColor(
+            originalDark,
+            dictionary,
+            resolveReferences,
+            tokenMap,
+            cssVarPrefix,
+          ) ??
+          getTokenValue(
+            token,
+            dictionary,
+            { isDark: true, forScssMap },
+            resolveReferences,
+          );
+      } else {
+        darkFinal = getTokenValue(
+          token,
+          dictionary,
+          { isDark: true, forScssMap },
+          resolveReferences,
+        );
+      }
+    }
+
+    return `light-dark(${lightFinal}, ${darkFinal})`;
+  }
+
+  // Light/dark same or no dark - recurse and propagate useLightDark to find where they differ
+  // When isDark is true and we have a dark value, use originalDark instead of originalValue
+  const valueToProcess = isDark && hasDark ? originalDark : originalValue;
+
+  if (isReferenceString(valueToProcess, usesReferences)) {
+    const result = buildRecursiveVarChainWithLightDark(
+      valueToProcess,
+      tokenMap,
+      dictionary,
+      useLightDark,
+      usesReferences,
+      resolveReferences,
+      cssVarPrefix,
+      forScssMap,
+    );
+    if (result && result !== valueToProcess) {
+      return result;
+    }
+  }
+
+  // Composite color with inner reference and same light/dark value: resolve referenced token
+  // to get a light-dark() pair. Uses color-mix() to preserve the primitive CSS var reference.
+  if (
+    useLightDark &&
+    isCompositeColor(originalValue) &&
+    isReferenceString(originalValue.color, usesReferences)
+  ) {
+    const refMatch = originalValue.color.match(/\{([^{}]+)\}/);
+    if (refMatch) {
+      const refTokenName = refMatch[1].replace(/\./g, "-");
+      const refToken = tokenMap.get(refTokenName);
+      if (refToken && hasDarkValue(refToken)) {
+        const lightResolved = getTokenValue(
+          refToken,
+          dictionary,
+          { isDark: false, forScssMap },
+          resolveReferences,
+        );
+        const darkResolved = getTokenValue(
+          refToken,
+          dictionary,
+          { isDark: true, forScssMap },
+          resolveReferences,
+        );
+        if (
+          typeof lightResolved === "string" &&
+          typeof darkResolved === "string" &&
+          lightResolved.startsWith("#")
+        ) {
+          const lightMix = compositeColorToCssMix(
+            refTokenName,
+            lightResolved,
+            originalValue.alpha,
+            cssVarPrefix,
+          );
+          const darkMix = compositeColorToCssMix(
+            refTokenName,
+            darkResolved,
+            originalValue.alpha,
+            cssVarPrefix,
+          );
+          return `light-dark(${lightMix}, ${darkMix})`;
+        }
+        return `light-dark(${lightResolved}, ${darkResolved})`;
+      }
+    }
+  }
+
+  // No references or composite value - return the resolved final value.
+  // For composite colors, pass tokenMap + cssVarPrefix to emit color-mix() in CSS contexts.
+  const valueToCheck = isDark && hasDark ? originalDark : originalValue;
+  if (isCompositeColor(valueToCheck)) {
+    const mixed = resolveCompositeColor(
+      valueToCheck,
+      dictionary,
+      resolveReferences,
+      tokenMap,
+      cssVarPrefix,
+    );
+    if (mixed) return mixed;
+  }
+  return getTokenValue(
+    token,
+    dictionary,
+    { isDark, forScssMap },
+    resolveReferences,
+  );
+};
+
+module.exports = {
+  getDtcgValue,
+  getTokenType,
+  getDtcgDescription,
+  hasDarkValue,
+  getDarkValue,
+  isCompositeColor,
+  isDimensionValue,
+  isGradientValue,
+  wrapScssValue,
+  getTokenName,
+  buildTokenMap,
+  convertToHex8,
+  compositeColorToCssMix,
+  resolveReference,
+  resolveCompositeColor,
+  getTokenValue,
+  isReferenceString,
+  buildRecursiveVarChainWithLightDark,
+  buildFallbackWithRefs,
+  buildGradientValue,
+  resolveGradientValue,
+};