@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/__tests__/token-helpers.test.js

@@ -0,0 +1,1160 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  getDtcgValue,
+  getTokenType,
+  getDtcgDescription,
+  hasDarkValue,
+  getDarkValue,
+  isCompositeColor,
+  isDimensionValue,
+  wrapScssValue,
+  getTokenName,
+  buildTokenMap,
+  convertToHex8,
+  compositeColorToCssMix,
+  resolveReference,
+  resolveCompositeColor,
+  getTokenValue,
+  isReferenceString,
+  buildRecursiveVarChainWithLightDark,
+  buildFallbackWithRefs,
+  isGradientValue,
+  resolveGradientValue,
+  buildGradientValue,
+} from "../token-helpers.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const mockDictionary = (tokens = []) => ({
+  allTokens: tokens,
+  unfilteredAllTokens: tokens,
+  tokens: {},
+  unfilteredTokens: {},
+});
+
+const mockUsesReferences = (value) =>
+  typeof value === "string" && value.includes("{");
+
+const mockResolveReferences = (refString) => {
+  // Minimal stub: returns the refString unchanged (caller handles fallback)
+  return refString;
+};
+
+// ---------------------------------------------------------------------------
+// getDtcgValue
+// ---------------------------------------------------------------------------
+
+describe("getDtcgValue", () => {
+  it("returns the $value property", () => {
+    expect(getDtcgValue({ $value: "#abc" })).toBe("#abc");
+  });
+
+  it("returns undefined when $value is absent", () => {
+    expect(getDtcgValue({})).toBeUndefined();
+  });
+
+  it("handles object values", () => {
+    const val = { color: "#fff", alpha: 0.5 };
+    expect(getDtcgValue({ $value: val })).toBe(val);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTokenType
+// ---------------------------------------------------------------------------
+
+describe("getTokenType", () => {
+  it("returns the $type property", () => {
+    expect(getTokenType({ $type: "color" })).toBe("color");
+  });
+
+  it("returns undefined when $type is absent", () => {
+    expect(getTokenType({})).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getDtcgDescription
+// ---------------------------------------------------------------------------
+
+describe("getDtcgDescription", () => {
+  it("returns the $description property", () => {
+    expect(getDtcgDescription({ $description: "A primary color" })).toBe(
+      "A primary color",
+    );
+  });
+
+  it("returns undefined when $description is absent", () => {
+    expect(getDtcgDescription({})).toBeUndefined();
+  });
+
+  it("returns empty string when $description is empty string", () => {
+    expect(getDtcgDescription({ $description: "" })).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hasDarkValue
+// ---------------------------------------------------------------------------
+
+describe("hasDarkValue", () => {
+  it("returns true when dark $value is present", () => {
+    const token = {
+      $extensions: { appearance: { dark: { $value: "#000" } } },
+    };
+    expect(hasDarkValue(token)).toBe(true);
+  });
+
+  it("returns false when dark $value is absent", () => {
+    expect(hasDarkValue({})).toBe(false);
+    expect(hasDarkValue({ $extensions: {} })).toBe(false);
+    expect(hasDarkValue({ $extensions: { appearance: {} } })).toBe(false);
+    expect(hasDarkValue({ $extensions: { appearance: { dark: {} } } })).toBe(
+      false,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getDarkValue
+// ---------------------------------------------------------------------------
+
+describe("getDarkValue", () => {
+  it("returns the dark $value", () => {
+    const token = {
+      $extensions: { appearance: { dark: { $value: "#111" } } },
+    };
+    expect(getDarkValue(token)).toBe("#111");
+  });
+
+  it("returns undefined when not present", () => {
+    expect(getDarkValue({})).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isCompositeColor
+// ---------------------------------------------------------------------------
+
+describe("isCompositeColor", () => {
+  it("returns true for { color, alpha } objects", () => {
+    expect(isCompositeColor({ color: "#fff", alpha: 0.5 })).toBe(true);
+  });
+
+  it("returns false for strings", () => {
+    expect(isCompositeColor("#fff")).toBe(false);
+  });
+
+  it("returns false for arrays", () => {
+    expect(isCompositeColor([{ color: "#fff", alpha: 0 }])).toBe(false);
+  });
+
+  it("returns falsy for null/undefined", () => {
+    expect(isCompositeColor(null)).toBeFalsy();
+    expect(isCompositeColor(undefined)).toBeFalsy();
+  });
+
+  it("returns false when color property is missing", () => {
+    expect(isCompositeColor({ alpha: 0.5 })).toBe(false);
+  });
+
+  it("returns false when alpha property is missing", () => {
+    expect(isCompositeColor({ color: "#fff" })).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isDimensionValue
+// ---------------------------------------------------------------------------
+
+describe("isDimensionValue", () => {
+  it("returns true for { value, unit } objects", () => {
+    expect(isDimensionValue({ value: 16, unit: "px" })).toBe(true);
+  });
+
+  it("returns false for strings", () => {
+    expect(isDimensionValue("16px")).toBe(false);
+  });
+
+  it("returns false for arrays", () => {
+    expect(isDimensionValue([16, "px"])).toBe(false);
+  });
+
+  it("returns falsy for null/undefined", () => {
+    expect(isDimensionValue(null)).toBeFalsy();
+    expect(isDimensionValue(undefined)).toBeFalsy();
+  });
+
+  it("returns false when value property is missing", () => {
+    expect(isDimensionValue({ unit: "px" })).toBe(false);
+  });
+
+  it("returns false when unit property is missing", () => {
+    expect(isDimensionValue({ value: 16 })).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// wrapScssValue
+// ---------------------------------------------------------------------------
+
+describe("wrapScssValue", () => {
+  it("wraps strings containing commas in double quotes", () => {
+    expect(wrapScssValue("Arial, sans-serif")).toBe('"Arial, sans-serif"');
+  });
+
+  it("returns strings without commas unchanged", () => {
+    expect(wrapScssValue("Arial")).toBe("Arial");
+  });
+
+  it("returns non-string values unchanged", () => {
+    expect(wrapScssValue(42)).toBe(42);
+    expect(wrapScssValue(null)).toBe(null);
+    expect(wrapScssValue(undefined)).toBe(undefined);
+  });
+
+  it("wraps even when comma is at the start or end", () => {
+    expect(wrapScssValue(",value")).toBe('",value"');
+    expect(wrapScssValue("value,")).toBe('"value,"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTokenName
+// ---------------------------------------------------------------------------
+
+describe("getTokenName", () => {
+  it("joins path segments with hyphens", () => {
+    expect(getTokenName({ path: ["color", "primary", "500"] })).toBe(
+      "color-primary-500",
+    );
+  });
+
+  it("filters out $schema segment", () => {
+    expect(getTokenName({ path: ["$schema", "color", "neutral"] })).toBe(
+      "color-neutral",
+    );
+  });
+
+  it("filters out any $-prefixed segments", () => {
+    expect(getTokenName({ path: ["$meta", "size", "4"] })).toBe("size-4");
+  });
+
+  it("returns 'unknown' for empty path", () => {
+    expect(getTokenName({ path: [] })).toBe("unknown");
+  });
+
+  it("returns 'unknown' when path is absent", () => {
+    expect(getTokenName({})).toBe("unknown");
+  });
+
+  it("returns 'unknown' when all segments are filtered out", () => {
+    expect(getTokenName({ path: ["$schema", "$meta"] })).toBe("unknown");
+  });
+
+  it("handles numeric path segments", () => {
+    expect(getTokenName({ path: ["size", 4] })).toBe("size-4");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTokenMap
+// ---------------------------------------------------------------------------
+
+describe("buildTokenMap", () => {
+  it("creates a Map keyed by token name", () => {
+    const token = { path: ["color", "primary"], $value: "#fff" };
+    const dict = mockDictionary([token]);
+    const map = buildTokenMap(dict);
+    expect(map).toBeInstanceOf(Map);
+    expect(map.get("color-primary")).toBe(token);
+  });
+
+  it("caches result via WeakMap (same reference returned)", () => {
+    const dict = mockDictionary([{ path: ["a"], $value: "1" }]);
+    const first = buildTokenMap(dict);
+    const second = buildTokenMap(dict);
+    expect(first).toBe(second);
+  });
+
+  it("falls back to allTokens when unfilteredAllTokens is absent", () => {
+    const token = { path: ["size", "4"], $value: "1rem" };
+    const dict = { allTokens: [token], tokens: {} };
+    const map = buildTokenMap(dict);
+    expect(map.get("size-4")).toBe(token);
+  });
+
+  it("handles empty token list", () => {
+    const dict = mockDictionary([]);
+    const map = buildTokenMap(dict);
+    expect(map.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// convertToHex8
+// ---------------------------------------------------------------------------
+
+describe("convertToHex8", () => {
+  it("converts 6-digit hex with alpha 0.5 to hex8", () => {
+    expect(convertToHex8("#ff0000", 0.5)).toBe("#ff000080");
+  });
+
+  it("expands 3-digit shorthand hex", () => {
+    expect(convertToHex8("#f00", 1)).toBe("#ff0000FF");
+  });
+
+  it("uses alpha 0 → '00'", () => {
+    expect(convertToHex8("#ffffff", 0)).toBe("#ffffff00");
+  });
+
+  it("uses alpha 1 → 'FF'", () => {
+    expect(convertToHex8("#000000", 1)).toBe("#000000FF");
+  });
+
+  it("returns input unchanged for invalid hex (no #)", () => {
+    expect(convertToHex8("ff0000", 0.5)).toBe("ff0000");
+  });
+
+  it("returns input unchanged when not a string", () => {
+    expect(convertToHex8(null, 0.5)).toBe(null);
+    expect(convertToHex8(undefined, 0.5)).toBe(undefined);
+  });
+
+  it("returns input unchanged for wrong hex length (5 digits)", () => {
+    expect(convertToHex8("#12345", 0.5)).toBe("#12345");
+  });
+
+  it("handles floating point alpha without drift (0.06 → 6%)", () => {
+    // 0.06 * 255 = 15.3 → rounds to 15 → 0x0F
+    const result = convertToHex8("#ffffff", 0.06);
+    expect(result).toBe("#ffffff0F");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// compositeColorToCssMix
+// ---------------------------------------------------------------------------
+
+describe("compositeColorToCssMix", () => {
+  it("generates correct color-mix() with prefix", () => {
+    const result = compositeColorToCssMix(
+      "color-neutral-0",
+      "#ffffff",
+      0.08,
+      "a2-",
+    );
+    expect(result).toBe(
+      "color-mix(in srgb, var(--a2-color-neutral-0, #ffffff) 8%, transparent)",
+    );
+  });
+
+  it("generates color-mix() without prefix", () => {
+    const result = compositeColorToCssMix("color-neutral-0", "#ffffff", 0.08);
+    expect(result).toBe(
+      "color-mix(in srgb, var(--color-neutral-0, #ffffff) 8%, transparent)",
+    );
+  });
+
+  it("avoids floating point drift (0.06 → 6%)", () => {
+    const result = compositeColorToCssMix("color-neutral-0", "#fff", 0.06, "");
+    expect(result).toContain("6%");
+    expect(result).not.toContain("5.999");
+  });
+
+  it("handles alpha 1 → 100%", () => {
+    const result = compositeColorToCssMix("color-neutral-0", "#fff", 1, "");
+    expect(result).toContain("100%");
+  });
+
+  it("handles alpha 0 → 0%", () => {
+    const result = compositeColorToCssMix("color-neutral-0", "#fff", 0, "");
+    expect(result).toContain("0%");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveReference
+// ---------------------------------------------------------------------------
+
+describe("resolveReference", () => {
+  it("returns non-strings unchanged", () => {
+    const obj = { $value: "#fff" };
+    expect(resolveReference(obj, {}, () => obj)).toBe(obj);
+  });
+
+  it("calls resolveReferences with the string and dictionary tokens", () => {
+    const resolveFn = vi.fn().mockReturnValue("#resolved");
+    const dict = { tokens: { color: {} }, unfilteredTokens: { color: {} } };
+    const result = resolveReference("{color.primary}", dict, resolveFn);
+    expect(result).toBe("#resolved");
+    expect(resolveFn).toHaveBeenCalledWith(
+      "{color.primary}",
+      dict.unfilteredTokens,
+      { usesDtcg: true },
+    );
+  });
+
+  it("falls back to original string if resolveReferences throws", () => {
+    const resolveFn = () => {
+      throw new Error("unresolvable");
+    };
+    const dict = { tokens: {}, unfilteredTokens: {} };
+    const result = resolveReference("{bad.ref}", dict, resolveFn);
+    expect(result).toBe("{bad.ref}");
+  });
+
+  it("uses unfilteredTokens when available over tokens", () => {
+    const resolveFn = vi.fn().mockReturnValue("#ok");
+    const dict = {
+      tokens: { a: 1 },
+      unfilteredTokens: { a: 1, b: 2 },
+    };
+    resolveReference("{a}", dict, resolveFn);
+    expect(resolveFn).toHaveBeenCalledWith("{a}", dict.unfilteredTokens, {
+      usesDtcg: true,
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveCompositeColor
+// ---------------------------------------------------------------------------
+
+describe("resolveCompositeColor", () => {
+  it("returns null for non-composite-color input", () => {
+    const dict = mockDictionary([]);
+    expect(resolveCompositeColor("#fff", dict, mockResolveReferences)).toBe(
+      null,
+    );
+  });
+
+  it("returns hex8 when no tokenMap provided", () => {
+    const colorObj = { color: "#ffffff", alpha: 0.5 };
+    const dict = mockDictionary([]);
+    const resolveFn = vi.fn().mockReturnValue("#ffffff");
+    const result = resolveCompositeColor(colorObj, dict, resolveFn);
+    expect(result).toBe("#ffffff80");
+  });
+
+  it("returns color-mix() when tokenMap has the referenced token", () => {
+    const refToken = { path: ["color", "neutral", "0"], $value: "#ffffff" };
+    const dict = mockDictionary([refToken]);
+    const tokenMap = buildTokenMap(dict);
+    const colorObj = { color: "{color.neutral.0}", alpha: 0.08 };
+    const resolveFn = vi.fn().mockReturnValue("#ffffff");
+    const result = resolveCompositeColor(
+      colorObj,
+      dict,
+      resolveFn,
+      tokenMap,
+      "a2-",
+    );
+    expect(result).toBe(
+      "color-mix(in srgb, var(--a2-color-neutral-0, #ffffff) 8%, transparent)",
+    );
+  });
+
+  it("returns hex8 when tokenMap does not contain the referenced token", () => {
+    const dict = mockDictionary([]);
+    const tokenMap = new Map();
+    const colorObj = { color: "{color.missing}", alpha: 0.5 };
+    const resolveFn = vi.fn().mockReturnValue("#aabbcc");
+    const result = resolveCompositeColor(
+      colorObj,
+      dict,
+      resolveFn,
+      tokenMap,
+      "a2-",
+    );
+    expect(result).toBe("#aabbcc80");
+  });
+
+  it("returns resolved color value when color doesn't start with #", () => {
+    const dict = mockDictionary([]);
+    const colorObj = { color: "{some.ref}", alpha: 0.5 };
+    const resolveFn = vi.fn().mockReturnValue("rgb(255,255,255)");
+    const result = resolveCompositeColor(colorObj, dict, resolveFn);
+    expect(result).toBe("rgb(255,255,255)");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTokenValue
+// ---------------------------------------------------------------------------
+
+describe("getTokenValue", () => {
+  const resolveFn = (val) => val; // identity
+
+  it("returns plain string value", () => {
+    const token = { $value: "#abc123" };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe(
+      "#abc123",
+    );
+  });
+
+  it("returns dark value when isDark=true and dark value exists", () => {
+    const token = {
+      $value: "#ffffff",
+      $extensions: { appearance: { dark: { $value: "#000000" } } },
+    };
+    expect(
+      getTokenValue(token, mockDictionary(), { isDark: true }, resolveFn),
+    ).toBe("#000000");
+  });
+
+  it("returns light value when isDark=true but no dark value", () => {
+    const token = { $value: "#ffffff" };
+    expect(
+      getTokenValue(token, mockDictionary(), { isDark: true }, resolveFn),
+    ).toBe("#ffffff");
+  });
+
+  it("unpacks dimension objects { value, unit }", () => {
+    const token = { $value: { value: 16, unit: "px" } };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe("16px");
+  });
+
+  it("normalizes 'transparent' to rgba(0, 0, 0, 0)", () => {
+    const token = { $value: "transparent" };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe(
+      "rgba(0, 0, 0, 0)",
+    );
+  });
+
+  it("returns empty string for undefined value", () => {
+    const token = { $value: undefined };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe("");
+  });
+
+  it("returns empty string for null value", () => {
+    const token = { $value: null };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe("");
+  });
+
+  it("wraps comma-containing values when forScssMap=true", () => {
+    const token = { $value: "Arial, sans-serif" };
+    expect(
+      getTokenValue(token, mockDictionary(), { forScssMap: true }, resolveFn),
+    ).toBe('"Arial, sans-serif"');
+  });
+
+  it("does NOT wrap comma values when forScssMap=false", () => {
+    const token = { $value: "Arial, sans-serif" };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe(
+      "Arial, sans-serif",
+    );
+  });
+
+  it("resolves composite color value", () => {
+    const token = { $value: { color: "#ffffff", alpha: 0.5 } };
+    const resolveFnHex = vi.fn().mockReturnValue("#ffffff");
+    const result = getTokenValue(token, mockDictionary(), {}, resolveFnHex);
+    expect(result).toBe("#ffffff80");
+  });
+
+  it("stringifies non-string non-object values", () => {
+    const token = { $value: 42 };
+    expect(getTokenValue(token, mockDictionary(), {}, resolveFn)).toBe("42");
+  });
+
+  it("extracts value from token-object returned by resolveReferences", () => {
+    // resolveReferences returns a full token object
+    const resolveFnObj = () => ({ $value: "#resolved" });
+    const token = { $value: "{some.ref}" };
+    const dict = { allTokens: [], tokens: {}, unfilteredTokens: {} };
+    const result = getTokenValue(token, dict, {}, resolveFnObj);
+    expect(result).toBe("#resolved");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isReferenceString
+// ---------------------------------------------------------------------------
+
+describe("isReferenceString", () => {
+  it("returns true for strings usesReferences considers a reference", () => {
+    expect(isReferenceString("{color.primary}", mockUsesReferences)).toBe(true);
+  });
+
+  it("returns false for plain strings", () => {
+    expect(isReferenceString("#ffffff", mockUsesReferences)).toBe(false);
+  });
+
+  it("returns false for non-strings", () => {
+    expect(isReferenceString(42, mockUsesReferences)).toBe(false);
+    expect(isReferenceString(null, mockUsesReferences)).toBe(false);
+    expect(isReferenceString(undefined, mockUsesReferences)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildRecursiveVarChainWithLightDark
+// ---------------------------------------------------------------------------
+
+describe("buildRecursiveVarChainWithLightDark", () => {
+  const resolveRefsFn = (val) => val;
+
+  it("returns non-reference values as-is", () => {
+    const tokenMap = new Map();
+    const dict = mockDictionary([]);
+    const result = buildRecursiveVarChainWithLightDark(
+      "#ffffff",
+      tokenMap,
+      dict,
+      false,
+      mockUsesReferences,
+      resolveRefsFn,
+      "a2-",
+    );
+    expect(result).toBe("#ffffff");
+  });
+
+  it("returns var(--name) for unknown token references", () => {
+    const tokenMap = new Map();
+    const dict = mockDictionary([]);
+    const result = buildRecursiveVarChainWithLightDark(
+      "{unknown.token}",
+      tokenMap,
+      dict,
+      false,
+      mockUsesReferences,
+      resolveRefsFn,
+      "a2-",
+    );
+    expect(result).toBe("var(--a2-unknown-token)");
+  });
+
+  it("builds var chain for primitive token (no dark variant)", () => {
+    const primToken = {
+      path: ["color", "neutral", "0"],
+      $value: "#ffffff",
+      original: { $value: "#ffffff" },
+    };
+    const tokenMap = new Map([["color-neutral-0", primToken]]);
+    const dict = mockDictionary([primToken]);
+    const result = buildRecursiveVarChainWithLightDark(
+      "{color.neutral.0}",
+      tokenMap,
+      dict,
+      true,
+      mockUsesReferences,
+      resolveRefsFn,
+      "a2-",
+    );
+    expect(result).toBe("var(--a2-color-neutral-0, #ffffff)");
+  });
+
+  it("inserts light-dark() when light and dark values differ", () => {
+    const primToken = {
+      path: ["color", "neutral", "0"],
+      $value: "#ffffff",
+      original: {
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      },
+      $extensions: { appearance: { dark: { $value: "#000000" } } },
+    };
+    const dict = mockDictionary([primToken]);
+    const tokenMap = buildTokenMap(dict);
+    const resolveRefs = vi.fn().mockReturnValue("#ffffff");
+
+    const result = buildRecursiveVarChainWithLightDark(
+      "{color.neutral.0}",
+      tokenMap,
+      dict,
+      true,
+      mockUsesReferences,
+      resolveRefs,
+      "a2-",
+    );
+    expect(result).toContain("light-dark(");
+    expect(result).toContain("var(--a2-color-neutral-0,");
+  });
+
+  it("propagates recursion through intermediate references", () => {
+    const primToken = {
+      path: ["color", "red", "500"],
+      $value: "#e13212",
+      original: { $value: "#e13212" },
+    };
+    const semanticToken = {
+      path: ["status", "color", "danger"],
+      $value: "{color.red.500}",
+      original: { $value: "{color.red.500}" },
+    };
+    const dict = mockDictionary([primToken, semanticToken]);
+    const tokenMap = buildTokenMap(dict);
+
+    const result = buildRecursiveVarChainWithLightDark(
+      "{status.color.danger}",
+      tokenMap,
+      dict,
+      false,
+      mockUsesReferences,
+      resolveRefsFn,
+      "a2-",
+    );
+    // Should chain through to the primitive
+    expect(result).toContain("var(--a2-status-color-danger,");
+    expect(result).toContain("var(--a2-color-red-500,");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildFallbackWithRefs
+// ---------------------------------------------------------------------------
+
+describe("buildFallbackWithRefs", () => {
+  const resolveRefsFn = (val) => val;
+
+  it("returns resolved plain value when no references", () => {
+    const token = { $value: "#ffffff", original: { $value: "#ffffff" } };
+    const dict = mockDictionary([token]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      {},
+      mockUsesReferences,
+      resolveRefsFn,
+    );
+    expect(result).toBe("#ffffff");
+  });
+
+  it("returns light-dark() when top-level light and dark values differ", () => {
+    const token = {
+      $value: "#ffffff",
+      original: {
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      },
+      $extensions: { appearance: { dark: { $value: "#000000" } } },
+    };
+    const dict = mockDictionary([token]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { useLightDark: true },
+      mockUsesReferences,
+      resolveRefsFn,
+    );
+    expect(result).toBe("light-dark(#ffffff, #000000)");
+  });
+
+  it("returns plain value when light and dark are the same", () => {
+    const token = {
+      $value: "#ffffff",
+      original: {
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#ffffff" } } },
+      },
+      $extensions: { appearance: { dark: { $value: "#ffffff" } } },
+    };
+    const dict = mockDictionary([token]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { useLightDark: true },
+      mockUsesReferences,
+      resolveRefsFn,
+    );
+    expect(result).toBe("#ffffff");
+  });
+
+  it("returns dark value when isDark=true and no references", () => {
+    const token = {
+      $value: "#ffffff",
+      original: {
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#111111" } } },
+      },
+      $extensions: { appearance: { dark: { $value: "#111111" } } },
+    };
+    const dict = mockDictionary([token]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { isDark: true },
+      mockUsesReferences,
+      resolveRefsFn,
+    );
+    expect(result).toBe("#111111");
+  });
+
+  it("handles reference values (light=dark=ref) without light-dark()", () => {
+    const primToken = {
+      path: ["color", "neutral", "0"],
+      $value: "#ffffff",
+      original: { $value: "#ffffff" },
+    };
+    const token = {
+      $value: "{color.neutral.0}",
+      original: { $value: "{color.neutral.0}" },
+      path: ["semantic", "bg"],
+    };
+    const dict = mockDictionary([primToken, token]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { useLightDark: false },
+      mockUsesReferences,
+      resolveRefsFn,
+    );
+    expect(result).toContain("var(--color-neutral-0,");
+  });
+
+  it("handles composite color with light-dark() when referenced token has dark", () => {
+    const refToken = {
+      path: ["color", "neutral", "0"],
+      $value: "#ffffff",
+      original: {
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      },
+      $extensions: { appearance: { dark: { $value: "#000000" } } },
+    };
+    const token = {
+      $value: { color: "{color.neutral.0}", alpha: 0.08 },
+      original: { $value: { color: "{color.neutral.0}", alpha: 0.08 } },
+    };
+    const resolveRefs = vi.fn().mockReturnValue("#ffffff");
+    const dict = mockDictionary([refToken]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { useLightDark: true, cssVarPrefix: "a2-" },
+      mockUsesReferences,
+      resolveRefs,
+    );
+    expect(result).toContain("light-dark(");
+    expect(result).toContain("color-mix(");
+  });
+
+  it("handles composite color (same light/dark) falling through to color-mix()", () => {
+    const refToken = {
+      path: ["color", "neutral", "0"],
+      $value: "#ffffff",
+      original: { $value: "#ffffff" },
+    };
+    const token = {
+      $value: { color: "{color.neutral.0}", alpha: 0.5 },
+      original: { $value: { color: "{color.neutral.0}", alpha: 0.5 } },
+    };
+    const resolveRefs = vi.fn().mockReturnValue("#ffffff");
+    const dict = mockDictionary([refToken]);
+    const tokenMap = buildTokenMap(dict);
+    const result = buildFallbackWithRefs(
+      token,
+      dict,
+      tokenMap,
+      { useLightDark: false, cssVarPrefix: "a2-" },
+      mockUsesReferences,
+      resolveRefs,
+    );
+    expect(result).toContain("color-mix(");
+    expect(result).toContain("#ffffff");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isGradientValue
+// ---------------------------------------------------------------------------
+
+describe("isGradientValue", () => {
+  it("returns true for a valid gradient object", () => {
+    expect(isGradientValue({ type: "linear", angle: 90, stops: [] })).toBe(
+      true,
+    );
+  });
+
+  it("returns false for strings", () => {
+    expect(isGradientValue("#fff")).toBe(false);
+  });
+
+  it("returns false for arrays", () => {
+    expect(isGradientValue([{ type: "linear" }])).toBe(false);
+  });
+
+  it("returns falsy for null/undefined", () => {
+    expect(isGradientValue(null)).toBeFalsy();
+    expect(isGradientValue(undefined)).toBeFalsy();
+  });
+
+  it("returns false when type is not a string", () => {
+    expect(isGradientValue({ type: 42, angle: 90, stops: [] })).toBe(false);
+  });
+
+  it("returns false when angle is not a number", () => {
+    expect(isGradientValue({ type: "linear", angle: "90deg", stops: [] })).toBe(
+      false,
+    );
+  });
+
+  it("returns false when stops is not an array", () => {
+    expect(isGradientValue({ type: "linear", angle: 90, stops: null })).toBe(
+      false,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveGradientValue
+// ---------------------------------------------------------------------------
+
+const makeGradientValue = (overrides = {}) => ({
+  type: "linear",
+  angle: 90,
+  stops: [],
+  ...overrides,
+});
+
+describe("resolveGradientValue", () => {
+  it("returns gradient value directly from token.original.$value", () => {
+    const gradient = makeGradientValue({ stops: [] });
+    const token = { original: { $value: gradient } };
+    expect(resolveGradientValue(token, new Map())).toBe(gradient);
+  });
+
+  it("follows a reference string to find the gradient in tokenMap", () => {
+    const gradient = makeGradientValue();
+    const refToken = { original: { $value: gradient } };
+    const tokenMap = new Map([["gradient-primary", refToken]]);
+    const token = { original: { $value: "{gradient.primary}" } };
+    expect(resolveGradientValue(token, tokenMap)).toBe(gradient);
+  });
+
+  it("returns null when reference cannot be found in tokenMap", () => {
+    const token = { original: { $value: "{gradient.missing}" } };
+    expect(resolveGradientValue(token, new Map())).toBeNull();
+  });
+
+  it("returns null when original.$value is a plain string (not a reference)", () => {
+    const token = { original: { $value: "some-string" } };
+    expect(resolveGradientValue(token, new Map())).toBeNull();
+  });
+
+  it("returns null when original is absent", () => {
+    expect(resolveGradientValue({}, new Map())).toBeNull();
+  });
+
+  it("resolves nested references (reference pointing to another reference)", () => {
+    const gradient = makeGradientValue();
+    const leafToken = { original: { $value: gradient } };
+    const midToken = { original: { $value: "{gradient.primary}" } };
+    const tokenMap = new Map([
+      ["gradient-primary", leafToken],
+      ["alias-gradient", midToken],
+    ]);
+    const token = { original: { $value: "{alias.gradient}" } };
+    expect(resolveGradientValue(token, tokenMap)).toBe(gradient);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildGradientValue
+// ---------------------------------------------------------------------------
+
+describe("buildGradientValue", () => {
+  const usesRefs = (v) => typeof v === "string" && v.includes("{");
+  const resolveRefs = (v) => v;
+
+  const makeStop = (lightRef, darkRef, position) => ({
+    position,
+    color: {
+      $type: "color",
+      $value: lightRef,
+      $extensions: {
+        appearance: {
+          light: { $type: "color", $value: lightRef },
+          dark: { $type: "color", $value: darkRef },
+        },
+      },
+    },
+  });
+
+  it("produces linear-gradient() with correct angle", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [
+        makeStop("#0265dc", "#45d8f2", 0),
+        makeStop("#45d8f2", "#cdf4fb", 1),
+      ],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toMatch(/^linear-gradient\(90deg,/);
+  });
+
+  it("uses light stop colors when isDark=false", () => {
+    const gradient = {
+      type: "linear",
+      angle: 45,
+      stops: [makeStop("#aaaaaa", "#111111", 0)],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("#aaaaaa");
+    expect(result).not.toContain("#111111");
+  });
+
+  it("uses dark stop colors when isDark=true", () => {
+    const gradient = {
+      type: "linear",
+      angle: 45,
+      stops: [makeStop("#aaaaaa", "#111111", 0)],
+    };
+    const result = buildGradientValue(
+      gradient,
+      true,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("#111111");
+    expect(result).not.toContain("#aaaaaa");
+  });
+
+  it("passes string positions through as-is", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [
+        makeStop("#fff", "#000", "10px"),
+        makeStop("#000", "#fff", "50px"),
+      ],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("10px");
+    expect(result).toContain("50px");
+    expect(result).not.toContain("1000%");
+  });
+
+  it("resolves token references embedded in string positions", () => {
+    const sizeToken = {
+      path: ["size", "4"],
+      $value: "1rem",
+      original: { $value: "1rem" },
+    };
+    const tokenMap = new Map([["size-4", sizeToken]]);
+    const dict = mockDictionary([sizeToken]);
+
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [makeStop("#fff", "#000", "calc(100% - {size.4})")],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      tokenMap,
+      dict,
+      "a2-",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("calc(100% - var(--a2-size-4,");
+    expect(result).not.toContain("{size.4}");
+  });
+
+  it("converts position 0→'0%' and 1→'100%'", () => {
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [makeStop("#fff", "#000", 0), makeStop("#000", "#fff", 1)],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("0%");
+    expect(result).toContain("100%");
+  });
+
+  it("builds var() chain for reference color stops", () => {
+    const blueToken = {
+      path: ["color", "blue", "600"],
+      $value: "#0265dc",
+      original: { $value: "#0265dc" },
+    };
+    const tokenMap = new Map([["color-blue-600", blueToken]]);
+    const dict = mockDictionary([blueToken]);
+
+    const gradient = {
+      type: "linear",
+      angle: 90,
+      stops: [makeStop("{color.blue.600}", "{color.blue.600}", 0)],
+    };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      tokenMap,
+      dict,
+      "a2-",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("var(--a2-color-blue-600,");
+  });
+
+  it("falls back to stop.$value when appearance light/dark is absent", () => {
+    const stop = {
+      position: 0,
+      color: { $type: "color", $value: "#fallback" },
+    };
+    const gradient = { type: "linear", angle: 90, stops: [stop] };
+    const result = buildGradientValue(
+      gradient,
+      false,
+      new Map(),
+      mockDictionary(),
+      "",
+      usesRefs,
+      resolveRefs,
+    );
+    expect(result).toContain("#fallback");
+  });
+});