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.

feat(core): extract design tokens from published styles + uses_token edges

gruming2073dd06de5e
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
new file mode 100644
index 00000000..2c8fcf9f
--- /dev/null
+++ b/understand-anything-plugin/packages/core/src/figma/__tests__/tokens.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { extractTokens } from "../parse/tokens";
+import type { FigmaDocument, FigmaStyles } from "../source/types";
+import type { GraphNode } from "../../types";
+
+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: [] },
+ ] },
+ ],
+ },
+};
+const styles: FigmaStyles = { meta: { styles: [{ key: "S_KEY", name: "color/brand-500", style_type: "FILL" }] } };
+const structural: GraphNode[] = [
+ { id: "component:2:1", type: "component", name: "Primary", summary: "Primary", tags: ["component"], complexity: "simple", figmaMeta: { fileKey: "ABC", nodeId: "2:1" } },
+];
+
+describe("extractTokens", () => {
+ const { nodes, edges } = extractTokens(doc, styles, structural, "ABC");
+ it("creates a token node per published style with tokenKind", () => {
+ const token = nodes.find((n) => n.type === "token");
+ expect(token).toBeTruthy();
+ expect(token!.figmaMeta?.tokenKind).toBe("color");
+ expect(token!.name).toBe("color/brand-500");
+ });
+ it("links consumers to tokens via uses_token", () => {
+ 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
new file mode 100644
index 00000000..648a83f6
--- /dev/null
+++ b/understand-anything-plugin/packages/core/src/figma/parse/tokens.ts
@@ -0,0 +1,61 @@
+import type { GraphNode, GraphEdge, FigmaMeta } from "../../types";
+import type { FigmaDocument, FigmaNode, FigmaStyles } from "../source/types";
+
+const STYLE_KIND: Record<string, NonNullable<FigmaMeta["tokenKind"]>> = {
+ FILL: "color", TEXT: "type", EFFECT: "effect", GRID: "grid",
+};
+
+function slug(s: string): string {
+ return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+export function extractTokens(
+ doc: FigmaDocument,
+ styles: FigmaStyles,
+ structuralNodes: GraphNode[],
+ fileKey: string,
+): { nodes: GraphNode[]; edges: GraphEdge[] } {
+ const nodes: GraphNode[] = [];
+ const edges: GraphEdge[] = [];
+ const tokenByStyleKey = new Map<string, string>();
+
+ // Only published styles/variables become token nodes (bounded set).
+ for (const s of styles.meta?.styles ?? []) {
+ const kind = STYLE_KIND[s.style_type] ?? "color";
+ const id = `token:${kind}:${slug(s.name)}`;
+ if (!tokenByStyleKey.has(s.key)) tokenByStyleKey.set(s.key, id);
+ if (!nodes.some((n) => n.id === id)) {
+ nodes.push({
+ id, type: "token", name: s.name, summary: s.name,
+ tags: ["token", kind], complexity: "simple",
+ figmaMeta: { fileKey, tokenKind: kind },
+ });
+ }
+ }
+
+ const graphIdByFigmaId = new Map<string, string>();
+ for (const n of structuralNodes) {
+ if (n.figmaMeta?.nodeId) graphIdByFigmaId.set(n.figmaMeta.nodeId, n.id);
+ }
+
+ const usesSeen = new Set<string>();
+ function walk(n: FigmaNode) {
+ const consumerId = graphIdByFigmaId.get(n.id);
+ if (consumerId && n.styles) {
+ for (const styleKey of Object.values(n.styles)) {
+ const tokenId = tokenByStyleKey.get(styleKey);
+ if (tokenId) {
+ const dedupe = `${consumerId}|${tokenId}`;
+ if (!usesSeen.has(dedupe)) {
+ usesSeen.add(dedupe);
+ edges.push({ source: consumerId, target: tokenId, type: "uses_token", direction: "forward", weight: 0.5 });
+ }
+ }
+ }
+ }
+ for (const c of n.children ?? []) walk(c);
+ }
+ walk(doc.document);
+
+ return { nodes, edges };
+}