pi-mono-figma 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # pi-mono-figma
 
-## Unreleased
+## 0.2.0
 
 ### Minor Changes
 
@@ -12,6 +12,25 @@
 - Updated tool descriptions, README, and skill guidance to prefer processed tools and keep raw JSON tools as debugging escape hatches.
 - Added response caps, truncation metadata, and next-step suggestions for summarized node output.
 
+### Added: Dev Mode parity helpers
+
+- Added golden fixture tests for Figma summarization and design-to-code helper behavior.
+- Added `figma_find_nodes_by_name` and `figma_find_nodes_by_text` for compact path-aware layer/text search.
+- Enriched `figma_get_implementation_context` with CSS layout, responsive, accessibility, design token, framework, and starter snippet hints.
+- Added `figma_extract_assets` for SVG/icon exports, node renders, image fill downloads, hashes, byte sizes, suggested names, and node-path manifests.
+- Added `figma_find_code_connect_mapping` for bounded local Code Connect/Figma reference discovery.
+- Added `figma_get_component_implementation_hints` for higher-level component implementation guidance.
+- Documented live selection parity as future plugin/bridge work rather than a REST baseline feature.
+
+## 0.1.2
+
+### Patch Changes
+
+### Fixed: package extension entrypoint
+
+- Added the package root `index.ts` extension entrypoint so pi can load the Figma tools from the published package manifest.
+- Documented the extension's benefits over Figma MCP in the package README.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -2,16 +2,33 @@
 
 A pi extension and skill package that exposes native Figma tools for design exploration and design-to-code workflows. The default tools return compact, LLM-ready design context instead of raw Figma JSON.
 
+## Benefits over Figma MCP
+
+This package is Pi-native and uses Figma's REST API directly, with tools designed specifically for LLM-friendly design exploration and design-to-code workflows.
+
+- **No hosted Figma MCP quota path:** the extension calls Figma's REST API directly instead of using a hosted Claude/Figma connector quota path. It is still subject to Figma API limits, and the client smooths calls with a fixed 1s limiter plus a 5-minute TTL cache.
+- **Better LLM-shaped output:** `figma_get_node_summary`, `figma_explain_node`, and `figma_get_implementation_context` avoid raw Figma JSON by default. They cap depth, skip hidden nodes, vector internals, and component internals unless requested, and return `metadata.nextSteps` when follow-up inspection would help.
+- **Design-to-code specialization:** `figma_get_implementation_context` extracts fields, buttons, layout measurements, typography, colors, spacing, CSS/flex/grid hints, responsive guidance, accessibility hints, design tokens, assets, and optional framework starter snippets instead of simply relaying generic server output.
+- **Safer local auth UX:** `figma_configure_auth` uses masked local prompting and stores the token in Pi auth storage. The model never sees the token.
+- **Good raw escape hatches:** raw `figma_get_file` and `figma_get_nodes` tools are available for debugging, while tool descriptions steer agents toward processed tools first.
+- **Local asset handling:** `figma_render_nodes` can download rendered images to an OS temp directory by default, while `figma_extract_assets` returns a manifest for SVG icons, node renders, and image fills with node paths, hashes, byte sizes, and suggested names. Persistent project directories are used only when `outputDir` is explicitly provided.
+- **Broader inspection surface:** styles, variables, components, component sets, component search, metadata, text extraction, rendering, summaries, explanations, and implementation context are exposed as separate native tools.
+
 ## Tools
 
 ### Processed, LLM-ready tools (preferred)
 
 - `figma_parse_url` — parse a Figma URL into `fileKey` and `nodeId`.
-- `figma_render_nodes` — render node image URLs and optionally download assets locally. Downloads use an OS temp directory by default unless `outputDir` is provided.
+- `figma_find_nodes_by_name` — search layer/node names in a file or subtree and return compact path-aware matches.
+- `figma_find_nodes_by_text` — search visible text in a file or subtree and return matches with nearest parent context.
+- `figma_render_nodes` — render node image URLs and optionally download assets locally. Downloads use an OS temp directory by default unless the user explicitly provides `outputDir`.
 - `figma_get_node_summary` — fetch a compact structured summary of a node: name, type, size, layout, spacing, visual style, visible text, component properties, and shallow child hierarchy.
 - `figma_extract_text` — return visible text nodes only.
 - `figma_explain_node` — explain a node in Markdown using summary, visible text, hierarchy, and optional rendered asset.
