@mp3wizard/figma-console-mcp 1.19.0 → 1.19.2

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

@@ -0,0 +1,230 @@
+/**
+ * Figma Annotations MCP Tools
+ * Tools for reading, writing, and managing design annotations on Figma nodes.
+ * Annotations are a Plugin API feature — requires Desktop Bridge plugin connection.
+ *
+ * Annotations are distinct from comments: they are node-level design specs that
+ * can pin specific properties (fills, width, typography, etc.) and support
+ * markdown-formatted labels. Designers use them to communicate animation timings,
+ * accessibility requirements, interaction specs, and other implementation details
+ * that don't fit in the description field.
+ */
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "annotation-tools" });
+// Valid AnnotationPropertyType values from the Figma Plugin API
+// Sourced from @figma/plugin-typings — keep in sync with AnnotationPropertyType union
+// Reference: https://developers.figma.com/docs/plugins/api/AnnotationProperty
+const ANNOTATION_PROPERTY_TYPES = [
+    "width",
+    "height",
+    "maxWidth",
+    "minWidth",
+    "maxHeight",
+    "minHeight",
+    "fills",
+    "strokes",
+    "effects",
+    "strokeWeight",
+    "cornerRadius",
+    "textStyleId",
+    "textAlignHorizontal",
+    "fontFamily",
+    "fontStyle",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "itemSpacing",
+    "padding",
+    "layoutMode",
+    "alignItems",
+    "opacity",
+    "mainComponent",
+    "gridRowGap",
+    "gridColumnGap",
+    "gridRowCount",
+    "gridColumnCount",
+    "gridRowAnchorIndex",
+    "gridColumnAnchorIndex",
+    "gridRowSpan",
+    "gridColumnSpan",
+];
+// Zod schema for annotation property
+const annotationPropertySchema = z.object({
+    type: z
+        .enum(ANNOTATION_PROPERTY_TYPES)
+        .describe("Design property to pin (e.g., 'fills', 'width', 'fontSize')"),
+});
+// Zod schema for a single annotation
+const annotationSchema = z.object({
+    label: z
+        .string()
+        .optional()
+        .describe("Plain text annotation label"),
+    labelMarkdown: z
+        .string()
+        .optional()
+        .describe("Rich text annotation label with markdown formatting. Supports bold, italic, links, lists, code, and headers."),
+    properties: z
+        .array(annotationPropertySchema)
+        .optional()
+        .describe("Design properties to pin to this annotation (e.g., fills, width, fontSize)"),
+    categoryId: z
+        .string()
+        .optional()
+        .describe("Annotation category ID. Use figma_get_annotation_categories to list available categories."),
+});
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerAnnotationTools(server, getDesktopConnector) {
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotations", "Read annotations from a Figma node. Annotations are designer-authored specs attached to nodes — they can include notes (plain text or markdown), pinned design properties (fills, width, fontSize, etc.), and category labels. Use this to discover animation timings, interaction specs, accessibility requirements, and other implementation details that designers annotate directly on the design. Set include_children=true to get annotations from child nodes too (useful for full component documentation). Requires Desktop Bridge plugin.", {
+        nodeId: z
+            .string()
+            .describe("Node ID to read annotations from (e.g., '695:313')"),
+        include_children: z.preprocess((v) => (typeof v === "string" ? v === "true" : v), z.boolean().optional().default(false)).describe("Also read annotations from child nodes. Useful for getting all annotations within a component tree."),
+        depth: z.preprocess((v) => (typeof v === "string" ? Number(v) : v), z.number().optional().default(1)).describe("How many levels deep to traverse when include_children is true (default: 1, max recommended: 5)"),
+    }, async ({ nodeId, include_children = false, depth = 1 }) => {
+        try {
+            logger.info({ nodeId, include_children, depth }, "Getting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotations(nodeId, include_children, Math.min(depth, 10));
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotations");
+            }
+            // The result may come back as { success, data } (WebSocket) or directly as data
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotations_failed",
+                            message: `Cannot get annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_set_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_set_annotations", "Write or clear annotations on a Figma node. Annotations communicate design specs to developers — use them to document animation timings, easing curves, interaction behaviors, accessibility requirements, and implementation notes. Supports plain text labels, rich markdown labels, pinned design properties, and annotation categories. Pass an empty array to clear all annotations. Use mode='append' to add to existing annotations, or mode='replace' (default) to overwrite. Requires Desktop Bridge plugin. This operation is undoable in Figma (Cmd+Z).", {
+        nodeId: z
+            .string()
+            .describe("Node ID to write annotations to (e.g., '695:313')"),
+        annotations: z.preprocess((v) => {
+            if (typeof v === "string") {
+                try {
+                    return JSON.parse(v);
+                }
+                catch {
+                    return v;
+                }
+            }
+            return v;
+        }, z.array(annotationSchema)).describe("Array of annotations to set. Each annotation can have a label (plain or markdown), pinned properties, and a category. Pass an empty array [] to clear all annotations."),
+        mode: z
+            .enum(["replace", "append"])
+            .optional()
+            .default("replace")
+            .describe("'replace' (default) overwrites all existing annotations. 'append' adds new annotations while keeping existing ones."),
+    }, async ({ nodeId, annotations, mode = "replace" }) => {
+        try {
+            logger.info({ nodeId, count: annotations.length, mode }, "Setting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.setAnnotations(nodeId, annotations, mode);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to set annotations");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            ...data,
+                            note: "Annotations set successfully. This operation is undoable in Figma (Cmd+Z).",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to set annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "set_annotations_failed",
+                            message: `Cannot set annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotation_categories
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotation_categories", "List available annotation categories in the current Figma file. Categories group annotations by purpose (e.g., interactions, accessibility, development notes). Use the returned category IDs when creating annotations with figma_set_annotations. Requires Desktop Bridge plugin.", {}, async () => {
+        try {
+            logger.info("Getting annotation categories");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotationCategories();
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotation categories");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotation categories");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotation_categories_failed",
+                            message: `Cannot get annotation categories. ${message}`,
+                            hint: "Annotation categories require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -130,6 +130,24 @@ export class CloudWebSocketConnector {
     async setNodeDescription(nodeId, description, descriptionMarkdown) {
         return this.sendCommand('SET_NODE_DESCRIPTION', { nodeId, description, descriptionMarkdown });
     }
+    // ============================================================================
+    // Annotation operations
+    // ============================================================================
+    async getAnnotations(nodeId, includeChildren, depth) {
+        return this.sendCommand('GET_ANNOTATIONS', { nodeId, includeChildren, depth }, 10000);
+    }
+    async setAnnotations(nodeId, annotations, mode) {
+        return this.sendCommand('SET_ANNOTATIONS', { nodeId, annotations, mode: mode || 'replace' });
+    }
+    async getAnnotationCategories() {
+        return this.sendCommand('GET_ANNOTATION_CATEGORIES', {}, 5000);
+    }
+    async deepGetComponent(nodeId, depth) {
+        return this.sendCommand('DEEP_GET_COMPONENT', { nodeId, depth: depth || 10 }, 30000);
+    }
+    async analyzeComponentSet(nodeId) {
+        return this.sendCommand('ANALYZE_COMPONENT_SET', { nodeId }, 30000);
+    }
     async addComponentProperty(nodeId, propertyName, type, defaultValue, options) {
         const params = { nodeId, propertyName, propertyType: type, defaultValue };
         if (options?.preferredValues)
@@ -244,6 +262,81 @@ export class CloudWebSocketConnector {
         return this.sendCommand('LINT_DESIGN', params, 120000);
     }
     // ============================================================================
+    // FigJam operations
+    // ============================================================================
+    async createSticky(params) {
+        return this.sendCommand('CREATE_STICKY', params);
+    }
+    async createStickies(params) {
+        return this.sendCommand('CREATE_STICKIES', params, 30000);
+    }
+    async createConnector(params) {
+        return this.sendCommand('CREATE_CONNECTOR', params);
+    }
+    async createShapeWithText(params) {
+        return this.sendCommand('CREATE_SHAPE_WITH_TEXT', params);
+    }
+    async createTable(params) {
+        return this.sendCommand('CREATE_TABLE', params, 30000);
+    }
+    async createCodeBlock(params) {
+        return this.sendCommand('CREATE_CODE_BLOCK', params);
+    }
+    async getBoardContents(params) {
+        return this.sendCommand('GET_BOARD_CONTENTS', params, 30000);
+    }
+    async getConnections() {
+        return this.sendCommand('GET_CONNECTIONS', {}, 15000);
+    }
+    // ============================================================================
+    // Slides operations
+    // ============================================================================
+    async listSlides() {
+        return this.sendCommand('LIST_SLIDES', {}, 10000);
+    }
+    async getSlideContent(params) {
+        return this.sendCommand('GET_SLIDE_CONTENT', params, 10000);
+    }
+    async createSlide(params) {
+        return this.sendCommand('CREATE_SLIDE', params, 10000);
+    }
+    async deleteSlide(params) {
+        return this.sendCommand('DELETE_SLIDE', params, 5000);
+    }
+    async duplicateSlide(params) {
+        return this.sendCommand('DUPLICATE_SLIDE', params, 5000);
+    }
+    async getSlideGrid() {
+        return this.sendCommand('GET_SLIDE_GRID', {}, 10000);
+    }
+    async reorderSlides(params) {
+        return this.sendCommand('REORDER_SLIDES', params, 15000);
+    }
+    async setSlideTransition(params) {
+        return this.sendCommand('SET_SLIDE_TRANSITION', params, 5000);
+    }
+    async getSlideTransition(params) {
+        return this.sendCommand('GET_SLIDE_TRANSITION', params, 5000);
+    }
+    async setSlidesViewMode(params) {
+        return this.sendCommand('SET_SLIDES_VIEW_MODE', params, 5000);
+    }
+    async getFocusedSlide() {
+        return this.sendCommand('GET_FOCUSED_SLIDE', {}, 5000);
+    }
+    async focusSlide(params) {
+        return this.sendCommand('FOCUS_SLIDE', params, 5000);
+    }
+    async skipSlide(params) {
+        return this.sendCommand('SKIP_SLIDE', params, 5000);
+    }
+    async addTextToSlide(params) {
+        return this.sendCommand('ADD_TEXT_TO_SLIDE', params, 10000);
+    }
+    async addShapeToSlide(params) {
+        return this.sendCommand('ADD_SHAPE_TO_SLIDE', params, 5000);
+    }
+    // ============================================================================
     // Cache management (no-op for cloud relay)
     // ============================================================================
     clearFrameCache() {

package/dist/cloudflare/core/deep-component-tools.js

@@ -0,0 +1,128 @@
+/**
+ * Deep Component Extraction MCP Tool
+ *
+ * Provides unlimited-depth component tree extraction via the Desktop Bridge
+ * Plugin API. Returns full visual properties, resolved design token names,
+ * instance references (mainComponent), prototype reactions, and annotations
+ * at every level of the tree.
+ *
+ * This complements figma_get_component_for_development (REST API, depth 4)
+ * with deeper, richer data when the Desktop Bridge plugin is connected.
+ */
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "deep-component-tools" });
+export function registerDeepComponentTools(server, getDesktopConnector) {
+    server.tool("figma_get_component_for_development_deep", "Get a deeply nested component tree with full visual properties, resolved design token names, instance references, prototype interactions, and annotations at every level. Uses the Desktop Bridge Plugin API for unlimited depth traversal — essential for complex components like data tables, nested menus, date pickers, and compound form fields where the standard depth-4 REST API tool misses deeper structure. Returns boundVariables resolved to actual token names (not just IDs), mainComponent references for INSTANCE nodes, and reactions for interaction states. Requires Desktop Bridge plugin. For simpler components (depth ≤ 4), use figma_get_component_for_development instead.", {
+        nodeId: z
+            .string()
+            .describe("Component node ID to extract (e.g., '695:313')"),
+        depth: z.preprocess((v) => (typeof v === "string" ? Number(v) : v), z.number().optional().default(10)).describe("Maximum tree depth to traverse (default: 10, max: 20). Use higher values for deeply nested components."),
+    }, async ({ nodeId, depth = 10 }) => {
+        try {
+            const clampedDepth = Math.min(Math.max(depth, 1), 20);
+            logger.info({ nodeId, depth: clampedDepth }, "Deep component extraction");
+            const connector = await getDesktopConnector();
+            const result = await connector.deepGetComponent(nodeId, clampedDepth);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to extract component");
+            }
+            const data = result.data || result;
+            // Measure response size and warn if large
+            const responseJson = JSON.stringify(data);
+            const sizeKB = Math.round(responseJson.length / 1024);
+            const response = {
+                nodeId,
+                component: data,
+                metadata: {
+                    purpose: "deep_component_development",
+                    treeDepth: clampedDepth,
+                    responseSizeKB: sizeKB,
+                    variablesResolved: data._variableMapSize || 0,
+                    note: [
+                        `Deep component tree extracted via Plugin API (depth ${clampedDepth}).`,
+                        "boundVariables are resolved to token names, collections, and codeSyntax.",
+                        "INSTANCE nodes include mainComponent references (key, name, component set).",
+                        "Use this data to generate production-quality, token-aware, accessible code.",
+                        sizeKB > 200 ? "Response is large — consider targeting a specific child node for deeper analysis." : null,
+                    ].filter(Boolean).join(" "),
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Deep component extraction failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "deep_component_failed",
+                            message: `Cannot extract deep component. ${message}`,
+                            hint: "This tool requires the Desktop Bridge plugin to be running in Figma. For REST API fallback (depth 4), use figma_get_component_for_development.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_analyze_component_set
+    // -----------------------------------------------------------------------
+    server.tool("figma_analyze_component_set", "Analyze a Figma COMPONENT_SET to extract variant state machine and cross-variant diffs for code generation. Returns: (1) variant axes (size, state) with all values, (2) CSS pseudo-class mappings for interaction states (hover→:hover, focus→:focus-visible, disabled→:disabled, error→[aria-invalid]), (3) visual diff from default state per variant (only changed properties — fill token, stroke token, stroke weight, text color, opacity, effects, visibility), (4) component property definitions mapped to code props (BOOLEAN→boolean, TEXT→string, INSTANCE_SWAP→slot/ReactNode). Use this on the parent COMPONENT_SET node, not individual variants. Requires Desktop Bridge plugin.", {
+        nodeId: z
+            .string()
+            .describe("COMPONENT_SET node ID (the parent of all variants, e.g., '214:274')"),
+    }, async ({ nodeId }) => {
+        try {
+            logger.info({ nodeId }, "Analyzing component set");
+            const connector = await getDesktopConnector();
+            const result = await connector.analyzeComponentSet(nodeId);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to analyze component set");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            nodeId,
+                            analysis: data,
+                            metadata: {
+                                purpose: "variant_state_machine",
+                                note: "Use cssMapping to implement interaction states as CSS pseudo-classes/attributes. diffFromDefault shows only what changes per variant — apply as style overrides. componentProps maps to your component's TypeScript interface.",
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Component set analysis failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "analyze_component_set_failed",
+                            message: `Cannot analyze component set. ${message}`,
+                            hint: "This tool requires the Desktop Bridge plugin and a COMPONENT_SET node ID (not an individual variant). Use figma_search_components to find component sets.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

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) {