Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

fix(figma): bridge file-local style ids to published keys for uses_token edges

Lum11043b50a557dcda
diff --git a/understand-anything-plugin/packages/core/src/figma/__tests__/tokens.test.ts b/understand-anything-plugin/packages/core/src/figma/__tests__/tokens.test.ts
index 37835264..dd2f58d1 100644
--- a/understand-anything-plugin/packages/core/src/figma/__tests__/tokens.test.ts
+++ b/understand-anything-plugin/packages/core/src/figma/__tests__/tokens.test.ts
@@ -3,15 +3,19 @@ import { extractTokens } from "../parse/tokens";
import type { FigmaDocument, FigmaStyles } from "../source/types";
import type { GraphNode } from "../../types";
+// Mirrors the real API shape: node.styles values are file-local style ids
+// ("100:1") that resolve through the document's top-level styles map to the
+// published key ("S_KEY") that /files/:key/styles reports.
const doc: FigmaDocument = {
name: "MyApp",
document: {
id: "0:0", name: "Document", type: "DOCUMENT", children: [
{ id: "1:9", name: "Components", type: "CANVAS", children: [
- { id: "2:1", name: "Primary", type: "COMPONENT", styles: { fill: "S_KEY" }, children: [] },
+ { id: "2:1", name: "Primary", type: "COMPONENT", styles: { fill: "100:1" }, children: [] },
] },
],
},
+ styles: { "100:1": { key: "S_KEY", name: "color/brand-500", styleType: "FILL" } },
};
const styles: FigmaStyles = { meta: { styles: [{ key: "S_KEY", name: "color/brand-500", style_type: "FILL" }] } };
const structural: GraphNode[] = [
@@ -26,7 +30,7 @@ describe("extractTokens", () => {
expect(token!.figmaMeta?.tokenKind).toBe("color");
expect(token!.name).toBe("color/brand-500");
});
- it("links consumers to tokens via uses_token", () => {
+ it("links consumers to tokens by bridging local style ids to published keys", () => {
const token = nodes.find((n) => n.type === "token")!;
expect(edges).toEqual(expect.arrayContaining([
expect.objectContaining({ source: "component:2:1", target: token.id, type: "uses_token" }),
@@ -44,11 +48,12 @@ describe("extractTokens — nested styled layers", () => {
id: "0:0", name: "Document", type: "DOCUMENT", children: [
{ id: "1:0", name: "Home", type: "CANVAS", children: [
{ id: "10:0", name: "Home Screen", type: "FRAME", children: [
- { id: "11:0", name: "Title", type: "TEXT", styles: { text: "T_KEY" }, children: [] },
+ { id: "11:0", name: "Title", type: "TEXT", styles: { text: "200:1" }, children: [] },
] },
] },
],
},
+ styles: { "200:1": { key: "T_KEY", name: "type/heading", styleType: "TEXT" } },
};
const nestedStyles: FigmaStyles = { meta: { styles: [{ key: "T_KEY", name: "type/heading", style_type: "TEXT" }] } };
const nestedStructural: GraphNode[] = [
@@ -64,3 +69,26 @@ describe("extractTokens — nested styled layers", () => {
]));
});
});
+
+describe("extractTokens — sources without a top-level styles map", () => {
+ // Offline/local sources may put published keys directly in node.styles;
+ // without doc.styles the value falls back to a direct key match.
+ const bareDoc: FigmaDocument = {
+ name: "MyApp",
+ document: {
+ id: "0:0", name: "Document", type: "DOCUMENT", children: [
+ { id: "1:9", name: "Components", type: "CANVAS", children: [
+ { id: "2:1", name: "Primary", type: "COMPONENT", styles: { fill: "S_KEY" }, children: [] },
+ ] },
+ ],
+ },
+ };
+
+ it("falls back to matching node style values directly against published keys", () => {
+ const { nodes, edges } = extractTokens(bareDoc, styles, structural, "ABC");
+ const token = nodes.find((n) => n.type === "token")!;
+ expect(edges).toEqual(expect.arrayContaining([
+ expect.objectContaining({ source: "component:2:1", target: token.id, type: "uses_token" }),
+ ]));
+ });
+});
diff --git a/understand-anything-plugin/packages/core/src/figma/parse/tokens.ts b/understand-anything-plugin/packages/core/src/figma/parse/tokens.ts
index 0f38c09f..23fc4bd9 100644
--- a/understand-anything-plugin/packages/core/src/figma/parse/tokens.ts
+++ b/understand-anything-plugin/packages/core/src/figma/parse/tokens.ts
@@ -47,7 +47,13 @@ export function extractTokens(
// relationships aren't dropped when the styled layer isn't itself a node.
const consumerId = graphIdByFigmaId.get(n.id) ?? nearestConsumerId;
if (consumerId && n.styles) {
- for (const styleKey of Object.values(n.styles)) {
+ for (const localStyleId of Object.values(n.styles)) {
+ // node.styles values are file-local style ids (e.g. "2:10") that
+ // index the document's top-level styles map, while token nodes are
+ // keyed by the global published key from /files/:key/styles. Bridge
+ // local id → published key; fall back to a direct match for sources
+ // that don't provide the top-level map.
+ const styleKey = doc.styles?.[localStyleId]?.key ?? localStyleId;
const tokenId = tokenByStyleKey.get(styleKey);
if (tokenId) {
const dedupe = `${consumerId}|${tokenId}`;
diff --git a/understand-anything-plugin/packages/core/src/figma/source/types.ts b/understand-anything-plugin/packages/core/src/figma/source/types.ts
index 665f267c..698c6090 100644
--- a/understand-anything-plugin/packages/core/src/figma/source/types.ts
+++ b/understand-anything-plugin/packages/core/src/figma/source/types.ts
@@ -5,7 +5,7 @@ export interface FigmaNode {
children?: FigmaNode[];
componentId?: string; // on INSTANCE → main component node id
absoluteBoundingBox?: { width: number; height: number } | null;
- styles?: Record<string, string>; // styleType (fill/text/effect/grid) → style key
+ styles?: Record<string, string>; // styleType (fill/text/effect/grid) → file-local style id, resolved via FigmaDocument.styles
transitionNodeID?: string | null; // prototype target node id
}
@@ -14,6 +14,7 @@ export interface FigmaDocument {
document: FigmaNode; // root (DOCUMENT) whose children are CANVAS (pages)
components?: Record<string, { key: string; name: string; componentSetId?: string }>;
componentSets?: Record<string, { key: string; name: string }>;
+ styles?: Record<string, { key: string; name?: string; styleType?: string }>; // file-local style id → published style; bridges node.styles to /files/:key/styles keys
version?: string; // Figma file version (changes on every edit)
lastModified?: string; // ISO timestamp
}