@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/sd-formats.js

@@ -0,0 +1,965 @@
+/**
+ * Style Dictionary format registrations
+ * @module sd-formats
+ */
+const {
+  generateBorderClasses,
+  generateColorClasses,
+  generateFontClasses,
+  generateSpacingClasses,
+} = require("./css-utils-format-utils");
+const {
+  getTokenName,
+  getTokenType,
+  getDtcgValue,
+  getDtcgDescription,
+  hasDarkValue,
+  isCompositeColor,
+  getTokenValue,
+  buildTokenMap,
+  buildFallbackWithRefs,
+  convertToHex8,
+  isGradientValue,
+  buildGradientValue,
+  resolveGradientValue,
+} = require("./token-helpers");
+
+/**
+ * Builds the CSS utils output string with layer declarations and @supports blocks.
+ * Creates a structured CSS output with fallback classes and dark-aware variants.
+ * @param {string} fallback - The fallback CSS classes (light mode only)
+ * @param {string} [darkAwareClasses=''] - The dark-aware CSS classes with light-dark()
+ * @returns {string} The complete CSS output with layer and @supports structure
+ */
+const buildCssUtilsOutput = (
+  fallback,
+  darkAwareClasses = "",
+  indent = "  ",
+) => {
+  const i = indent;
+  const i2 = i + "  ";
+  const supportsBlock = darkAwareClasses
+    ? `\n@supports (color: light-dark(#fff, #000)) {\n  ${darkAwareClasses.replaceAll("\n", "\n  ")}\n}`
+    : "";
+  const supportsBlockNested = darkAwareClasses
+    ? `\n${i}@supports (color: light-dark(#fff, #000)) {\n${i2}${darkAwareClasses.replaceAll("\n", `\n${i2}`)}\n${i}}`
+    : "";
+
+  return `@layer starter, reset, base, state, application;
+
+${fallback}${supportsBlock}
+
+@layer application {
+${i}${fallback.replaceAll("\n", `\n${i}`)}${supportsBlockNested}
+}`;
+};
+
+/**
+ * Registers CSS utility class formats for a given class prefix.
+ * Creates format registrations for: All utils, Borders, Colors, Fonts, and Spacing.
+ * Each format generates CSS utility classes with CSS variable fallbacks and light-dark() support.
+ * @param {import('style-dictionary').default} StyleDictionary - The Style Dictionary class instance
+ * @param {string} prefix - CSS class prefix (e.g., '' or 'a2-')
+ * @param {Function} usesReferences - Function to check if a value uses references
+ * @param {Function} resolveReferences - Function to resolve references
+ * @param {string} [cssVarPrefix=''] - Prefix for CSS variable names (e.g., 'a2-')
+ * @returns {void}
+ */
+const registerCssUtilsFormats = (
+  StyleDictionary,
+  prefix,
+  usesReferences,
+  resolveReferences,
+  cssVarPrefix = "",
+) => {
+  /**
+   * Format: custom/CSSUtils/{prefix}All
+   * Generates all CSS utility classes including colors, borders, typography, and spacing.
+   */
+  StyleDictionary.registerFormat({
+    name: `custom/CSSUtils/${prefix}All`,
+    format: ({ dictionary }) => {
+      const allTokens = dictionary.allTokens || [];
+      // Build token map once for O(1) lookups
+      const tokenMap = buildTokenMap(dictionary);
+
+      // Single pass: compute light fallback value once per token, bucket into output arrays
+      const nonColorBucket = [];
+      const colorFallbackBucket = [];
+      const colorDarkAwareBucket = [];
+
+      for (const token of allTokens) {
+        const name = getTokenName(token);
+        const lightValue = buildFallbackWithRefs(
+          token,
+          dictionary,
+          tokenMap,
+          { isDark: false, cssVarPrefix },
+          usesReferences,
+          resolveReferences,
+        );
+
+        if (name.startsWith("border")) {
+          nonColorBucket.push(
+            ...generateBorderClasses(name, lightValue, {
+              prefix,
+              cssVarPrefix,
+            }),
+          );
+        }
+        if (name.startsWith("typography")) {
+          nonColorBucket.push(
+            ...generateFontClasses(name, lightValue, { prefix }),
+          );
+        } else if (name.startsWith("size")) {
+          nonColorBucket.push(
+            ...generateSpacingClasses(name, lightValue, {
+              prefix,
+              cssVarPrefix,
+            }),
+          );
+        }
+
+        const isColorToken =
+          name.startsWith("status-color") ||
+          name.startsWith("foreground-color") ||
+          name.startsWith("background-color") ||
+          name.startsWith("overlay-color") ||
+          name.startsWith("border-color");
+
+        if (isColorToken) {
+          const classes = name.startsWith("border-color")
+            ? generateBorderClasses(name, lightValue, { prefix, cssVarPrefix })
+            : generateColorClasses(name, lightValue, { prefix, cssVarPrefix });
+          colorFallbackBucket.push(...classes);
+
+          if (hasDarkValue(token)) {
+            const darkAwareValue = buildFallbackWithRefs(
+              token,
+              dictionary,
+              tokenMap,
+              { useLightDark: true, cssVarPrefix },
+              usesReferences,
+              resolveReferences,
+            );
+            const darkClasses = name.startsWith("border-color")
+              ? generateBorderClasses(name, darkAwareValue, {
+                  prefix,
+                  cssVarPrefix,
+                })
+              : generateColorClasses(name, darkAwareValue, {
+                  prefix,
+                  cssVarPrefix,
+                });
+            colorDarkAwareBucket.push(...darkClasses);
+          }
+        }
+      }
+
+      const colorTokens = colorDarkAwareBucket
+        .filter((t) => t != null)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+      const nonColorTokens = nonColorBucket
+        .filter((t) => t != null)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+      const colorFallbackTokens = colorFallbackBucket
+        .filter((t) => t != null)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      const withSr = nonColorTokens.concat(
+        "\n",
+        ".sr-only {border: 0; clip: rect(0, 0, 0, 0); height: 1px; margin: -1px; overflow: hidden; padding-block: 0; padding-inline: 0; position: absolute; white-space: nowrap; width: 1px;}",
+      );
+
+      return buildCssUtilsOutput(
+        `${withSr}\n${colorFallbackTokens}\n`,
+        colorTokens,
+        "    ",
+      );
+    },
+  });
+
+  /**
+   * Format: custom/CSSUtils/{prefix}Borders
+   * Generates CSS utility classes for border tokens (radius, width, color).
+   */
+  StyleDictionary.registerFormat({
+    name: `custom/CSSUtils/${prefix}Borders`,
+    format: ({ dictionary }) => {
+      const allTokens = dictionary.allTokens || [];
+      // Build token map once for O(1) lookups
+      const tokenMap = buildTokenMap(dictionary);
+
+      // Dark-aware classes with light-dark() for @supports block
+      // Uses recursive var chain with light-dark at primitive level
+      const darkAwareClasses = allTokens
+        .filter((token) => {
+          const name = getTokenName(token);
+          return name.includes("color") && name.includes("border");
+        })
+        .filter(hasDarkValue) // Only tokens with dark values
+        .map((token) => {
+          // Use useLightDark to get: light-dark(var(--light-ref, #hex), var(--dark-ref, #hex))
+          const value = buildFallbackWithRefs(
+            token,
+            dictionary,
+            tokenMap,
+            { useLightDark: true, cssVarPrefix },
+            usesReferences,
+            resolveReferences,
+          );
+          const name = getTokenName(token);
+          // Pass value directly - it already contains light-dark()
+          return generateBorderClasses(name, value, { prefix, cssVarPrefix });
+        })
+        .flat()
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      // Fallback classes (light values only, with recursive var chain)
+      const fallback = allTokens
+        .filter((token) => getTokenName(token).startsWith("border"))
+        .map((token) => {
+          const value = buildFallbackWithRefs(
+            token,
+            dictionary,
+            tokenMap,
+            { isDark: false, cssVarPrefix },
+            usesReferences,
+            resolveReferences,
+          );
+          const name = getTokenName(token);
+          return generateBorderClasses(name, value, { prefix, cssVarPrefix });
+        })
+        .flat()
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      return buildCssUtilsOutput(fallback, darkAwareClasses);
+    },
+  });
+
+  /**
+   * Format: custom/CSSUtils/{prefix}Colors
+   * Generates CSS utility classes for color tokens (background, foreground, status, overlay).
+   */
+  StyleDictionary.registerFormat({
+    name: `custom/CSSUtils/${prefix}Colors`,
+    format: ({ dictionary }) => {
+      const allTokens = dictionary.allTokens || [];
+      // Build token map once for O(1) lookups
+      const tokenMap = buildTokenMap(dictionary);
+
+      // Dark-aware classes with recursive var chain and light-dark at primitive level
+      const result = allTokens
+        .filter((token) => getTokenName(token).includes("color"))
+        .filter(hasDarkValue) // Only tokens with dark values for @supports block
+        .map((token) => {
+          // Use useLightDark to get: light-dark(var(--light-ref, #hex), var(--dark-ref, #hex))
+          const value = buildFallbackWithRefs(
+            token,
+            dictionary,
+            tokenMap,
+            { useLightDark: true, cssVarPrefix },
+            usesReferences,
+            resolveReferences,
+          );
+          const name = getTokenName(token);
+          // Pass value directly - it already contains light-dark()
+          return generateColorClasses(name, value, { prefix, cssVarPrefix });
+        })
+        .flat()
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      // Fallback classes (light values only, with recursive var chain)
+      const fallback = allTokens
+        .map((token) => {
+          const value = buildFallbackWithRefs(
+            token,
+            dictionary,
+            tokenMap,
+            { isDark: false, cssVarPrefix },
+            usesReferences,
+            resolveReferences,
+          );
+          const name = getTokenName(token);
+          return generateColorClasses(name, value, { prefix, cssVarPrefix });
+        })
+        .flat()
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      return buildCssUtilsOutput(fallback, result);
+    },
+  });
+
+  /**
+   * Format: custom/CSSUtils/{prefix}Fonts
+   * Generates CSS utility classes for typography tokens (font-family, font-weight, font-size).
+   */
+  StyleDictionary.registerFormat({
+    name: `custom/CSSUtils/${prefix}Fonts`,
+    format: ({ dictionary }) => {
+      const fallback = (dictionary.allTokens || [])
+        .map((token) => {
+          const value = getTokenValue(token, dictionary, {}, resolveReferences);
+          const name = getTokenName(token);
+          return generateFontClasses(name, value, { prefix });
+        })
+        .flat()
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      return buildCssUtilsOutput(fallback);
+    },
+  });
+
+  /**
+   * Format: custom/CSSUtils/{prefix}Spacing
+   * Generates CSS utility classes for spacing/size tokens (margin, padding).
+   */
+  StyleDictionary.registerFormat({
+    name: `custom/CSSUtils/${prefix}Spacing`,
+    format: ({ dictionary }) => {
+      const fallback = (dictionary.allTokens || [])
+        .filter((token) => getTokenName(token).startsWith("size"))
+        .map((token) => {
+          const value = getTokenValue(token, dictionary, {}, resolveReferences);
+          const name = getTokenName(token);
+          return generateSpacingClasses(name, value, { prefix, cssVarPrefix });
+        })
+        .flat()
+        .filter(Boolean)
+        .sort((a, b) => a.localeCompare(b))
+        .join("\n");
+
+      return buildCssUtilsOutput(fallback);
+    },
+  });
+};
+
+/**
+ * Registers all custom Style Dictionary formats including SCSS variables, ES6 exports,
+ * CSS variables, and CSS utility classes.
+ * @param {import('style-dictionary').default} StyleDictionary - The Style Dictionary class instance
+ * @param {Function} usesReferences - Function to check if a value uses references
+ * @param {Function} resolveReferences - Function to resolve references
+ * @param {string} [cssVarPrefix=''] - Prefix for CSS variable names (e.g., 'a2-')
+ * @returns {void}
+ * @example
+ * const StyleDictionary = require('style-dictionary');
+ * registerFormats(StyleDictionary, usesReferences, resolveReferences, 'a2-');
+ */
+const registerFormats = (
+  StyleDictionary,
+  usesReferences,
+  resolveReferences,
+  cssVarPrefix = "",
+) => {
+  /**
+   * Format: custom/scss-variables
+   * Generates SCSS variables with CSS var() fallbacks and light-dark() support.
+   * Output format: $var: var(--var, value);
+   */
+  StyleDictionary.registerFormat({
+    name: "custom/scss-variables",
+    format: ({ dictionary }) => {
+      // Build token lookup map once for O(1) lookups
+      const tokensByName = buildTokenMap(dictionary);
+
+      return dictionary.allTokens
+        .map((token) => {
+          const name = getTokenName(token);
+          const description = getDtcgDescription(token);
+          const comment = description ? `// ${description}\n` : "";
+
+          // Special handling for overlay-color (no CSS variable)
+          if (name.startsWith("overlay-color")) {
+            return `${comment}$${name}: ${getTokenValue(token, dictionary, {}, resolveReferences)};`;
+          }
+
+          // Gradient tokens: build linear-gradient() fallback with CSS var chains
+          if (getTokenType(token) === "gradient") {
+            const gradientValue = resolveGradientValue(token, tokensByName);
+            if (!isGradientValue(gradientValue)) return null;
+            const hasDark = gradientValue.stops.some(
+              (s) =>
+                s.color.$extensions?.appearance?.dark?.$value !== undefined,
+            );
+            const light = buildGradientValue(
+              gradientValue,
+              false,
+              tokensByName,
+              dictionary,
+              cssVarPrefix,
+              usesReferences,
+              resolveReferences,
+            );
+            const fallback = hasDark
+              ? `light-dark(${light}, ${buildGradientValue(gradientValue, true, tokensByName, dictionary, cssVarPrefix, usesReferences, resolveReferences)})`
+              : light;
+            return `${comment}$${name}: var(--${cssVarPrefix}${name}, ${fallback});`;
+          }
+
+          // Build fallback with light-dark() at the level where values differ
+          const fallback = buildFallbackWithRefs(
+            token,
+            dictionary,
+            tokensByName,
+            { useLightDark: true, cssVarPrefix },
+            usesReferences,
+            resolveReferences,
+          );
+          return `${comment}$${name}: var(--${cssVarPrefix}${name}, ${fallback});`;
+        })
+        .filter(Boolean)
+        .join("\n");
+    },
+  });
+
+  /**
+   * Format: custom/scss-variables-map
+   * Generates SCSS variable maps for both primitive and semantic tokens.
+   * Creates separate $light, $dark, and $nonColor maps for tokens with appearance variants.
+   */
+  StyleDictionary.registerFormat({
+    name: "custom/scss-variables-map",
+    format: ({ dictionary, file }) => {
+      const allTokens = dictionary.allTokens || [];
+      const hasAppearanceVariants = allTokens.some(hasDarkValue);
+
+      // Check if this is for component tokens - they need only the final primitive reference
+      const isComponentBuild = file.destination?.includes("component");
+
+      // Build token lookup map once for O(1) lookups
+      const tokensByName = buildTokenMap(dictionary);
+
+      /**
+       * Builds a nested CSS var chain, skipping tokens with $extensions.appearance or from component folder.
+       * @param {Object} token - The token object
+       * @param {boolean} [isDark=false] - Whether to get dark mode value
+       * @param {string} [prefix=cssVarPrefix] - CSS variable prefix
+       * @returns {string} The CSS var chain
+       * @example
+       * // Returns: var(--a2-border-radius-medium, var(--a2-radius-2, 0.375rem))
+       */
+      const getNoLightDarkRef = (
+        token,
+        isDark = false,
+        prefix = cssVarPrefix,
+      ) => {
+        /**
+         * Recursively builds the var chain for a token and its references.
+         * @param {Object} currentToken - The current token being processed
+         * @param {Set<string>} [visited=new Set()] - Set of visited token names to prevent cycles
+         * @param {boolean} [isFirst=true] - Whether this is the first token in the chain
+         * @returns {string} The CSS var chain
+         */
+        const buildChain = (
+          currentToken,
+          visited = new Set(),
+          isFirst = true,
+        ) => {
+          const tokenName = getTokenName(currentToken);
+          if (visited.has(tokenName)) {
+            return getTokenValue(
+              currentToken,
+              dictionary,
+              { isDark, forScssMap: true },
+              resolveReferences,
+            );
+          }
+          visited.add(tokenName);
+
+          // Check if this token should be skipped in the chain
+          const hasAppearance =
+            currentToken.original?.$extensions?.appearance !== undefined ||
+            currentToken.$extensions?.appearance !== undefined;
+          const isComponentToken =
+            currentToken.filePath?.includes("/component/");
+          const shouldSkip = hasAppearance || (isFirst && isComponentToken);
+
+          // Get the value (considering light/dark mode)
+          const valueToFollow = isDark
+            ? (currentToken.original?.$extensions?.appearance?.dark?.$value ??
+              currentToken.original?.$value ??
+              getDtcgValue(currentToken))
+            : (currentToken.original?.$extensions?.appearance?.light?.$value ??
+              currentToken.original?.$value ??
+              getDtcgValue(currentToken));
+
+          // If value is a reference, try to follow it
+          if (
+            typeof valueToFollow === "string" &&
+            valueToFollow.includes("{")
+          ) {
+            const match = valueToFollow.match(/\{([^{}]+)\}/);
+            if (match) {
+              const refPath = match[1];
+              const refToken = tokensByName.get(refPath.replace(/\./g, "-"));
+              if (refToken) {
+                // Recursively build the chain for the referenced token
+                const innerChain = buildChain(refToken, visited, false);
+
+                // Skip this token in the chain if it has appearance or is component
+                if (shouldSkip) {
+                  return innerChain;
+                }
+
+                // Include this token in the chain
+                return `var(--${prefix}${tokenName}, ${innerChain})`;
+              }
+            }
+          }
+
+          // Composite color: resolve inner reference via tokenMap and apply alpha
+          if (isCompositeColor(valueToFollow)) {
+            const refMatch =
+              typeof valueToFollow.color === "string" &&
+              valueToFollow.color.match(/\{([^{}]+)\}/);
+            if (refMatch) {
+              const refTokenName = refMatch[1].replace(/\./g, "-");
+              const refToken = tokensByName.get(refTokenName);
+              if (refToken) {
+                const resolved = getTokenValue(
+                  refToken,
+                  dictionary,
+                  { isDark, forScssMap: true },
+                  resolveReferences,
+                );
+                if (typeof resolved === "string" && resolved.startsWith("#")) {
+                  return convertToHex8(resolved, valueToFollow.alpha);
+                }
+                return resolved;
+              }
+            }
+          }
+
+          // No reference or can't follow - this is the final value
+          if (shouldSkip) {
+            return getTokenValue(
+              currentToken,
+              dictionary,
+              { isDark, forScssMap: true },
+              resolveReferences,
+            );
+          }
+
+          // Include in chain with final value
+          const finalValue = getTokenValue(
+            currentToken,
+            dictionary,
+            { isDark, forScssMap: true },
+            resolveReferences,
+          );
+          return `var(--${prefix}${tokenName}, ${finalValue})`;
+        };
+
+        return buildChain(token);
+      };
+
+      if (hasAppearanceVariants) {
+        /**
+         * Checks if a token is a color type token.
+         * @param {Object} token - The token object
+         * @returns {boolean} True if the token is a color type
+         */
+        const isColorToken = (token) => getTokenType(token) === "color";
+
+        const light = allTokens
+          .filter(isColorToken)
+          .map((token) => {
+            const name = getTokenName(token);
+            // For components, get innermost var; for semantic, get full fallback chain
+            const fallback = isComponentBuild
+              ? getNoLightDarkRef(token, false)
+              : buildFallbackWithRefs(
+                  token,
+                  dictionary,
+                  tokensByName,
+                  {
+                    useLightDark: false,
+                    isDark: false,
+                    cssVarPrefix,
+                    forScssMap: true,
+                  },
+                  usesReferences,
+                  resolveReferences,
+                );
+            return `  ${name}: ${fallback},`;
+          })
+          .join("\n");
+
+        const dark = allTokens
+          .filter(isColorToken)
+          .map((token) => {
+            const name = getTokenName(token);
+            const fallback = isComponentBuild
+              ? getNoLightDarkRef(token, true)
+              : buildFallbackWithRefs(
+                  token,
+                  dictionary,
+                  tokensByName,
+                  {
+                    useLightDark: false,
+                    isDark: true,
+                    cssVarPrefix,
+                    forScssMap: true,
+                  },
+                  usesReferences,
+                  resolveReferences,
+                );
+            return `  ${name}: ${fallback},`;
+          })
+          .join("\n");
+
+        const nonColor = allTokens
+          .filter((token) => !isColorToken(token))
+          .map((token) => {
+            const name = getTokenName(token);
+            if (getTokenType(token) === "gradient") {
+              const gradientValue = resolveGradientValue(token, tokensByName);
+              if (!isGradientValue(gradientValue)) return null;
+              const fallback = buildGradientValue(
+                gradientValue,
+                false,
+                tokensByName,
+                dictionary,
+                cssVarPrefix,
+                usesReferences,
+                resolveReferences,
+              );
+              return `  ${name}: "${fallback}",`;
+            }
+            const fallback = isComponentBuild
+              ? getNoLightDarkRef(token, false)
+              : buildFallbackWithRefs(
+                  token,
+                  dictionary,
+                  tokensByName,
+                  { useLightDark: false, cssVarPrefix, forScssMap: true },
+                  usesReferences,
+                  resolveReferences,
+                );
+            return `  ${name}: ${fallback},`;
+          })
+          .filter(Boolean)
+          .join("\n");
+
+        return `$light: (\n${light}\n);\n$dark: (\n${dark}\n);\n$nonColor: (\n${nonColor}\n);`;
+      } else {
+        const vars = allTokens
+          .map((token) => {
+            const name = getTokenName(token);
+            if (getTokenType(token) === "gradient") {
+              const gradientValue = resolveGradientValue(token, tokensByName);
+              if (!isGradientValue(gradientValue)) return null;
+              const fallback = buildGradientValue(
+                gradientValue,
+                false,
+                tokensByName,
+                dictionary,
+                cssVarPrefix,
+                usesReferences,
+                resolveReferences,
+              );
+              return `  ${name}: "${fallback}",`;
+            }
+            const fallback = isComponentBuild
+              ? getNoLightDarkRef(token, false)
+              : buildFallbackWithRefs(
+                  token,
+                  dictionary,
+                  tokensByName,
+                  { useLightDark: false, cssVarPrefix, forScssMap: true },
+                  usesReferences,
+                  resolveReferences,
+                );
+            return `  ${name}: ${fallback},`;
+          })
+          .filter(Boolean)
+          .join("\n");
+
+        return `$token: (\n${vars}\n);`;
+      }
+    },
+  });
+
+  /**
+   * Extracts terminal hex values for light and dark from a buildFallbackWithRefs result.
+   * Finds the light-dark() call in the chain (may be nested in var() fallbacks) and
+   * extracts the last hex from each arm. Returns { light, dark } where dark is null
+   * if no light-dark() was found (meaning light === dark).
+   * @param {string} chain - Result of buildFallbackWithRefs with useLightDark: true
+   * @returns {{ light: string, dark: string|null }}
+   */
+  const extractLightDarkHex = (chain) => {
+    const ldIdx = chain.indexOf("light-dark(");
+    if (ldIdx === -1) {
+      const hexes = chain.match(/#[0-9a-fA-F]{3,8}/g);
+      return { light: hexes ? hexes[hexes.length - 1] : chain, dark: null };
+    }
+    // Find matching close paren for the light-dark( call
+    let depth = 0;
+    const start = ldIdx + "light-dark(".length;
+    let end = -1;
+    for (let i = ldIdx + "light-dark(".length - 1; i < chain.length; i++) {
+      if (chain[i] === "(") depth++;
+      else if (chain[i] === ")") {
+        depth--;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    if (end === -1) {
+      const hexes = chain.match(/#[0-9a-fA-F]{3,8}/g);
+      return { light: hexes ? hexes[hexes.length - 1] : chain, dark: null };
+    }
+    // Split the two top-level args of light-dark() by finding the comma at depth 0
+    const inner = chain.slice(start, end);
+    let splitIdx = -1;
+    let d = 0;
+    for (let i = 0; i < inner.length; i++) {
+      if (inner[i] === "(") d++;
+      else if (inner[i] === ")") d--;
+      else if (inner[i] === "," && d === 0) {
+        splitIdx = i;
+        break;
+      }
+    }
+    if (splitIdx === -1) {
+      const hexes = chain.match(/#[0-9a-fA-F]{3,8}/g);
+      return { light: hexes ? hexes[hexes.length - 1] : chain, dark: null };
+    }
+    const lightArm = inner.slice(0, splitIdx);
+    const darkArm = inner.slice(splitIdx + 1);
+    const lastHex = (s) => {
+      const m = s.match(/#[0-9a-fA-F]{3,8}/g);
+      return m ? m[m.length - 1] : s.trim();
+    };
+    return { light: lastHex(lightArm), dark: lastHex(darkArm) };
+  };
+
+  /**
+   * Format: custom/es6-variable
+   * Generates ES6 module exports for tokens with TypeScript-compatible JSDoc types.
+   * Tokens with dark variants include an extensions.appearance.dark.value property.
+   * Uses buildFallbackWithRefs to walk the full reference chain so that multi-hop
+   * semantic references correctly resolve to their terminal dark hex values.
+   */
+  StyleDictionary.registerFormat({
+    name: "custom/es6-variable",
+    format: ({ dictionary }) => {
+      const typeDefinitions = `/**
+ * @typedef {Object} TokenValue
+ * @property {string} value
+ */
+
+/**
+ * @typedef {Object} TokenWithAppearance
+ * @property {string} value
+ * @property {Object} extensions
+ * @property {Object} extensions.appearance
+ * @property {Object} extensions.appearance.dark
+ * @property {string} extensions.appearance.dark.value
+ */
+
+`;
+      const tokensByName = buildTokenMap(dictionary);
+
+      return (
+        typeDefinitions +
+        dictionary.allTokens
+          .map((token) => {
+            const name = getTokenName(token);
+            const pascalName = name
+              .split("-")
+              .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+              .join("");
+
+            const description = getDtcgDescription(token);
+            const descriptionTag = description
+              ? ` * @description ${description}\n`
+              : "";
+
+            // Gradient tokens: build linear-gradient() strings directly (no hex extraction)
+            if (getTokenType(token) === "gradient") {
+              const gradientValue = resolveGradientValue(token, tokensByName);
+              if (!isGradientValue(gradientValue)) return null;
+              const hasDark = gradientValue.stops.some(
+                (s) =>
+                  s.color.$extensions?.appearance?.dark?.$value !== undefined,
+              );
+              const lightValue = buildGradientValue(
+                gradientValue,
+                false,
+                tokensByName,
+                dictionary,
+                "",
+                usesReferences,
+                resolveReferences,
+              );
+              if (hasDark) {
+                const darkValue = buildGradientValue(
+                  gradientValue,
+                  true,
+                  tokensByName,
+                  dictionary,
+                  "",
+                  usesReferences,
+                  resolveReferences,
+                );
+                return `/**\n * @type {TokenWithAppearance}\n${descriptionTag} */
+export const ${pascalName} = {
+  value: ${JSON.stringify(lightValue)},
+  extensions: {
+    appearance: {
+      dark: {
+        value: ${JSON.stringify(darkValue)}
+      }
+    }
+  }
+};`;
+              }
+              return `/**\n * @type {TokenValue}\n${descriptionTag} */
+export const ${pascalName} = { value: ${JSON.stringify(lightValue)} };`;
+            }
+
+            const chain = buildFallbackWithRefs(
+              token,
+              dictionary,
+              tokensByName,
+              { useLightDark: true, cssVarPrefix: "" },
+              usesReferences,
+              resolveReferences,
+            );
+            const { light: lightValue, dark: darkValue } = chain.includes(
+              "light-dark(",
+            )
+              ? extractLightDarkHex(chain)
+              : {
+                  light: getTokenValue(
+                    token,
+                    dictionary,
+                    {},
+                    resolveReferences,
+                  ),
+                  dark: null,
+                };
+
+            if (darkValue !== null || hasDarkValue(token)) {
+              const resolvedDark = darkValue !== null ? darkValue : lightValue;
+              return `/**\n * @type {TokenWithAppearance}\n${descriptionTag} */
+export const ${pascalName} = {
+  value: ${JSON.stringify(lightValue)},
+  extensions: {
+    appearance: {
+      dark: {
+        value: ${JSON.stringify(resolvedDark)}
+      }
+    }
+  }
+};`;
+            }
+            return `/**\n * @type {TokenValue}\n${descriptionTag} */
+export const ${pascalName} = { value: ${JSON.stringify(lightValue)} };`;
+          })
+          .filter(Boolean)
+          .join("\n")
+      );
+    },
+  });
+
+  /**
+   * Format: custom/CSSVariables
+   * Generates CSS custom properties in a :root selector with light-dark() support.
+   */
+  StyleDictionary.registerFormat({
+    name: "custom/CSSVariables",
+    format: ({ dictionary }) => {
+      const tokensByName = buildTokenMap(dictionary);
+
+      const cssVars = dictionary.allTokens
+        .map((token) => {
+          const name = getTokenName(token).replace("-default", "");
+          const description = getDtcgDescription(token);
+          const comment = description ? `  /* ${description} */\n` : "";
+
+          if (getTokenType(token) === "gradient") {
+            const gradientValue = resolveGradientValue(token, tokensByName);
+            if (!isGradientValue(gradientValue)) return null;
+            const hasDark = gradientValue.stops.some(
+              (s) =>
+                s.color.$extensions?.appearance?.dark?.$value !== undefined,
+            );
+            const light = buildGradientValue(
+              gradientValue,
+              false,
+              tokensByName,
+              dictionary,
+              cssVarPrefix,
+              usesReferences,
+              resolveReferences,
+            );
+            if (hasDark) {
+              const dark = buildGradientValue(
+                gradientValue,
+                true,
+                tokensByName,
+                dictionary,
+                cssVarPrefix,
+                usesReferences,
+                resolveReferences,
+              );
+              return `${comment}  --${cssVarPrefix}${name}: light-dark(${light}, ${dark});`;
+            }
+            return `${comment}  --${cssVarPrefix}${name}: ${light};`;
+          }
+
+          const light = getTokenValue(token, dictionary, {}, resolveReferences);
+          const dark = hasDarkValue(token)
+            ? getTokenValue(
+                token,
+                dictionary,
+                { isDark: true },
+                resolveReferences,
+              )
+            : null;
+
+          if (dark) {
+            return `${comment}  --${cssVarPrefix}${name}: light-dark(${light}, ${dark});`;
+          }
+          return `${comment}  --${cssVarPrefix}${name}: ${light};`;
+        })
+        .filter(Boolean)
+        .join(`\n`);
+
+      return `:root {\n${cssVars}\n}`;
+    },
+  });
+
+  // Register CSS utils formats for each prefix
+  const CSS_UTILS_PREFIXES = ["", "a2-"];
+  CSS_UTILS_PREFIXES.forEach((prefix) => {
+    registerCssUtilsFormats(
+      StyleDictionary,
+      prefix,
+      usesReferences,
+      resolveReferences,
+      cssVarPrefix,
+    );
+  });
+};
+
+module.exports = {
+  registerFormats,
+};