@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/__tests__/sd-formats.test.js

@@ -0,0 +1,950 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { registerFormats } from "../sd-formats.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a mock StyleDictionary that captures registered format functions
+ * so we can call them directly in tests.
+ */
+const createMockSD = () => {
+  const formats = {};
+  return {
+    registerFormat: vi.fn(({ name, format }) => {
+      formats[name] = format;
+    }),
+    _formats: formats,
+  };
+};
+
+const mockUsesReferences = (value) =>
+  typeof value === "string" && value.includes("{");
+
+const mockResolveReferences = (val) => val;
+
+const makeToken = (overrides = {}) => ({
+  path: ["color", "primary"],
+  $value: "#ffffff",
+  $type: "color",
+  original: { $value: "#ffffff" },
+  ...overrides,
+});
+
+const makeDictionary = (tokens = []) => ({
+  allTokens: tokens,
+  unfilteredAllTokens: tokens,
+  tokens: {},
+  unfilteredTokens: {},
+});
+
+let sd;
+beforeEach(() => {
+  sd = createMockSD();
+  registerFormats(sd, mockUsesReferences, mockResolveReferences, "a2-");
+});
+
+// ---------------------------------------------------------------------------
+// Registration checks
+// ---------------------------------------------------------------------------
+
+describe("registerFormats", () => {
+  it("registers custom/scss-variables", () => {
+    expect(sd._formats["custom/scss-variables"]).toBeDefined();
+  });
+
+  it("registers custom/scss-variables-map", () => {
+    expect(sd._formats["custom/scss-variables-map"]).toBeDefined();
+  });
+
+  it("registers custom/es6-variable", () => {
+    expect(sd._formats["custom/es6-variable"]).toBeDefined();
+  });
+
+  it("registers custom/CSSVariables", () => {
+    expect(sd._formats["custom/CSSVariables"]).toBeDefined();
+  });
+
+  it("registers CSS utils formats for both prefixes", () => {
+    expect(sd._formats["custom/CSSUtils/All"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/a2-All"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/Colors"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/a2-Colors"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/Borders"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/a2-Borders"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/Fonts"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/a2-Fonts"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/Spacing"]).toBeDefined();
+    expect(sd._formats["custom/CSSUtils/a2-Spacing"]).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildCssUtilsOutput (tested via the format output)
+// ---------------------------------------------------------------------------
+
+describe("buildCssUtilsOutput structure (via Fonts format)", () => {
+  it("output contains @layer declaration", () => {
+    const format = sd._formats["custom/CSSUtils/Fonts"];
+    const dict = makeDictionary([
+      makeToken({
+        path: ["typography", "body", "font-family"],
+        $value: "Arial",
+      }),
+    ]);
+    const output = format({ dictionary: dict });
+    expect(output).toContain("@layer");
+    expect(output).toContain("starter");
+  });
+
+  it("output contains @layer application block", () => {
+    const format = sd._formats["custom/CSSUtils/Fonts"];
+    const dict = makeDictionary([]);
+    const output = format({ dictionary: dict });
+    expect(output).toContain("@layer application");
+  });
+
+  it("does NOT include @supports block when no dark-aware classes", () => {
+    const format = sd._formats["custom/CSSUtils/Fonts"];
+    const dict = makeDictionary([
+      makeToken({
+        path: ["typography", "body", "font-family"],
+        $value: "Arial",
+      }),
+    ]);
+    const output = format({ dictionary: dict });
+    expect(output).not.toContain("@supports");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSVariables format
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSVariables", () => {
+  const format = () => sd._formats["custom/CSSVariables"];
+
+  it("wraps output in :root { ... }", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["color", "primary"], $value: "#ffffff" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toMatch(/^:root \{/);
+    expect(output).toMatch(/\}$/);
+  });
+
+  it("outputs CSS custom properties for each token", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["size", "4"], $value: "1rem", $type: "dimension" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("--a2-size-4: 1rem;");
+  });
+
+  it("includes light-dark() for tokens with dark value", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("light-dark(#ffffff, #000000)");
+  });
+
+  it("strips -default suffix from token name", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "default"],
+        $value: "#fff",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("--a2-background-color:");
+    expect(output).not.toContain("--a2-background-color-default:");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/scss-variables format
+// ---------------------------------------------------------------------------
+
+describe("custom/scss-variables", () => {
+  const format = () => sd._formats["custom/scss-variables"];
+
+  it("generates $name: var(--prefix-name, fallback); for regular tokens", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["color", "primary"], $value: "#ffffff" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("$color-primary: var(--a2-color-primary,");
+  });
+
+  it("generates plain value for overlay-color tokens (no CSS var)", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["overlay", "color", "scrim"],
+        $value: "rgba(0,0,0,0.5)",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("$overlay-color-scrim: rgba(0,0,0,0.5);");
+    expect(output).not.toContain("var(--");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/scss-variables-map format
+// ---------------------------------------------------------------------------
+
+describe("custom/scss-variables-map", () => {
+  const format = () => sd._formats["custom/scss-variables-map"];
+
+  it("generates $token map when no tokens have dark variants", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["size", "4"], $value: "1rem", $type: "dimension" }),
+    ]);
+    const output = format()({ dictionary: dict, file: {} });
+    expect(output).toContain("$token: (");
+  });
+
+  it("generates $light, $dark, $nonColor maps when tokens have dark variants", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $type: "color",
+        original: {
+          $value: "#ffffff",
+          $extensions: { appearance: { dark: { $value: "#000000" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict, file: {} });
+    expect(output).toContain("$light: (");
+    expect(output).toContain("$dark: (");
+    expect(output).toContain("$nonColor: (");
+  });
+
+  it("detects component build via file.destination containing 'component'", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $type: "color",
+        original: {
+          $value: "#ffffff",
+          $extensions: { appearance: { dark: { $value: "#000000" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+        filePath: "src/theme/core/component/button.tokens.json",
+      }),
+    ]);
+    // Should not throw for component build
+    expect(() =>
+      format()({
+        dictionary: dict,
+        file: { destination: "component-variables.scss" },
+      }),
+    ).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/es6-variable format
+// ---------------------------------------------------------------------------
+
+describe("custom/es6-variable", () => {
+  const format = () => sd._formats["custom/es6-variable"];
+
+  it("generates TokenValue export for tokens without dark variant", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["size", "4"], $value: "1rem", $type: "dimension" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@type {TokenValue}");
+    expect(output).toContain('export const Size4 = { value: "1rem" };');
+  });
+
+  it("generates TokenWithAppearance export for tokens with dark variant", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $type: "color",
+        original: {
+          $value: "#ffffff",
+          $extensions: { appearance: { dark: { $value: "#000000" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@type {TokenWithAppearance}");
+    expect(output).toContain("extensions");
+    expect(output).toContain("appearance");
+    expect(output).toContain("dark");
+  });
+
+  it("converts token name to PascalCase export name", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "primary"],
+        $value: "#fff",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("export const BackgroundColorPrimary");
+  });
+
+  it("includes type definition header", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@typedef {Object} TokenValue");
+    expect(output).toContain("@typedef {Object} TokenWithAppearance");
+  });
+
+  it("includes @description JSDoc tag when token has $description", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["size", "4"],
+        $value: "1rem",
+        $type: "dimension",
+        $description: "Base spacing unit",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@description Base spacing unit");
+  });
+
+  it("omits @description tag when token has no $description", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["size", "4"], $value: "1rem", $type: "dimension" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).not.toContain("@description");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSVariables — $description comment
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSVariables — $description comments", () => {
+  const format = () => sd._formats["custom/CSSVariables"];
+
+  it("prepends /* description */ comment when token has $description", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $description: "Primary brand color",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("/* Primary brand color */");
+  });
+
+  it("omits comment when token has no $description", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["color", "primary"], $value: "#ffffff" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).not.toContain("/*");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/scss-variables — $description comment
+// ---------------------------------------------------------------------------
+
+describe("custom/scss-variables — $description comments", () => {
+  const format = () => sd._formats["custom/scss-variables"];
+
+  it("prepends // description comment when token has $description", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#ffffff",
+        $description: "Primary brand color",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("// Primary brand color");
+  });
+
+  it("prepends // comment for overlay-color tokens with $description", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["overlay", "color", "scrim"],
+        $value: "rgba(0,0,0,0.5)",
+        $description: "Scrim overlay",
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("// Scrim overlay");
+    expect(output).toContain("$overlay-color-scrim:");
+  });
+
+  it("omits comment when token has no $description", () => {
+    const dict = makeDictionary([
+      makeToken({ path: ["color", "primary"], $value: "#ffffff" }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).not.toContain("//");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSUtils/Colors format
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSUtils/Colors", () => {
+  const format = () => sd._formats["custom/CSSUtils/Colors"];
+
+  it("output contains @layer declaration", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@layer");
+  });
+
+  it("generates .bg-* class for background-color tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "primary"],
+        $value: "#ffffff",
+        original: { $value: "#ffffff" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain(".bg-primary");
+    expect(output).toContain("background-color:");
+  });
+
+  it("includes @supports block for tokens with dark variants", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "primary"],
+        $value: "#ffffff",
+        original: {
+          $value: "#ffffff",
+          $extensions: { appearance: { dark: { $value: "#111111" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#111111" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@supports (color: light-dark(#fff, #000))");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSUtils/Borders format
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSUtils/Borders", () => {
+  const format = () => sd._formats["custom/CSSUtils/Borders"];
+
+  it("output contains @layer declaration", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@layer");
+  });
+
+  it("generates border-radius class", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["border", "radius", "small"],
+        $value: "4px",
+        $type: "dimension",
+        original: { $value: "4px" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("border-radius:");
+    expect(output).toContain("4px");
+  });
+
+  it("includes @supports block for border-color tokens with dark variants", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["border", "color", "default"],
+        $value: "#cccccc",
+        $type: "color",
+        original: {
+          $value: "#cccccc",
+          $extensions: { appearance: { dark: { $value: "#444444" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#444444" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@supports (color: light-dark(#fff, #000))");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSUtils/Spacing format
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSUtils/Spacing", () => {
+  const format = () => sd._formats["custom/CSSUtils/Spacing"];
+
+  it("output contains @layer declaration", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@layer");
+  });
+
+  it("generates spacing classes for size tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["size", "4"],
+        $value: "1rem",
+        $type: "dimension",
+        original: { $value: "1rem" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("margin");
+    expect(output).toContain("padding");
+    expect(output).toContain("-4");
+  });
+
+  it("ignores non-size tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["color", "primary"],
+        $value: "#fff",
+        original: { $value: "#fff" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    // Should not contain color-related properties
+    expect(output).not.toContain("background-color");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// custom/CSSUtils/All format
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSUtils/All", () => {
+  const format = () => sd._formats["custom/CSSUtils/All"];
+
+  it("output contains @layer declaration", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@layer");
+  });
+
+  it("includes .sr-only utility class", () => {
+    const dict = makeDictionary([]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain(".sr-only");
+  });
+
+  it("generates color classes for background-color tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "primary"],
+        $value: "#ffffff",
+        original: { $value: "#ffffff" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("background-color");
+  });
+
+  it("generates spacing classes for size tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["size", "4"],
+        $value: "1rem",
+        $type: "dimension",
+        original: { $value: "1rem" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("margin");
+    expect(output).toContain("padding");
+  });
+
+  it("generates font classes for typography tokens", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["typography", "body", "font-family"],
+        $value: "Arial",
+        $type: "fontFamily",
+        original: { $value: "Arial" },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("font-family");
+  });
+
+  it("includes @supports block for color tokens with dark variants", () => {
+    const dict = makeDictionary([
+      makeToken({
+        path: ["background", "color", "primary"],
+        $value: "#ffffff",
+        original: {
+          $value: "#ffffff",
+          $extensions: { appearance: { dark: { $value: "#000000" } } },
+        },
+        $extensions: { appearance: { dark: { $value: "#000000" } } },
+      }),
+    ]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@supports (color: light-dark(#fff, #000))");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gradient tokens in custom/CSSVariables
+// ---------------------------------------------------------------------------
+
+describe("custom/CSSVariables — gradient tokens", () => {
+  const format = () => sd._formats["custom/CSSVariables"];
+
+  const makeGradientToken = (hasDark = true) => ({
+    path: ["gradient", "primary"],
+    $type: "gradient",
+    $value: {
+      type: "linear",
+      angle: 90,
+      stops: [
+        {
+          position: 0,
+          color: {
+            $type: "color",
+            $value: "#0265dc",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#0265dc" },
+                ...(hasDark
+                  ? { dark: { $type: "color", $value: "#45d8f2" } }
+                  : {}),
+              },
+            },
+          },
+        },
+        {
+          position: 1,
+          color: {
+            $type: "color",
+            $value: "#45d8f2",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#45d8f2" },
+                ...(hasDark
+                  ? { dark: { $type: "color", $value: "#cdf4fb" } }
+                  : {}),
+              },
+            },
+          },
+        },
+      ],
+    },
+    original: {
+      $value: {
+        type: "linear",
+        angle: 90,
+        stops: [
+          {
+            position: 0,
+            color: {
+              $type: "color",
+              $value: "#0265dc",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#0265dc" },
+                  ...(hasDark
+                    ? { dark: { $type: "color", $value: "#45d8f2" } }
+                    : {}),
+                },
+              },
+            },
+          },
+          {
+            position: 1,
+            color: {
+              $type: "color",
+              $value: "#45d8f2",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#45d8f2" },
+                  ...(hasDark
+                    ? { dark: { $type: "color", $value: "#cdf4fb" } }
+                    : {}),
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  });
+
+  it("emits CSS variable with linear-gradient() for gradient token", () => {
+    const dict = makeDictionary([makeGradientToken(false)]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("--a2-gradient-primary:");
+    expect(output).toContain("linear-gradient(");
+  });
+
+  it("emits light-dark() wrapper for gradient token with dark stop variants", () => {
+    const dict = makeDictionary([makeGradientToken(true)]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("light-dark(");
+    expect(output).toContain("linear-gradient(");
+  });
+
+  it("includes $description as CSS comment for gradient token", () => {
+    const token = {
+      ...makeGradientToken(false),
+      $description: "Primary brand gradient",
+    };
+    const dict = makeDictionary([token]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("/* Primary brand gradient */");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gradient tokens in custom/scss-variables
+// ---------------------------------------------------------------------------
+
+describe("custom/scss-variables — gradient tokens", () => {
+  const format = () => sd._formats["custom/scss-variables"];
+
+  const makeGradientToken = () => ({
+    path: ["gradient", "primary"],
+    $type: "gradient",
+    $value: {
+      type: "linear",
+      angle: 90,
+      stops: [
+        {
+          position: 0,
+          color: {
+            $type: "color",
+            $value: "#0265dc",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#0265dc" },
+                dark: { $type: "color", $value: "#45d8f2" },
+              },
+            },
+          },
+        },
+      ],
+    },
+    original: {
+      $value: {
+        type: "linear",
+        angle: 90,
+        stops: [
+          {
+            position: 0,
+            color: {
+              $type: "color",
+              $value: "#0265dc",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#0265dc" },
+                  dark: { $type: "color", $value: "#45d8f2" },
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  });
+
+  it("emits $name: var(--prefix-name, linear-gradient(...)) for gradient tokens", () => {
+    const dict = makeDictionary([makeGradientToken()]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("$gradient-primary:");
+    expect(output).toContain("linear-gradient(");
+  });
+
+  it("includes $description as SCSS comment for gradient token", () => {
+    const token = {
+      ...makeGradientToken(),
+      $description: "Primary brand gradient",
+    };
+    const dict = makeDictionary([token]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("// Primary brand gradient");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gradient tokens in custom/es6-variable
+// ---------------------------------------------------------------------------
+
+describe("custom/es6-variable — gradient tokens", () => {
+  const format = () => sd._formats["custom/es6-variable"];
+
+  const makeGradientToken = () => ({
+    path: ["gradient", "primary"],
+    $type: "gradient",
+    $value: {
+      type: "linear",
+      angle: 90,
+      stops: [
+        {
+          position: 0,
+          color: {
+            $type: "color",
+            $value: "#0265dc",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#0265dc" },
+                dark: { $type: "color", $value: "#45d8f2" },
+              },
+            },
+          },
+        },
+        {
+          position: 1,
+          color: {
+            $type: "color",
+            $value: "#45d8f2",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#45d8f2" },
+                dark: { $type: "color", $value: "#cdf4fb" },
+              },
+            },
+          },
+        },
+      ],
+    },
+    original: {
+      $value: {
+        type: "linear",
+        angle: 90,
+        stops: [
+          {
+            position: 0,
+            color: {
+              $type: "color",
+              $value: "#0265dc",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#0265dc" },
+                  dark: { $type: "color", $value: "#45d8f2" },
+                },
+              },
+            },
+          },
+          {
+            position: 1,
+            color: {
+              $type: "color",
+              $value: "#45d8f2",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#45d8f2" },
+                  dark: { $type: "color", $value: "#cdf4fb" },
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  });
+
+  it("emits TokenWithAppearance export for gradient tokens with dark stops", () => {
+    const dict = makeDictionary([makeGradientToken()]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@type {TokenWithAppearance}");
+    expect(output).toContain("GradientPrimary");
+  });
+
+  it("includes both light and dark gradient string values", () => {
+    const dict = makeDictionary([makeGradientToken()]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("linear-gradient(");
+    // es6-variable uses { value: "<light>", extensions: { appearance: { dark: { value: "<dark>" } } } }
+    expect(output).toContain("value:");
+    expect(output).toContain("dark:");
+  });
+
+  it("includes $description as @description JSDoc tag for gradient token", () => {
+    const token = {
+      ...makeGradientToken(),
+      $description: "Primary brand gradient",
+    };
+    const dict = makeDictionary([token]);
+    const output = format()({ dictionary: dict });
+    expect(output).toContain("@description Primary brand gradient");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gradient tokens in custom/scss-variables-map
+// ---------------------------------------------------------------------------
+
+describe("custom/scss-variables-map — gradient tokens", () => {
+  const format = () => sd._formats["custom/scss-variables-map"];
+
+  const makeGradientToken = () => ({
+    path: ["gradient", "primary"],
+    $type: "gradient",
+    $value: {
+      type: "linear",
+      angle: 90,
+      stops: [
+        {
+          position: 0,
+          color: {
+            $type: "color",
+            $value: "#0265dc",
+            $extensions: {
+              appearance: {
+                light: { $type: "color", $value: "#0265dc" },
+                dark: { $type: "color", $value: "#45d8f2" },
+              },
+            },
+          },
+        },
+      ],
+    },
+    original: {
+      $value: {
+        type: "linear",
+        angle: 90,
+        stops: [
+          {
+            position: 0,
+            color: {
+              $type: "color",
+              $value: "#0265dc",
+              $extensions: {
+                appearance: {
+                  light: { $type: "color", $value: "#0265dc" },
+                  dark: { $type: "color", $value: "#45d8f2" },
+                },
+              },
+            },
+          },
+        ],
+      },
+    },
+  });
+
+  it("includes gradient in the nonColor map as a quoted string", () => {
+    const dict = makeDictionary([makeGradientToken()]);
+    const output = format()({ dictionary: dict, file: {} });
+    expect(output).toContain("gradient-primary");
+    expect(output).toContain("linear-gradient(");
+  });
+});