figma-console-mcp 1.29.1 → 1.30.0

package/README.md

@@ -8,7 +8,7 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, **debugging**, and **bidirectional token sync**.
 
-> **🆕 Shared Library Inspection (v1.29.0, patched v1.29.1):** Three new tools fill the gap between "I see a component key in search results" and "I can actually use it." `figma_get_library_component_by_key` resolves any component key to full property definitions + variant keys + visual specs — without needing the source library file's URL. `figma_get_library_variables` lists every variable from your subscribed libraries (no Enterprise plan required — uses the Plugin API path that works on Pro and Org). `figma_import_library_variable` brings a library token into the current file so it can be bound to nodes alongside the file's own variables. Works on every Figma plan. 106 tools total. **Patched v1.29.1:** `figma_get_design_system_kit` now reads variables on any plan via the bridge too — no more 403 for non-Enterprise users. [See what's new →](CHANGELOG.md#1291---2026-05-30)
+> **🆕 Native variable binding & typography (v1.30.0):** The structured write tools now handle the operations that used to force you into raw `figma_execute`. `figma_set_fills` / `figma_set_strokes` bind a fill or stroke to a color variable via a new `variableId` param (works on any Figma plan through the bridge — no Enterprise Variables API). `figma_set_text` gains `fontFamily` / `fontStyle` with space-insensitive normalization (`SemiBold` → `Semi Bold`) and graceful fallback. `figma_instantiate_component` now pre-loads instance fonts before text overrides (no more silently-skipped overrides) and reports failed overrides in a `warnings` array. Works on every Figma plan. [See what's new →](CHANGELOG.md#1300---2026-06-02)
 
 ## What is this?
 
@@ -808,9 +808,11 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.29.1 (Stable) - Production-ready with shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.30.0 (Stable) - Production-ready with native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.30.0** - Native variable binding + typography in the structured write tools, closing the Plugin API gaps that used to force raw `figma_execute`. `figma_set_fills` / `figma_set_strokes` accept a `variableId` to bind a fill/stroke to a color variable via `setBoundVariableForPaint` (any plan, via the bridge). `figma_set_text` gains `fontFamily` / `fontStyle` with space-insensitive normalization (`SemiBold` → `Semi Bold`) and graceful `Regular` fallback. `figma_instantiate_component` pre-loads instance text fonts before applying overrides (fixes silently-skipped text overrides on non-Regular weights) and returns a `warnings` array for failed overrides. Also fixes a mixed-font crash in `figma_set_text` and a `ui.html` relay that was dropping new message fields. No new tools; **plugin re-import required** (bridge `ui.html` + `code.js` changed). Validated live; 1185 tests passing.
+- [x] **v1.29.2** - Bug fix: `figma_generate_component_doc` now renders Figma component descriptions faithfully and reliably tags atomic-design level. Single-`#` headings in descriptions render as real sections (Usage Guidelines, Implementation Considerations, Accessibility Requirements, Content Configuration) instead of leaking as `- # Heading` list items; frontmatter `description` takes the first sentence instead of truncating on the word "Accessibility"; the generated Figma URL no longer doubles `?node-id=`; and the component's atomic level (atom/molecule/organism/template) is auto-detected via a single `ids=<node>` file request + divider walk-back, with no dependency on library publishing. No new tools; plugin re-import not required.
 - [x] **v1.29.1** - Bug fix: `figma_get_design_system_kit` now resolves variables bridge-first (Desktop Bridge / cloud relay → REST fallback) instead of calling the Enterprise-only Variables REST API directly. Non-Enterprise users no longer hit a 403 on the kit's token section when a bridge is connected, and a REST 403 now points the caller back to the bridge instead of dead-ending. 7 new tests, 1185 total passing. No new tools; plugin re-import not required.
 - [x] **v1.29.0** - Shared library inspection: three new tools close the gap between "I have a component key" and "I can actually use it." `figma_get_library_component_by_key` resolves any 40-char component key to full `componentPropertyDefinitions` + variants (with their published keys) + per-variant visual specs — without needing the source library file's URL. `figma_get_library_variables` lists library tokens via Plugin API (works on every Figma plan; the REST equivalent is Enterprise-only). `figma_import_library_variable` imports a library token to the current file so it can be bound to nodes. 27 new tests, 1178 total passing. Plugin re-import optional.
 - [x] **v1.28.1** - Bug fix patch surfacing from live-fire testing of the v1.28.0 formatters against multi-tier semantic-token design systems. Fixes: Tailwind v3 emitted empty `module.exports` for alias-only sets (now resolves alias chains to literal values); TypeScript module + JSON flat + JSON nested formatters emitted `"{alias.path}"` strings as literal values (now resolves); Tailwind v4 namespace-prefix doubling (`--color-theme-color-X` is now `--color-theme-X`). Adds `resolveAliasChain` public helper. 1151 tests still passing.

package/dist/cloudflare/core/design-code-tools.js

@@ -174,7 +174,7 @@ export function parseComponentDescription(description) {
     for (const line of lines) {
         const trimmed = line.trim();
         // Detect section headers: bold text (**Header**), markdown headers (## Header), or plain text exact matches
-        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|###?\s*)(.+?)(?:\*\*)?$/);
+        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|#{1,6}\s*)(.+?)(?:\*\*)?$/);
         const headerText = markdownHeaderMatch ? markdownHeaderMatch[1].trim().replace(/\*\*/g, "") : null;
         // Check if this is a Figma per-property documentation block (e.g., "Show Left Icon: True – Purpose")
         // These should be routed to "other" to avoid polluting content guidelines and accessibility sections
@@ -1380,7 +1380,47 @@ function buildParityInstruction(componentName, parityScore, counts, canonicalSou
 // ============================================================================
 // Documentation Section Generators
 // ============================================================================
-function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource) {
+/**
+ * Detect the atomic-design level (atom | molecule | organism | template) of a component
+ * by finding its Figma page and walking the ordered page list back to the nearest
+ * section-divider page (e.g. "ATOMS", "MOLECULES", "ORGANISMS"). Returns null when the
+ * file doesn't use atomic-design page sections or the page can't be resolved — callers
+ * then simply omit the `level` frontmatter. Best-effort and never throws.
+ */
+async function detectAtomicLevel(api, fileKey, nodeId, setNodeId, _componentMeta, _allComponentsMeta) {
+    try {
+        const targetId = setNodeId || nodeId;
+        // Resolve the page the component lives on — independent of library-publish
+        // status (published `containing_frame` metadata is empty for many files).
+        // Requesting the file with `ids` returns every page in document order, but
+        // prunes each page's children to only the path reaching the requested node,
+        // so the single page whose subtree still contains the node is its home page.
+        const pages = (await api.getFile(fileKey, { ids: [targetId] }))?.document?.children || [];
+        const contains = (n) => n?.id === targetId || (Array.isArray(n?.children) && n.children.some(contains));
+        const idx = pages.findIndex((p) => contains(p));
+        if (idx < 0)
+            return null;
+        // Walk back to the nearest atomic-design divider page.
+        const LEVELS = [
+            ["ATOM", "atom"],
+            ["MOLECULE", "molecule"],
+            ["ORGANISM", "organism"],
+            ["TEMPLATE", "template"],
+        ];
+        for (let i = idx; i >= 0; i--) {
+            const stripped = (pages[i]?.name || "").toUpperCase().replace(/[^A-Z]/g, "");
+            for (const [marker, level] of LEVELS) {
+                if (stripped.startsWith(marker))
+                    return level;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource, level) {
     const status = codeInfo?.changelog?.[0]
         ? "stable"
         : componentMeta?.description?.toLowerCase().includes("deprecated")
@@ -1388,6 +1428,8 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
             : "stable";
     const version = codeInfo?.changelog?.[0]?.version || "1.0.0";
     const tags = [componentName.toLowerCase()];
+    if (level)
+        tags.push(level);
     if (node.type === "COMPONENT_SET")
         tags.push("variants");
     if (node.componentPropertyDefinitions)
@@ -1395,10 +1437,11 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
     const lines = [
         "---",
         `title: ${componentName}`,
-        `description: ${(description.split(/(?:When to Use|When NOT to Use|Variants|Content Requirements|Accessibility)/i)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim() || `${componentName} component`}`,
+        `description: ${((description.split(/\n\s*\n|\n#{1,6}\s|\n\*\*/)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim().split(/(?<=[.!?])\s+/)[0] || `${componentName} component`)}`,
         `status: ${status}`,
         `version: ${version}`,
         `category: components`,
+        ...(level ? [`level: ${level}`] : []),
         `tags: [${tags.join(", ")}]`,
         `figma: ${fileUrl}`,
     ];
@@ -2560,7 +2603,9 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Desktop Bridge fetch failed, proceeding without bridge-sourced data");
                 }
             }
-            const fileUrl_ = `${url}?node-id=${nodeId.replace(":", "-")}`;
+            // Strip any existing query (e.g. the connected file's ?node-id=<page>) before
+            // appending the target node, otherwise the URL ends up with a doubled ?node-id=.
+            const fileUrl_ = `${url.split("?")[0]}?node-id=${nodeId.replace(":", "-")}`;
             // Parse the component description for structured content
             const parsedDesc = parseComponentDescription(description);
             // Determine canonical source
@@ -2589,7 +2634,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             const parts = [];
             const includedSections = [];
             if (includeFrontmatter) {
-                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource));
+                const atomicLevel = await detectAtomicLevel(api, fileKey, nodeId, setInfo.setNodeId, componentMeta, allComponentsMeta);
+                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel));
                 parts.push("");
             }
             if (s.overview) {

package/dist/cloudflare/core/design-system-tools.js

@@ -7,7 +7,8 @@
  * to generate code with structural fidelity to the real design system.
  */
 import { z } from "zod";
-import { extractFileKey, formatVariables } from "./figma-api.js";
+import { extractFileKey } from "./figma-api.js";
+import { resolveFormattedVariables } from "./variable-resolver.js";
 import { createChildLogger } from "./logger.js";
 const logger = createChildLogger({ component: "design-system-tools" });
 // ============================================================================
@@ -420,13 +421,15 @@ function compressKit(kit, level) {
 // ============================================================================
 // Tool Registration
 // ============================================================================
-export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, variablesCache, options) {
+export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, variablesCache, options, getDesktopConnector) {
     server.tool("figma_get_design_system_kit", "PREFERRED TOOL for design system extraction — replaces separate figma_get_styles, figma_get_variables, and figma_get_component calls. " +
         "Returns tokens, components, and styles in a single optimized response with adaptive compression for large systems. " +
         "Includes component visual specs (exact colors, padding, typography, layout), rendered screenshots, " +
         "token values per mode (light/dark), and resolved style values. " +
         "Use this instead of calling individual tools to avoid context window overflow. " +
-        "Ideal for AI code generation — use visualSpec for pixel-accurate reproduction.", {
+        "Ideal for AI code generation — use visualSpec for pixel-accurate reproduction. " +
+        "Tokens/variables are read through the connected Desktop Bridge or cloud relay and work on ANY Figma plan — no Enterprise required. " +
+        "If a tokens fetch ever reports the Variables REST API is plan-limited (403), the bridge/relay is the plan-independent path: ensure it's connected and retry rather than abandoning variables.", {
         fileKey: z
             .string()
             .optional()
@@ -482,25 +485,32 @@ export function registerDesignSystemTools(server, getFigmaAPI, getCurrentUrl, va
                 try {
                     logger.info({ fileKey: resolvedFileKey }, "Fetching design tokens");
                     // Check cache first
-                    let variablesData = null;
                     const cacheKey = `vars:${resolvedFileKey}`;
+                    let formatted = null;
                     if (variablesCache) {
                         const cached = variablesCache.get(cacheKey);
                         if (cached && Date.now() - cached.timestamp < 5 * 60 * 1000) {
-                            variablesData = cached.data;
+                            formatted = cached.data;
                             logger.info("Using cached variables data");
                         }
                     }
-                    if (!variablesData) {
-                        variablesData = await withTimeout(api.getLocalVariables(resolvedFileKey), 30000, "getLocalVariables");
+                    if (!formatted) {
+                        // Bridge-first: the Desktop Bridge / cloud relay reads variables on
+                        // ANY plan via the Plugin API. The Enterprise-only REST Variables API
+                        // is the fallback, used only when no bridge is connected — so most
+                        // users (non-Enterprise) no longer dead-end on a 403 here.
+                        formatted = await resolveFormattedVariables({
+                            getDesktopConnector,
+                            getFigmaAPI,
+                            fileKey: resolvedFileKey,
+                        });
                         if (variablesCache) {
                             variablesCache.set(cacheKey, {
-                                data: variablesData,
+                                data: formatted,
                                 timestamp: Date.now(),
                             });
                         }
                     }
-                    const formatted = formatVariables(variablesData);
                     const collections = groupVariablesByCollection(formatted);
                     kit.tokens = {
                         collections,

package/dist/cloudflare/core/tokens-tools.js

@@ -30,7 +30,7 @@ const logger = createChildLogger({ component: "tokens-tools" });
  * on every exported token document. Kept in sync with package.json by
  * scripts/release.sh — see step 3 of the release flow.
  */
-const MCP_VERSION = "1.29.0";
+const MCP_VERSION = "1.29.2";
 const EXPORT_TOOL_DESCRIPTION = `Export Figma variables to design token files in your codebase. Bidirectional with figma_import_tokens — together they replace Style Dictionary and Tokens Studio's export pipeline for the popular styling methods.
 
 FULLY-IMPLEMENTED OUTPUT FORMATS:

package/dist/cloudflare/core/variable-resolver.js

@@ -0,0 +1,85 @@
+/**
+ * Bridge-first variable resolution.
+ *
+ * Figma's Variables REST API (`/files/:key/variables/local`) is **Enterprise-only**
+ * and returns 403 for the majority of users (Starter/Pro/Org). The Desktop Bridge
+ * and cloud relay read variables through the Plugin API
+ * (`figma.variables.getLocalVariablesAsync`), which works on **every** Figma plan.
+ *
+ * Orchestration tools (e.g. `figma_get_design_system_kit`) historically called the
+ * REST API directly and dead-ended on a 403 for non-Enterprise users — even when a
+ * bridge was connected. This helper mirrors `figma_get_variables`' resolution order
+ * so every variable-reading tool behaves consistently:
+ *
+ *   1. Desktop Bridge / cloud relay (any plan)  ← preferred
+ *   2. REST Variables API (Enterprise only)      ← fallback
+ *
+ * It returns the same normalized shape as `formatVariables()`.
+ */
+import { formatVariables, withTimeout } from "./figma-api.js";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "variable-resolver" });
+/**
+ * The Desktop Bridge returns variables/collections as **arrays**, while
+ * `formatVariables()` expects **objects keyed by id** (the REST shape). Convert so
+ * the same formatter handles both transports.
+ */
+function bridgeArraysToFormatInput(data) {
+    const variables = {};
+    for (const v of data.variables || []) {
+        if (v && v.id)
+            variables[v.id] = v;
+    }
+    const variableCollections = {};
+    for (const c of data.variableCollections || []) {
+        if (c && c.id)
+            variableCollections[c.id] = c;
+    }
+    return { variables, variableCollections };
+}
+/**
+ * Resolve + format local variables, preferring the Desktop Bridge / cloud relay and
+ * falling back to the Enterprise-only REST API only when no bridge is connected.
+ *
+ * @throws a bridge-pointing error when the bridge is unavailable AND the REST API
+ *         fails (e.g. 403 without Enterprise), so callers/LLMs retry via the bridge
+ *         instead of treating variables as inaccessible.
+ */
+export async function resolveFormattedVariables(opts) {
+    const { getDesktopConnector, getFigmaAPI, fileKey } = opts;
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    // 1. Desktop Bridge / cloud relay — works on ANY plan. Preferred.
+    if (getDesktopConnector) {
+        try {
+            const connector = await getDesktopConnector();
+            const raw = await withTimeout(connector.getVariables(fileKey), timeoutMs, "Desktop Bridge variables");
+            // EXECUTE_CODE responses nest the return value under `result`; unwrap so
+            // both the live and cached plugin paths produce a uniform shape. See #68.
+            const data = raw?.result?.variables ? raw.result : raw;
+            if (data?.success && Array.isArray(data.variables)) {
+                const formatted = formatVariables(bridgeArraysToFormatInput(data));
+                logger.info({ source: "desktop_bridge", variableCount: formatted.variables.length }, "Resolved variables via Desktop Bridge");
+                return { ...formatted, source: "desktop_bridge" };
+            }
+            logger.warn({ fileKey, error: data?.error }, "Desktop Bridge returned no variables; falling back to REST API");
+        }
+        catch (err) {
+            logger.warn({ fileKey, error: err instanceof Error ? err.message : String(err) }, "Desktop Bridge variable fetch failed; falling back to REST API");
+        }
+    }
+    // 2. REST Variables API — Enterprise only. Last resort.
+    const api = await getFigmaAPI();
+    try {
+        const local = await withTimeout(api.getLocalVariables(fileKey), timeoutMs, "getLocalVariables");
+        const formatted = formatVariables(local);
+        logger.info({ source: "rest_api", variableCount: formatted.variables.length }, "Resolved variables via REST API");
+        return { ...formatted, source: "rest_api" };
+    }
+    catch (restErr) {
+        const msg = restErr instanceof Error ? restErr.message : String(restErr);
+        throw new Error(`[figma-console-mcp] Could not read variables. The Figma Variables REST API ` +
+            `is unavailable for this file (${msg}) — it requires an Enterprise plan. ` +
+            `Connect the Figma Console MCP Desktop Bridge plugin (or pair it via Cloud Mode) ` +
+            `to read variables on ANY plan, then retry.`);
+    }
+}

package/dist/cloudflare/index.js

@@ -74,7 +74,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         this.server = (() => {
             const s = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.29.0",
+                version: "1.29.2",
             });
             // Identity wrap — every tool's response and thrown error gets stamped
             // with our MCP name so cross-MCP attribution is unambiguous.
@@ -809,7 +809,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         registerVersionTools(this.server, async () => await this.getFigmaAPI(), () => this.browserManager?.getCurrentUrl() || null, { isRemoteMode: true });
         // Register Design System Kit tool
         registerDesignSystemTools(this.server, async () => await this.getFigmaAPI(), () => this.browserManager?.getCurrentUrl() || null, undefined, // variablesCache
-        { isRemoteMode: true });
+        { isRemoteMode: true }, getCloudDesktopConnector);
         // Register Library Tools (key-based component inspection across shared libraries)
         registerLibraryTools(this.server, async () => await this.getFigmaAPI());
         // Register Library Variable Tools (Plugin-API based — list + import variables
@@ -1083,7 +1083,7 @@ export default {
             });
             const statelessServer = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.29.0",
+                version: "1.29.2",
             });
             wrapServerForIdentity(statelessServer);
             // ================================================================
@@ -1180,7 +1180,7 @@ export default {
             registerCommentTools(statelessServer, async () => statelessApi, getCloudFileUrl);
             registerVersionTools(statelessServer, async () => statelessApi, getCloudFileUrl);
             registerDesignSystemTools(statelessServer, async () => statelessApi, getCloudFileUrl, new Map(), // Fresh variables cache per request
-            { isRemoteMode: true });
+            { isRemoteMode: true }, getCloudDesktopConnector);
             registerLibraryTools(statelessServer, async () => statelessApi);
             registerLibraryVariableTools(statelessServer, getCloudDesktopConnector);
             await statelessServer.connect(transport);
@@ -1720,7 +1720,7 @@ export default {
             return new Response(JSON.stringify({
                 status: "healthy",
                 service: "Figma Console MCP",
-                version: "1.29.0",
+                version: "1.29.2",
                 endpoints: {
                     mcp: ["/sse", "/mcp"],
                     oauth_mcp_spec: ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],

package/dist/core/design-code-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"design-code-tools.d.ts","sourceRoot":"","sources":["../../src/core/design-code-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK/C,OAAO,KAAK,EAUX,uBAAuB,EACvB,MAAM,wBAAwB,CAAC;AAUhC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1F,qDAAqD;AACrD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzG;AAiED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBpG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUxD;AAMD,sEAAsE;AACtE,UAAU,iBAAiB;IAC1B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,iBAAiB,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC/D,0BAA0B;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC;IACzC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CA0KhF;AAMD,mDAAmD;AACnD,UAAU,gBAAgB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5F,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9F,UAAU,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjG,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7C;AAED,uCAAuC;AACvC,UAAU,aAAa;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,gBAAgB,EAAE,CAqBpG;AAoED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAU,GAAG,aAAa,EAAE,CAiCzG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,GAAE,MAAU,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAqB3F;AAmHD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,GAAG,CAKhD;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AA8uDD,gFAAgF;AAChF,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GACjB,uBAAuB,CAazB;AAyJD,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EACpC,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,EAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9D,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,EACpC,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACtC,IAAI,CAwjBN"}
+{"version":3,"file":"design-code-tools.d.ts","sourceRoot":"","sources":["../../src/core/design-code-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/design-code-tools.js

@@ -174,7 +174,7 @@ export function parseComponentDescription(description) {
     for (const line of lines) {
         const trimmed = line.trim();
         // Detect section headers: bold text (**Header**), markdown headers (## Header), or plain text exact matches
-        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|###?\s*)(.+?)(?:\*\*)?$/);
+        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|#{1,6}\s*)(.+?)(?:\*\*)?$/);
         const headerText = markdownHeaderMatch ? markdownHeaderMatch[1].trim().replace(/\*\*/g, "") : null;
         // Check if this is a Figma per-property documentation block (e.g., "Show Left Icon: True – Purpose")
         // These should be routed to "other" to avoid polluting content guidelines and accessibility sections
@@ -1380,7 +1380,47 @@ function buildParityInstruction(componentName, parityScore, counts, canonicalSou
 // ============================================================================
 // Documentation Section Generators
 // ============================================================================
-function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource) {
+/**
+ * Detect the atomic-design level (atom | molecule | organism | template) of a component
+ * by finding its Figma page and walking the ordered page list back to the nearest
+ * section-divider page (e.g. "ATOMS", "MOLECULES", "ORGANISMS"). Returns null when the
+ * file doesn't use atomic-design page sections or the page can't be resolved — callers
+ * then simply omit the `level` frontmatter. Best-effort and never throws.
+ */
+async function detectAtomicLevel(api, fileKey, nodeId, setNodeId, _componentMeta, _allComponentsMeta) {
+    try {
+        const targetId = setNodeId || nodeId;
+        // Resolve the page the component lives on — independent of library-publish
+        // status (published `containing_frame` metadata is empty for many files).
+        // Requesting the file with `ids` returns every page in document order, but
+        // prunes each page's children to only the path reaching the requested node,
+        // so the single page whose subtree still contains the node is its home page.
+        const pages = (await api.getFile(fileKey, { ids: [targetId] }))?.document?.children || [];
+        const contains = (n) => n?.id === targetId || (Array.isArray(n?.children) && n.children.some(contains));
+        const idx = pages.findIndex((p) => contains(p));
+        if (idx < 0)
+            return null;
+        // Walk back to the nearest atomic-design divider page.
+        const LEVELS = [
+            ["ATOM", "atom"],
+            ["MOLECULE", "molecule"],
+            ["ORGANISM", "organism"],
+            ["TEMPLATE", "template"],
+        ];
+        for (let i = idx; i >= 0; i--) {
+            const stripped = (pages[i]?.name || "").toUpperCase().replace(/[^A-Z]/g, "");
+            for (const [marker, level] of LEVELS) {
+                if (stripped.startsWith(marker))
+                    return level;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource, level) {
     const status = codeInfo?.changelog?.[0]
         ? "stable"
         : componentMeta?.description?.toLowerCase().includes("deprecated")
@@ -1388,6 +1428,8 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
             : "stable";
     const version = codeInfo?.changelog?.[0]?.version || "1.0.0";
     const tags = [componentName.toLowerCase()];
+    if (level)
+        tags.push(level);
     if (node.type === "COMPONENT_SET")
         tags.push("variants");
     if (node.componentPropertyDefinitions)
@@ -1395,10 +1437,11 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
     const lines = [
         "---",
         `title: ${componentName}`,
-        `description: ${(description.split(/(?:When to Use|When NOT to Use|Variants|Content Requirements|Accessibility)/i)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim() || `${componentName} component`}`,
+        `description: ${((description.split(/\n\s*\n|\n#{1,6}\s|\n\*\*/)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim().split(/(?<=[.!?])\s+/)[0] || `${componentName} component`)}`,
         `status: ${status}`,
         `version: ${version}`,
         `category: components`,
+        ...(level ? [`level: ${level}`] : []),
         `tags: [${tags.join(", ")}]`,
         `figma: ${fileUrl}`,
     ];
@@ -2560,7 +2603,9 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Desktop Bridge fetch failed, proceeding without bridge-sourced data");
                 }
             }
-            const fileUrl_ = `${url}?node-id=${nodeId.replace(":", "-")}`;
+            // Strip any existing query (e.g. the connected file's ?node-id=<page>) before
+            // appending the target node, otherwise the URL ends up with a doubled ?node-id=.
+            const fileUrl_ = `${url.split("?")[0]}?node-id=${nodeId.replace(":", "-")}`;
             // Parse the component description for structured content
             const parsedDesc = parseComponentDescription(description);
             // Determine canonical source
@@ -2589,7 +2634,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             const parts = [];
             const includedSections = [];
             if (includeFrontmatter) {
-                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource));
+                const atomicLevel = await detectAtomicLevel(api, fileKey, nodeId, setInfo.setNodeId, componentMeta, allComponentsMeta);
+                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel));
                 parts.push("");
             }
             if (s.overview) {