fix: disambiguate named styles with duplicate names (#319)

* fix: disambiguate named styles with duplicate names

Fixes #265

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: use raw style ID for collision disambiguation

Use the full Figma style ID (which is a node ID like "161:300") as the
suffix instead of stripping non-alphanumeric characters. Produces
readable output like "Heading / Large (161:300)" and avoids collisions
that could occur from truncating the ID.

Also updates test to use realistic Figma-format style IDs and names.

* refactor: extract registerStyle helper for style registration

Consolidates the repeated named-style-or-anonymous-var pattern into a
single registerStyle function. Used for text styles, fills, and effects.

Strokes remain explicit because named stroke styles store only colors
(with weight/dashes kept on the node) while anonymous strokes bundle
everything into one variable.

* refactor: unify stroke color handling with fills and effects

Stroke colors now go through registerStyle like fills and effects.
Stroke metadata (weight, dashes) always lives on the node rather than
sometimes being bundled into the style var.

* refactor: use fill prefix for stroke colors to enable deduplication

Stroke colors are structurally identical to fill colors in Figma (both
are FILL-type styles). Using the same prefix allows identical colors
used as both fills and strokes to deduplicate into a single global var.

* test: verify fill/stroke color deduplication uses fill prefix

Stroke node is placed first to ensure the test catches regressions
where stroke colors get a different prefix than fills, which would
prevent cross-context deduplication of identical colors.

* fix: align fill and stroke paint processing

Filter invisible paints from fills (matching strokes behavior) and
reverse stroke colors to CSS stacking order (matching fills behavior).
Both pipelines now process paints identically: filter visible, parse,
reverse.

---------

Co-authored-by: Clawdbot <bot@clawd.bot>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Graham Lipsman <graham@branchlabs.com>

Author: 4 people

src/extractors/built-in.ts

@@ -15,7 +15,7 @@ import {
   isTextNode,
 } from "~/transformers/text.js";
 import { hasValue, isRectangleCornerRadii } from "~/utils/identity.js";
-import { generateVarId } from "~/utils/common.js";
+import { generateVarId, isVisible } from "~/utils/common.js";
 import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
 
 // Reverse lookup cache: serialized style value → varId.
@@ -48,6 +48,26 @@ function findOrCreateVar(globalVars: GlobalVars, value: StyleTypes, prefix: stri
   return varId;
 }
 
+/**
+ * Register a style value, preferring a Figma named style when available.
+ * Falls back to an auto-generated deduplicating variable ID.
+ */
+function registerStyle(
+  node: FigmaDocumentNode,
+  context: TraversalContext,
+  value: StyleTypes,
+  styleKeys: string[],
+  prefix: string,
+): string {
+  const styleMatch = getStyleMatch(node, context, styleKeys);
+  if (styleMatch) {
+    const styleKey = resolveStyleKey(context, styleMatch, value);
+    context.globalVars.styles[styleKey] = value;
+    return styleKey;
+  }
+  return findOrCreateVar(context.globalVars, value, prefix);
+}
+
 /**
  * Extracts layout-related properties from a node.
  */
@@ -71,14 +91,7 @@ export const textExtractor: ExtractorFn = (node, result, context) => {
   if (hasTextStyle(node)) {
     const textStyle = extractTextStyle(node);
     if (textStyle) {
-      // Prefer Figma named style when available
-      const styleName = getStyleName(node, context, ["text", "typography"]);
-      if (styleName) {
-        context.globalVars.styles[styleName] = textStyle;
-        result.textStyle = styleName;
-      } else {
-        result.textStyle = findOrCreateVar(context.globalVars, textStyle, "style");
-      }
+      result.textStyle = registerStyle(node, context, textStyle, ["text", "typography"], "style");
     }
   }
 };
@@ -93,43 +106,26 @@ export const visualsExtractor: ExtractorFn = (node, result, context) => {
 
   // fills
   if (hasValue("fills", node) && Array.isArray(node.fills) && node.fills.length) {
-    const fills = node.fills.map((fill) => parsePaint(fill, hasChildren)).reverse();
-    const styleName = getStyleName(node, context, ["fill", "fills"]);
-    if (styleName) {
-      context.globalVars.styles[styleName] = fills;
-      result.fills = styleName;
-    } else {
-      result.fills = findOrCreateVar(context.globalVars, fills, "fill");
-    }
+    const fills = node.fills
+      .filter(isVisible)
+      .map((fill) => parsePaint(fill, hasChildren))
+      .reverse();
+    result.fills = registerStyle(node, context, fills, ["fill", "fills"], "fill");
   }
 
   // strokes
   const strokes = buildSimplifiedStrokes(node, hasChildren);
   if (strokes.colors.length) {
-    const styleName = getStyleName(node, context, ["stroke", "strokes"]);
-    if (styleName) {
-      // Only colors are stylable; keep other stroke props on the node
-      context.globalVars.styles[styleName] = strokes.colors;
-      result.strokes = styleName;
-      if (strokes.strokeWeight) result.strokeWeight = strokes.strokeWeight;
-      if (strokes.strokeDashes) result.strokeDashes = strokes.strokeDashes;
-      if (strokes.strokeWeights) result.strokeWeights = strokes.strokeWeights;
-    } else {
-      result.strokes = findOrCreateVar(context.globalVars, strokes, "stroke");
-    }
+    result.strokes = registerStyle(node, context, strokes.colors, ["stroke", "strokes"], "fill");
+    if (strokes.strokeWeight) result.strokeWeight = strokes.strokeWeight;
+    if (strokes.strokeDashes) result.strokeDashes = strokes.strokeDashes;
+    if (strokes.strokeWeights) result.strokeWeights = strokes.strokeWeights;
   }
 
   // effects
   const effects = buildSimplifiedEffects(node);
   if (Object.keys(effects).length) {
-    const styleName = getStyleName(node, context, ["effect", "effects"]);
-    if (styleName) {
-      // Effects styles store only the effect values
-      context.globalVars.styles[styleName] = effects;
-      result.effects = styleName;
-    } else {
-      result.effects = findOrCreateVar(context.globalVars, effects, "effect");
-    }
+    result.effects = registerStyle(node, context, effects, ["effect", "effects"], "effect");
   }
 
   // opacity
@@ -168,24 +164,38 @@ export const componentExtractor: ExtractorFn = (node, result, _context) => {
   }
 };
 
+type StyleMatch = { name: string; id: string };
+
 // Helper to fetch a Figma style name for specific style keys on a node
-function getStyleName(
+function getStyleMatch(
   node: FigmaDocumentNode,
   context: TraversalContext,
   keys: string[],
-): string | undefined {
+): StyleMatch | undefined {
   if (!hasValue("styles", node)) return undefined;
   const styleMap = node.styles as Record<string, string>;
   for (const key of keys) {
     const styleId = styleMap[key];
     if (styleId) {
       const meta = context.globalVars.extraStyles?.[styleId];
-      if (meta?.name) return meta.name;
+      if (meta?.name) return { name: meta.name, id: styleId };
     }
   }
   return undefined;
 }
 
+function resolveStyleKey(
+  context: TraversalContext,
+  styleMatch: StyleMatch,
+  value: StyleTypes,
+): string {
+  const existing = context.globalVars.styles[styleMatch.name];
+  if (!existing) return styleMatch.name;
+  if (JSON.stringify(existing) === JSON.stringify(value)) return styleMatch.name;
+
+  return `${styleMatch.name} (${styleMatch.id})`;
+}
+
 // -------------------- CONVENIENCE COMBINATIONS --------------------
 
 /**

src/tests/tree-walker.test.ts

@@ -2,8 +2,9 @@ import { describe, expect, it } from "vitest";
 import { extractFromDesign } from "~/extractors/node-walker.js";
 import { allExtractors, collapseSvgContainers } from "~/extractors/built-in.js";
 import { simplifyRawFigmaObject } from "~/extractors/design-extractor.js";
-import type { GetFileResponse } from "@figma/rest-api-spec";
+import type { GetFileResponse, Style } from "@figma/rest-api-spec";
 import type { Node as FigmaNode } from "@figma/rest-api-spec";
+import type { GlobalVars } from "~/extractors/types.js";
 
 // Minimal Figma node factory — only the fields the walker actually reads.
 // The Figma types are deeply discriminated unions; we cast through unknown
@@ -120,6 +121,77 @@ describe("extractFromDesign", () => {
     const fillEntries = Object.entries(globalVars.styles).filter(([key]) => key.startsWith("fill"));
     expect(fillEntries).toHaveLength(1);
   });
+
+  it("deduplicates identical colors used as both fill and stroke", async () => {
+    const sharedColor = [{ type: "SOLID", color: { r: 1, g: 0, b: 0, a: 1 }, visible: true }];
+
+    // Stroke node first — if strokes used a different prefix, the var would
+    // be named stroke_* and the fill would reuse it under the wrong prefix.
+    const strokeNode = makeNode({
+      id: "8:1",
+      name: "A",
+      type: "FRAME",
+      strokes: sharedColor,
+      strokeWeight: 1,
+    });
+    const fillNode = makeNode({ id: "8:2", name: "B", type: "FRAME", fills: sharedColor });
+
+    const { nodes, globalVars } = await extractFromDesign([strokeNode, fillNode], allExtractors);
+
+    expect(nodes[0].strokes).toBeDefined();
+    expect(nodes[1].fills).toBeDefined();
+    expect(nodes[0].strokes).toBe(nodes[1].fills);
+
+    // The shared var should use the fill prefix since stroke colors are
+    // structurally identical to fill colors in Figma (both are FILL-type styles).
+    const colorEntries = Object.entries(globalVars.styles).filter(
+      ([, value]) => JSON.stringify(value) === JSON.stringify(["#FF0000"]),
+    );
+    expect(colorEntries).toHaveLength(1);
+    expect(colorEntries[0][0]).toMatch(/^fill_/);
+  });
+
+  it("disambiguates named styles when style names collide", async () => {
+    const nodeA = makeNode({
+      id: "7:1",
+      name: "Text A",
+      type: "TEXT",
+      characters: "Hello",
+      style: { fontFamily: "Inter", fontWeight: 400, fontSize: 12 },
+      styles: { text: "13:77" },
+    });
+
+    const nodeB = makeNode({
+      id: "7:2",
+      name: "Text B",
+      type: "TEXT",
+      characters: "World",
+      style: { fontFamily: "Inter", fontWeight: 600, fontSize: 14 },
+      styles: { text: "161:300" },
+    });
+
+    const extraStyles: Record<string, Style> = {
+      "13:77": { name: "Heading / Large" } as Style,
+      "161:300": { name: "Heading / Large" } as Style,
+    };
+
+    const globalVars = { styles: {}, extraStyles } as GlobalVars;
+
+    const { nodes, globalVars: resultVars } = await extractFromDesign(
+      [nodeA, nodeB],
+      allExtractors,
+      {},
+      globalVars,
+    );
+
+    expect(nodes[0].textStyle).toBe("Heading / Large");
+    expect(nodes[1].textStyle).toBe("Heading / Large (161:300)");
+
+    const styleKeys = Object.keys(resultVars.styles).filter((key) =>
+      key.startsWith("Heading / Large"),
+    );
+    expect(styleKeys).toHaveLength(2);
+  });
 });
 
 describe("collapseSvgContainers", () => {

src/transformers/style.ts

@@ -234,7 +234,11 @@ export function buildSimplifiedStrokes(
 ): SimplifiedStroke {
   let strokes: SimplifiedStroke = { colors: [] };
   if (hasValue("strokes", n) && Array.isArray(n.strokes) && n.strokes.length) {
-    strokes.colors = n.strokes.filter(isVisible).map((stroke) => parsePaint(stroke, hasChildren));
+    // Reverse to match CSS stacking order (Figma layers bottom-to-top, CSS top-to-bottom)
+    strokes.colors = n.strokes
+      .filter(isVisible)
+      .map((stroke) => parsePaint(stroke, hasChildren))
+      .reverse();
   }
 
   if (hasValue("strokeWeight", n) && typeof n.strokeWeight === "number" && n.strokeWeight > 0) {