@mp3wizard/figma-console-mcp 1.17.3 → 1.19.2

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

@@ -1748,6 +1748,50 @@ function generateAccessibilitySection(node, parsedDesc, codeInfo) {
     }
     return lines.join("\n");
 }
+function generateDesignAnnotationsSection(node) {
+    // Annotations come from the Desktop Bridge plugin (node.annotations)
+    // They are available when the component was fetched via Desktop Bridge
+    const annotations = node.annotations || [];
+    if (annotations.length === 0) {
+        return [
+            "",
+            "## Design Annotations",
+            "",
+            "_No design annotations found on this node. Designers can add annotations in Dev Mode to specify animation timings, easing curves, interaction behaviors, and other implementation details._",
+            "_Use `figma_get_annotations` with `include_children=true` to check child nodes for annotations._",
+            "",
+        ].join("\n");
+    }
+    const lines = ["", "## Design Annotations", ""];
+    lines.push(`Found **${annotations.length}** annotation(s) on this component:`, "");
+    for (let i = 0; i < annotations.length; i++) {
+        const ann = annotations[i];
+        const num = i + 1;
+        // Header with category if available
+        const categoryLabel = ann.categoryName ? ` (${ann.categoryName})` : (ann.categoryId ? ` (category: ${ann.categoryId})` : "");
+        lines.push(`### Annotation ${num}${categoryLabel}`);
+        lines.push("");
+        // Label content
+        if (ann.labelMarkdown) {
+            // Indent markdown content and render it
+            lines.push(ann.labelMarkdown);
+            lines.push("");
+        }
+        else if (ann.label) {
+            lines.push(ann.label);
+            lines.push("");
+        }
+        // Pinned properties
+        if (ann.properties && ann.properties.length > 0) {
+            lines.push("**Pinned Properties:**");
+            for (const prop of ann.properties) {
+                lines.push(`- \`${prop.type}\``);
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
 function generateChangelogSection(codeInfo) {
     if (!codeInfo?.changelog || codeInfo.changelog.length === 0)
         return "";
@@ -2083,7 +2127,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             logger.info({ fileKey, nodeId, canonicalSource, enrich }, "Starting design-code parity check");
             const api = await getFigmaAPI();
             // Fetch component node
-            const nodesResponse = await api.getNodes(fileKey, [nodeId], { depth: 2 });
+            const nodesResponse = await api.getNodes(fileKey, [nodeId], { depth: 4 });
             const nodeData = nodesResponse?.nodes?.[nodeId];
             if (!nodeData?.document) {
                 throw new Error(`Node ${nodeId} not found in file ${fileKey}`);
@@ -2234,7 +2278,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
     // -----------------------------------------------------------------------
     // Tool: figma_generate_component_doc
     // -----------------------------------------------------------------------
-    server.tool("figma_generate_component_doc", "Generate AI-complete component documentation from a Figma component. Produces structured markdown with anatomy, per-variant color tokens, typography, content guidelines (parsed from Figma description), icon mapping, spacing tokens, and design-code parity analysis. Merges Figma design data with optional code-side info (CVA definitions, sub-component APIs, source files). Output works with any docs platform. For richest output, read the component source code first and pass codeInfo.", {
+    server.tool("figma_generate_component_doc", "Generate AI-complete component documentation from a Figma component. Produces structured markdown with anatomy, per-variant color tokens, typography, content guidelines (parsed from Figma description), design annotations (animation timings, interaction specs, accessibility notes from Dev Mode), icon mapping, spacing tokens, and design-code parity analysis. Merges Figma design data with optional code-side info (CVA definitions, sub-component APIs, source files). Output works with any docs platform. For richest output, read the component source code first and pass codeInfo.", {
         fileUrl: z
             .string()
             .url()
@@ -2252,6 +2296,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             behavior: z.boolean().optional().default(false),
             implementation: z.boolean().optional().default(true),
             accessibility: z.boolean().optional().default(true),
+            designAnnotations: z.boolean().optional().default(true),
             relatedComponents: z.boolean().optional().default(false),
             changelog: z.boolean().optional().default(true),
             parity: z.boolean().optional().default(true),
@@ -2350,19 +2395,27 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             // REST API getNodes() often returns empty description for COMPONENT_SET nodes,
             // so fall back to Desktop Bridge plugin API which has the reliable description.
             let description = node.descriptionMarkdown || node.description || componentMeta?.description || "";
-            if (!description && getDesktopConnector) {
+            if (getDesktopConnector) {
                 try {
                     const connector = await getDesktopConnector();
                     const bridgeResult = await connector.getComponentFromPluginUI(nodeId);
                     if (bridgeResult.success && bridgeResult.component) {
-                        description = bridgeResult.component.descriptionMarkdown || bridgeResult.component.description || "";
-                        if (description) {
-                            logger.info("Fetched description via Desktop Bridge (REST API returned empty)");
+                        // Fetch description from bridge if REST API returned empty
+                        if (!description) {
+                            description = bridgeResult.component.descriptionMarkdown || bridgeResult.component.description || "";
+                            if (description) {
+                                logger.info("Fetched description via Desktop Bridge (REST API returned empty)");
+                            }
+                        }
+                        // Always fetch annotations from bridge (REST API never has them)
+                        if (bridgeResult.component.annotations && bridgeResult.component.annotations.length > 0) {
+                            node.annotations = bridgeResult.component.annotations;
+                            logger.info({ count: node.annotations.length }, "Fetched annotations via Desktop Bridge for documentation");
                         }
                     }
                 }
                 catch {
-                    logger.warn("Desktop Bridge description fetch failed, proceeding without description");
+                    logger.warn("Desktop Bridge fetch failed, proceeding without bridge-sourced data");
                 }
             }
             const fileUrl_ = `${url}?node-id=${nodeId.replace(":", "-")}`;
@@ -2441,6 +2494,11 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                 parts.push(generateAccessibilitySection(node, parsedDesc, codeInfo));
                 includedSections.push("accessibility");
             }
+            if (s.designAnnotations !== false) {
+                const annotationsSection = generateDesignAnnotationsSection(node);
+                parts.push(annotationsSection);
+                includedSections.push("designAnnotations");
+            }
             if (s.parity && hasCodeInfo && hasFigmaData && codeInfo) {
                 const paritySection = generateParitySection(node, codeInfo);
                 if (paritySection) {

package/dist/cloudflare/core/enrichment/enrichment-service.js

@@ -152,20 +152,116 @@ export class EnrichmentService {
                 }
                 enriched.styles_used = stylesUsed;
             }
-            // Extract variables used
-            if (component.boundVariables) {
-                const varsUsed = [];
-                // This would need actual variable resolution
-                enriched.variables_used = varsUsed;
-            }
-            // Detect hardcoded values (simplified for now)
-            // TODO: Implement full hardcoded value detection
-            enriched.hardcoded_values = [];
+            // Extract variables used and detect hardcoded values by walking the node tree
+            const varsUsed = [];
+            const hardcodedValues = [];
+            const variables = this.extractVariablesMap(data);
+            // Walk node tree to find boundVariables and hardcoded values
+            const walkForTokens = (node, path = "") => {
+                if (!node)
+                    return;
+                const nodePath = path ? `${path} > ${node.name || node.id}` : (node.name || node.id);
+                const bv = node.boundVariables || {};
+                // Check fills
+                if (node.fills && Array.isArray(node.fills)) {
+                    for (let i = 0; i < node.fills.length; i++) {
+                        const fill = node.fills[i];
+                        if (fill.type === "SOLID" && fill.visible !== false) {
+                            const fillBv = bv.fills;
+                            if (fillBv && (Array.isArray(fillBv) ? fillBv[i] : fillBv)) {
+                                const varRef = Array.isArray(fillBv) ? fillBv[i] : fillBv;
+                                if (varRef?.id) {
+                                    const varInfo = variables.get(varRef.id);
+                                    varsUsed.push({
+                                        variableId: varRef.id,
+                                        variableName: varInfo?.name || varRef.id,
+                                        property: "fill",
+                                        nodePath,
+                                    });
+                                }
+                            }
+                            else {
+                                // Hardcoded fill
+                                const c = fill.color;
+                                if (c) {
+                                    hardcodedValues.push({
+                                        property: "fill",
+                                        value: `rgb(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)})`,
+                                        nodePath,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Check strokes
+                if (node.strokes && Array.isArray(node.strokes)) {
+                    for (let i = 0; i < node.strokes.length; i++) {
+                        const stroke = node.strokes[i];
+                        if (stroke.type === "SOLID" && stroke.visible !== false) {
+                            const strokeBv = bv.strokes;
+                            if (strokeBv && (Array.isArray(strokeBv) ? strokeBv[i] : strokeBv)) {
+                                const varRef = Array.isArray(strokeBv) ? strokeBv[i] : strokeBv;
+                                if (varRef?.id) {
+                                    const varInfo = variables.get(varRef.id);
+                                    varsUsed.push({
+                                        variableId: varRef.id,
+                                        variableName: varInfo?.name || varRef.id,
+                                        property: "stroke",
+                                        nodePath,
+                                    });
+                                }
+                            }
+                            else {
+                                const c = stroke.color;
+                                if (c) {
+                                    hardcodedValues.push({
+                                        property: "stroke",
+                                        value: `rgb(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)})`,
+                                        nodePath,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Check spacing/sizing tokens
+                const spacingProps = ["itemSpacing", "paddingLeft", "paddingRight", "paddingTop", "paddingBottom", "cornerRadius"];
+                for (const prop of spacingProps) {
+                    if (node[prop] !== undefined && node[prop] !== 0) {
+                        if (bv[prop]?.id) {
+                            const varInfo = variables.get(bv[prop].id);
+                            varsUsed.push({
+                                variableId: bv[prop].id,
+                                variableName: varInfo?.name || bv[prop].id,
+                                property: prop,
+                                nodePath,
+                            });
+                        }
+                        else {
+                            hardcodedValues.push({
+                                property: prop,
+                                value: node[prop],
+                                nodePath,
+                            });
+                        }
+                    }
+                }
+                // Recurse into children
+                if (node.children && Array.isArray(node.children)) {
+                    for (const child of node.children) {
+                        walkForTokens(child, nodePath);
+                    }
+                }
+            };
+            walkForTokens(component);
+            enriched.variables_used = varsUsed;
+            enriched.hardcoded_values = hardcodedValues;
             // Calculate token coverage
-            const totalProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0) + (enriched.hardcoded_values?.length || 0);
-            const tokenProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0);
+            const totalProps = varsUsed.length + (enriched.styles_used?.length || 0) + hardcodedValues.length;
+            const tokenProps = varsUsed.length + (enriched.styles_used?.length || 0);
             enriched.token_coverage =
-                totalProps > 0 ? Math.round((tokenProps / totalProps) * 100) : 0;
+                totalProps > 0 ? Math.round((tokenProps / totalProps) * 100) : 100;
             this.logger.info({ componentId: component.id, coverage: enriched.token_coverage }, "Component enrichment complete");
             return enriched;
         }