-- `figma_get_implementation_context` — return coding-ready design context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, assets, and component hierarchy.
+- `figma_get_implementation_context` — return coding-ready design context: purpose, sections, fields/buttons, measurements, typography, colors, spacing, CSS layout, responsive hints, accessibility hints, design token resolution, assets, component hierarchy, and optional snippets.
+- `figma_extract_assets` — extract SVG/icon exports, node renders, and image fills into a node-path manifest with hashes and local paths.
+- `figma_find_code_connect_mapping` — scan the current repo for Code Connect files, `figma.connect(...)`, Figma URLs/node IDs, and component key references.
+- `figma_get_component_implementation_hints` — combine summary, implementation context, variants/properties, tokens, assets, accessibility, optional Code Connect matches, and starter snippets.
 - `figma_get_design_context` — fetch compact file context. With `nodeId`, returns target node summary plus location/sibling context; without `nodeId`, returns canvases and top-level frames only.
 - `figma_get_node_metadata` — fetch compact spatial/layout metadata for one or more nodes.
 - `figma_get_styles` — fetch named styles.
@@ -42,17 +59,61 @@ figma_explain_node
 
 ```text
 figma_parse_url
+figma_find_nodes_by_name or figma_find_nodes_by_text when the URL does not include the exact target node
 figma_render_nodes
-figma_get_implementation_context
+figma_get_implementation_context with framework/styling when useful
 figma_get_node_summary for specific subnodes if needed
 ```
 
+Example implementation-context options:
+
+```ts
+{
+  framework: "react",
+  styling: "styled-components",
+  resolveTokens: true,
+  includeCodeSnippets: true
+}
+```
+
+### Finding a frame or layer before implementation
+
+```text
+figma_get_design_context
+figma_find_nodes_by_name query="Checkout" nodeId=<top-level-frame-if-known>
+figma_find_nodes_by_text query="Submit" nodeId=<candidate-frame>
+```
+
+### Extracting assets for a frame
+
+```text
+figma_extract_assets assetTypes=["svgIcons", "nodeRenders", "imageFills"]
+```
+
+Use returned `nodePath`, `suggestedName`, `sha256`, and `bytes` to map downloaded files back to Figma layers and avoid duplicate assets.
+Omit `outputDir` unless the user asked for files to be saved in a persistent project location; the default is an OS temp directory.
+
+### Finding local Code Connect mappings
+
+```text
+figma_find_code_connect_mapping fileKey=<fileKey> nodeId=<nodeId>
+figma_get_component_implementation_hints includeCodeConnect=true framework="react"
+```
+
+Use Code Connect matches only as local implementation hints; no Figma write access is used.
+
 ### Debugging raw Figma data
 
 ```text
 figma_get_nodes
 ```
 
+## Live selection boundary
+
+This package is REST/API-based and read-only. It can inspect files, nodes, styles, variables, renders, and local repository mappings when you provide a file key/node ID, but it does **not** currently know the live selection in an open Figma desktop/browser session.
+
+True Dev Mode-style live selection parity would require a separate local bridge or Figma plugin that captures the current selection and exposes selected file/node IDs to Pi. See [`docs/live-selection-bridge.md`](docs/live-selection-bridge.md) for a future architecture sketch.
+
 ## Processed node options
 
 Processed tools fetch nodes with compact depth limits and summarize safely:
@@ -63,6 +124,10 @@ Processed tools fetch nodes with compact depth limits and summarize safely:
   includeHidden?: boolean; // default false
   includeVectors?: boolean; // default false
   includeComponentInternals?: boolean; // default false
+  framework?: "react" | "html" | "vue" | "angular" | "react-native";
+  styling?: "css" | "css-modules" | "styled-components" | "tailwind" | "inline";
+  resolveTokens?: boolean; // implementation context, default true
+  includeCodeSnippets?: boolean; // implementation context, default false
 }
 ```
 

package/__tests__/code-connect.test.ts

@@ -0,0 +1,32 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findCodeConnectMapping } from "../src/code-connect.js";
+
+test("findCodeConnectMapping discovers figma.connect, URLs, and node IDs", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await writeFile(join(root, "Button.figma.tsx"), "figma.connect(Button, 'https://www.figma.com/design/FILE123/Name?node-id=1-2')\n");
+	await writeFile(join(root, "README.md"), "component key COMPONENT123\n");
+	const result = await findCodeConnectMapping({ cwd: root, fileKey: "FILE123", nodeId: "1:2", componentKey: "COMPONENT123" });
+	assert.ok(result.matches.some((match) => match.kind === "figma-connect"));
+	assert.ok(result.matches.some((match) => match.kind === "figma-file-reference"));
+	assert.ok(result.matches.some((match) => match.kind === "component-key-reference"));
+});
+
+test("findCodeConnectMapping ignores node_modules and enforces caps", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await mkdir(join(root, "node_modules"));
+	await writeFile(join(root, "node_modules", "Ignored.ts"), "figma.connect(Ignored)\n");
+	await writeFile(join(root, "One.ts"), "figma.connect(One)\nfigma.connect(Two)\n");
+	const result = await findCodeConnectMapping({ cwd: root, fileKey: "FILE123", maxMatches: 1 });
+	assert.equal(result.matches.length, 1);
+	assert.equal(result.matches[0]?.path, "One.ts");
+	assert.equal(result.metadata.truncated, true);
+});
+
+test("findCodeConnectMapping rejects rootDir outside cwd", async () => {
+	const root = await mkdtemp(join(tmpdir(), "figma-code-connect-"));
+	await assert.rejects(() => findCodeConnectMapping({ cwd: root, rootDir: "/", fileKey: "FILE123" }), /rootDir/);
+});

package/__tests__/figma-assets.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { collectAssetCandidates, formatFromPath, safeFilename, sha256 } from "../src/figma-assets.js";
+
+const assetTree = {
+	id: "10:1",
+	name: "Hero Card",
+	type: "FRAME",
+	absoluteBoundingBox: { width: 320, height: 200 },
+	fills: [{ type: "IMAGE", imageRef: "abc123", scaleMode: "FILL" }],
+	children: [
+		{ id: "10:2", name: "Close icon", type: "VECTOR", absoluteBoundingBox: { width: 16, height: 16 } },
+		{ id: "10:3", name: "Logo Mark", type: "FRAME", absoluteBoundingBox: { width: 32, height: 32 } },
+		{ id: "10:4", name: "Hidden asset", type: "VECTOR", visible: false, absoluteBoundingBox: { width: 16, height: 16 } },
+	],
+};
+
+test("collectAssetCandidates detects icons, node renders, image fills, and paths", () => {
+	const result = collectAssetCandidates(assetTree, { assetTypes: ["svgIcons", "nodeRenders", "imageFills"] });
+	assert.ok(result.assets.some((asset) => asset.kind === "svgIcon" && asset.nodePath === "Hero Card > Close icon"));
+	assert.ok(result.assets.some((asset) => asset.kind === "nodeRender" && asset.nodePath === "Hero Card"));
+	assert.ok(result.assets.some((asset) => asset.kind === "imageFill" && asset.imageRef === "abc123"));
+	assert.equal(result.assets.some((asset) => asset.nodeName === "Hidden asset"), false);
+});
+
+test("collectAssetCandidates supports hidden nodes and caps results", () => {
+	const result = collectAssetCandidates(assetTree, { includeHidden: true, maxAssets: 1 });
+	assert.equal(result.assets.length, 1);
+	assert.equal(result.metadata.truncated, true);
+	assert.ok(result.metadata.truncatedReasons.some((reason) => reason.includes("maxAssets")));
+});
+
+test("asset helper utilities normalize names, hashes, and formats", () => {
+	assert.equal(safeFilename("Close Icon / Primary"), "close-icon-primary");
+	assert.equal(sha256("abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+	assert.equal(formatFromPath("/tmp/icon.svg"), "svg");
+	assert.equal(formatFromPath("/tmp/photo.jpeg"), "jpg");
+});

package/__tests__/figma-component-hints.test.ts

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildComponentImplementationHints } from "../src/figma-component-hints.js";
+import { getImplementationContext, summarizeNode } from "../src/figma-summarizer.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("buildComponentImplementationHints combines summary, variants, accessibility, tokens, and snippets", async () => {
+	const node = await fixture("component-instance.json");
+	const summary = summarizeNode(node, { depth: 3 });
+	const context = getImplementationContext(node, { framework: "react", includeCodeSnippets: true });
+	const hints = buildComponentImplementationHints(summary, context, { framework: "react", includeSnippet: true, includeCodeConnect: true }, { rootDir: "/repo", matches: [], metadata: { truncated: false, truncatedReasons: [], nextSteps: [] } });
+	assert.equal(hints.componentName, "SettingsModal");
+	assert.ok(hints.suggestedProps.some((prop) => prop.name === "children"));
+	assert.ok(hints.statesAndVariants.some((variant) => variant.name === "State"));
+	assert.ok(hints.accessibilityRequirements.some((hint) => hint.role === "dialog" || hint.role === "button"));
+	assert.match(String(hints.frameworkHints?.snippet), /export function SettingsModal/);
+	assert.ok(hints.metadata.nextSteps.some((step) => step.includes("Code Connect")));
+});

package/__tests__/figma-implementation-layout.test.ts

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { getImplementationContext } from "../src/figma-summarizer.js";
+import { buildCssLayoutHints, buildResponsiveHints } from "../src/figma-implementation.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("buildCssLayoutHints maps auto-layout to CSS flex and grid hints", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const hints = buildCssLayoutHints(node);
+	assert.deepEqual((hints.css as Record<string, unknown>).display, "flex");
+	assert.equal((hints.css as Record<string, unknown>).flexDirection, "column");
+	assert.equal((hints.css as Record<string, unknown>).gap, "16px");
+	assert.equal((hints.css as Record<string, unknown>).padding, "20px 24px 20px 24px");
+	assert.ok(Array.isArray((hints.css as Record<string, unknown>).layoutGrids));
+});
+
+test("buildResponsiveHints recommends fill, hug, fixed, and wrap behavior", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const hints = buildResponsiveHints(node);
+	assert.ok(hints.some((hint) => String(hint.name) === "Header Row" && (hint.recommendations as string[]).some((rec) => rec.includes("width: 100%"))));
+	assert.ok(hints.some((hint) => String(hint.name) === "Dashboard Card" && (hint.recommendations as string[]).some((rec) => rec.includes("Fixed width"))));
+});
+
+test("implementation context includes layout, responsive, accessibility, tokens, and snippets", async () => {
+	const node = await fixture("variables-and-styles.json");
+	const context = getImplementationContext(node, {
+		framework: "react",
+		styling: "styled-components",
+		includeCodeSnippets: true,
+		tokenMap: {
+			styles: { "S:primary-fill": { name: "Color/Primary", type: "FILL" }, "S:text-button": { name: "Typography/Button", type: "TEXT" } },
+			variables: { "VariableID:color-primary": { name: "color.primary" }, "VariableID:text-on-primary": { name: "color.onPrimary" }, "VariableID:radius-md": { name: "radius.md" } },
+			collections: {},
+			warnings: [],
+		},
+	});
+	assert.ok(context.cssLayout);
+	assert.ok(context.accessibility?.some((hint) => hint.role === "button"));
+	assert.ok((context.designTokens?.resolved as Array<Record<string, unknown>>).some((token) => token.name === "Color/Primary"));
+	assert.equal(context.frameworkHints?.framework, "react");
+	assert.match(String(context.frameworkHints?.snippet), /styled\.section/);
+});

package/__tests__/figma-search.test.ts

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findNodesByName, findNodesByText } from "../src/figma-search.js";
+
+async function fixture(name: string): Promise<unknown> {
+	return JSON.parse(await readFile(join(import.meta.dirname, "fixtures", name), "utf8"));
+}
+
+test("findNodesByName supports partial, exact, and case-sensitive matching", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	assert.deepEqual(findNodesByName(node, { query: "button" }).matches.map((match) => match.name), ["Save button", "Button label"]);
+	assert.equal(findNodesByName(node, { query: "save button", exact: true }).matches.length, 1);
+	assert.equal(findNodesByName(node, { query: "save button", exact: true, caseSensitive: true }).matches.length, 0);
+});
+
+test("findNodesByText returns path and parent context", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const result = findNodesByText(node, { query: "Water risk" });
+	assert.equal(result.matches[0]?.text, "Water risk summary");
+	assert.equal(result.matches[0]?.parent?.name, "Header Row");
+	assert.match(result.matches[0]?.path ?? "", /Dashboard Card > Header Row > Title/);
+});
+
+test("findNodesByName respects hidden and vector filters", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	assert.equal(findNodesByName(node, { query: "Hidden" }).matches.length, 0);
+	assert.equal(findNodesByName(node, { query: "Hidden", includeHidden: true }).matches.length, 1);
+	assert.equal(findNodesByName(node, { query: "icon" }).matches.length, 0);
+	assert.equal(findNodesByName(node, { query: "icon", includeVectors: true }).matches.length, 1);
+});
+
+test("findNodesByText searches collapsed instance text but not vector internals", async () => {
+	const node = await fixture("component-instance.json");
+	const result = findNodesByText(node, { query: "Continue" });
+	assert.equal(result.matches.length, 1);
+	assert.equal(result.matches[0]?.parent?.name, "Primary CTA instance");
+	assert.ok(result.metadata.nextSteps.some((step) => step.includes("includeComponentInternals")));
+});
+
+test("findNodesByName enforces depth and result caps", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const depthLimited = findNodesByName(node, { query: "Title", depth: 1 });
+	assert.equal(depthLimited.matches.length, 0);
+	assert.ok(depthLimited.metadata.truncatedReasons.some((reason) => reason.includes("depth limit")));
+
+	const capped = findNodesByName(node, { query: "", maxResults: 1 });
+	assert.equal(capped.matches.length, 1);
+	assert.ok(capped.metadata.truncatedReasons.some((reason) => reason.includes("maxResults")));
+});

package/__tests__/figma-summarizer.test.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { extractVisibleText, getImplementationContext, summarizeNode } from "../src/figma-summarizer.js";
+
+async function fixture(name: string): Promise<unknown> {
+	const path = join(import.meta.dirname, "fixtures", name);
+	return JSON.parse(await readFile(path, "utf8"));
+}
+
+test("summarizeNode excludes hidden nodes and vector internals by default", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	const summary = summarizeNode(node, { depth: 3 });
+	assert.deepEqual(summary.visibleText, ["Visible copy"]);
+	assert.equal(summary.children?.some((child) => child.name === "Hidden text"), false);
+	assert.equal(summary.children?.some((child) => child.name === "Search icon"), false);
+});
+
+test("summarizeNode can include hidden nodes and vectors when requested", async () => {
+	const node = await fixture("hidden-and-vectors.json");
+	const summary = summarizeNode(node, { depth: 3, includeHidden: true, includeVectors: true });
+	assert.deepEqual(summary.visibleText, ["Visible copy", "Hidden copy"]);
+	assert.ok(summary.children?.some((child) => child.name === "Hidden text"));
+	assert.ok(summary.children?.some((child) => child.name === "Search icon"));
+});
+
+test("component instances collapse structural internals while retaining useful text", async () => {
+	const node = await fixture("component-instance.json");
+	const summary = summarizeNode(node, { depth: 2 });
+	const instance = summary.children?.find((child) => child.type === "INSTANCE");
+	assert.equal(instance?.children, undefined);
+	assert.deepEqual(instance?.text, ["Continue"]);
+	assert.ok(summary.metadata?.truncatedReasons.some((reason) => reason.includes("Collapsed component instance")));
+});
+
+test("extractVisibleText returns capped text metadata", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const result = extractVisibleText(node, { maxVisibleText: 1 });
+	assert.deepEqual(result.texts, ["Water risk summary"]);
+	assert.equal(result.metadata.truncated, true);
+	assert.ok(result.metadata.nextSteps.includes("Use figma_extract_text on a narrower child node to see more text."));
+});
+
+test("getImplementationContext deterministically extracts typography colors spacing and controls", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const context = getImplementationContext(node, { depth: 3 });
+	assert.match(context.purpose, /Water risk summary/);
+	assert.equal(context.sections.length, 2);
+	assert.ok(context.buttons.some((button) => button.name === "Save button"));
+	assert.ok(context.typography.some((entry) => entry.fontFamily === "Inter" && entry.fontSize === 18));
+	assert.ok(context.colors.some((entry) => entry.hex === "#ffffff"));
+	assert.ok(context.spacing.some((entry) => entry.itemSpacing === 16));
+});
+
+test("depth and children caps produce truncation metadata", async () => {
+	const node = await fixture("complex-auto-layout.json");
+	const depthLimited = summarizeNode(node, { depth: 1 });
+	assert.equal(depthLimited.metadata?.truncated, true);
+	assert.ok(depthLimited.metadata?.nextSteps.some((step) => step.includes("depth 2")));
+
+	const childLimited = summarizeNode(node, { depth: 2, maxChildren: 1 });
+	assert.equal(childLimited.children?.length, 1);
+	assert.ok(childLimited.metadata?.truncatedReasons.some((reason) => reason.includes("Capped children")));
+});

package/__tests__/fixtures/complex-auto-layout.json

@@ -0,0 +1,115 @@
+{
+  "id": "1:1",
+  "name": "Dashboard Card",
+  "type": "FRAME",
+  "visible": true,
+  "absoluteBoundingBox": { "width": 360, "height": 240 },
+  "layoutMode": "VERTICAL",
+  "primaryAxisAlignItems": "MIN",
+  "counterAxisAlignItems": "STRETCH",
+  "layoutWrap": "NO_WRAP",
+  "layoutSizingHorizontal": "FIXED",
+  "layoutSizingVertical": "HUG",
+  "itemSpacing": 16,
+  "paddingLeft": 24,
+  "paddingRight": 24,
+  "paddingTop": 20,
+  "paddingBottom": 20,
+  "layoutGrids": [
+    { "pattern": "COLUMNS", "count": 12, "gutterSize": 16, "sectionSize": 56 }
+  ],
+  "fills": [
+    { "type": "SOLID", "color": { "r": 1, "g": 1, "b": 1 }, "opacity": 1 }
+  ],
+  "strokes": [
+    {
+      "type": "SOLID",
+      "color": { "r": 0.8, "g": 0.84, "b": 0.9 },
+      "opacity": 1
+    }
+  ],
+  "cornerRadius": 12,
+  "children": [
+    {
+      "id": "1:2",
+      "name": "Header Row",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 312, "height": 40 },
+      "layoutMode": "HORIZONTAL",
+      "primaryAxisAlignItems": "SPACE_BETWEEN",
+      "counterAxisAlignItems": "CENTER",
+      "layoutSizingHorizontal": "FILL",
+      "layoutSizingVertical": "HUG",
+      "itemSpacing": 8,
+      "children": [
+        {
+          "id": "1:3",
+          "name": "Title",
+          "type": "TEXT",
+          "absoluteBoundingBox": { "width": 140, "height": 24 },
+          "characters": "Water risk summary",
+          "style": {
+            "fontFamily": "Inter",
+            "fontSize": 18,
+            "fontWeight": 700,
+            "lineHeightPx": 24
+          },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 0.05, "g": 0.1, "b": 0.18 },
+              "opacity": 1
+            }
+          ]
+        },
+        {
+          "id": "1:4",
+          "name": "More icon",
+          "type": "VECTOR",
+          "absoluteBoundingBox": { "width": 20, "height": 20 },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 0.3, "g": 0.35, "b": 0.44 },
+              "opacity": 1
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "1:5",
+      "name": "Save button",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 120, "height": 40 },
+      "layoutMode": "HORIZONTAL",
+      "primaryAxisAlignItems": "CENTER",
+      "counterAxisAlignItems": "CENTER",
+      "itemSpacing": 8,
+      "fills": [
+        {
+          "type": "SOLID",
+          "color": { "r": 0.05, "g": 0.42, "b": 0.95 },
+          "opacity": 1
+        }
+      ],
+      "children": [
+        {
+          "id": "1:6",
+          "name": "Button label",
+          "type": "TEXT",
+          "characters": "Save",
+          "absoluteBoundingBox": { "width": 34, "height": 20 },
+          "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 },
+          "fills": [
+            {
+              "type": "SOLID",
+              "color": { "r": 1, "g": 1, "b": 1 },
+              "opacity": 1
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__tests__/fixtures/component-instance.json

@@ -0,0 +1,50 @@
+{
+  "id": "2:1",
+  "name": "Settings modal",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 480, "height": 360 },
+  "children": [
+    {
+      "id": "2:2",
+      "name": "Primary CTA instance",
+      "type": "INSTANCE",
+      "componentId": "99:1",
+      "componentSetId": "99:0",
+      "componentProperties": {
+        "State": { "type": "VARIANT", "value": "Default" },
+        "Disabled": { "type": "BOOLEAN", "value": false }
+      },
+      "absoluteBoundingBox": { "width": 180, "height": 44 },
+      "children": [
+        {
+          "id": "2:3",
+          "name": "Hidden icon",
+          "type": "VECTOR",
+          "absoluteBoundingBox": { "width": 16, "height": 16 }
+        },
+        {
+          "id": "2:4",
+          "name": "Label",
+          "type": "TEXT",
+          "characters": "Continue",
+          "absoluteBoundingBox": { "width": 70, "height": 20 },
+          "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 }
+        }
+      ]
+    },
+    {
+      "id": "2:5",
+      "name": "Email input field",
+      "type": "FRAME",
+      "absoluteBoundingBox": { "width": 300, "height": 48 },
+      "children": [
+        {
+          "id": "2:6",
+          "name": "Placeholder",
+          "type": "TEXT",
+          "characters": "Email address"
+        }
+      ]
+    }
+  ]
+}

package/__tests__/fixtures/hidden-and-vectors.json

@@ -0,0 +1,28 @@
+{
+  "id": "4:1",
+  "name": "Visibility Fixture",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 200, "height": 120 },
+  "children": [
+    {
+      "id": "4:2",
+      "name": "Visible text",
+      "type": "TEXT",
+      "characters": "Visible copy"
+    },
+    {
+      "id": "4:3",
+      "name": "Hidden text",
+      "type": "TEXT",
+      "visible": false,
+      "characters": "Hidden copy"
+    },
+    {
+      "id": "4:4",
+      "name": "Search icon",
+      "type": "VECTOR",
+      "absoluteBoundingBox": { "width": 16, "height": 16 },
+      "children": [{ "id": "4:5", "name": "Vector point", "type": "VECTOR" }]
+    }
+  ]
+}

package/__tests__/fixtures/variables-and-styles.json

@@ -0,0 +1,40 @@
+{
+  "id": "3:1",
+  "name": "Tokenized Button",
+  "type": "FRAME",
+  "absoluteBoundingBox": { "width": 160, "height": 48 },
+  "layoutMode": "HORIZONTAL",
+  "primaryAxisAlignItems": "CENTER",
+  "counterAxisAlignItems": "CENTER",
+  "styles": { "fill": "S:primary-fill", "stroke": "S:border-default" },
+  "boundVariables": {
+    "fills": [{ "type": "VARIABLE_ALIAS", "id": "VariableID:color-primary" }],
+    "cornerRadius": { "type": "VARIABLE_ALIAS", "id": "VariableID:radius-md" }
+  },
+  "fills": [
+    {
+      "type": "SOLID",
+      "color": { "r": 0.02, "g": 0.35, "b": 0.9 },
+      "opacity": 1
+    }
+  ],
+  "cornerRadius": 8,
+  "children": [
+    {
+      "id": "3:2",
+      "name": "Label",
+      "type": "TEXT",
+      "characters": "Submit",
+      "style": { "fontFamily": "Inter", "fontSize": 14, "fontWeight": 600 },
+      "styles": { "text": "S:text-button" },
+      "boundVariables": {
+        "fills": [
+          { "type": "VARIABLE_ALIAS", "id": "VariableID:text-on-primary" }
+        ]
+      },
+      "fills": [
+        { "type": "SOLID", "color": { "r": 1, "g": 1, "b": 1 }, "opacity": 1 }
+      ]
+    }
+  ]
+}