figma-annotations-strategy

name	figma-annotations-strategy
description	Generate strategic Figma annotations via MCP based on PRs, tickets, or user descriptions. Use when the user wants to document a screen, flow, or component for Figma, or mentions "figma annotations", "annotation strategy".

Figma Annotations Strategy (via Figma Console MCP)

Context and goal

This skill automates the extraction and structuring of strategic context for screens, flows, or components, and attaches it directly in Figma via the figma-console MCP server. The result is the instant injection of native annotations (Figma Annotation tool, shortcut Y) onto components.

MANDATORY: Cursor/Claude MUST use Figma's native annotations. Under no circumstances should it create separate "cards" or "frames" floating on the canvas, or use the comments tool.

Activation trigger

Whenever the user requests creation of "annotations for Figma", screen documentation, or provides a link/text and asks to extract context.

Required flow

1. Context validation

Before generating annotations, validate that the provided context covers the 5 critical points:

• Screen/flow objective: What is the user trying to accomplish?
• Critical business rules: Restrictions, calculations, or essential logic.
• Important states or exceptions: Loading, empty states, errors, edge cases.
• Technical dependencies: APIs, permissions, hardware.
• Non-obvious behaviors: Animations, transitions, conditional interactions.

If any essential information is missing, ask the user before proceeding!

2. Native category definition

Categories improve annotation scannability (native Figma colored pills).

• Never include the category in the raw text (e.g. [Behavior]).
• Ensure the category exists natively (Figma Annotation Categories).
• If it does not exist in Figma, create it natively via code using figma.annotations.addAnnotationCategoryAsync({ label: 'Name', color: 'blue' }).
• Valid Figma API colors for categories: 'yellow' | 'orange' | 'red' | 'pink' | 'violet' | 'blue' | 'teal' | 'green'.
• The final annotation must use native categoryId and text without category prefix.

2.1 Categorization rules (required)

• Business rules -> Business Rule
• UX/interaction rules -> Behavior
• Motion and transition -> Animation
• Exceptions, fallback, unavailability -> Exception
• Technical dependencies and limitations -> Technical Dependency
• Future improvements and backlog -> Future Delivery

3. Direct execution in Figma (required)

You must NOT generate JSON files on disk. You MUST use the figma_execute tool (provided by the figma-console MCP server) to attach annotations.

Base script for figma_execute:

Adapt the code below by replacing the ANNOTATIONS_DATA variable with the real data you generated, referencing the correct Figma node IDs.

const ANNOTATIONS_DATA = [
  {
    id: "COMPONENT_ID",
    text: "Detailed description of the behavior, rule, or state.",
    categoryLabel: "Behavior",
    categoryColor: "blue" // 'yellow'|'orange'|'red'|'pink'|'violet'|'blue'|'teal'|'green'
  }
];

async function applyNativeAnnotations() {
  const existingCategories = await figma.annotations.getAnnotationCategoriesAsync();
  const categoryMap = new Map();
  
  // Map existing categories in the file
  for (const c of existingCategories) {
    const full = await figma.annotations.getAnnotationCategoryByIdAsync(c.id);
    categoryMap.set(full.label, full.id);
  }

  let appliedCount = 0;

  for (const item of ANNOTATIONS_DATA) {
    const node = await figma.getNodeByIdAsync(item.id);
    if (!node || !('annotations' in node)) {
      console.log(`Node ${item.id} not found or does not support annotations.`);
      continue;
    }

    // Create category if it does not exist
    let catId = categoryMap.get(item.categoryLabel);
    if (!catId) {
      try {
        const newCat = await figma.annotations.addAnnotationCategoryAsync({
          label: item.categoryLabel,
          color: item.categoryColor
        });
        catId = newCat.id;
        categoryMap.set(item.categoryLabel, catId);
      } catch (e) {
        console.error(`Error creating category ${item.categoryLabel}:`, e);
      }
    }

    // Update annotation with NATIVE category (colored pill)
    const newAnnotation = { labelMarkdown: item.text };
    if (catId) {
      newAnnotation.categoryId = catId;
    }
    
    // Do not create card/frame. Only native annotation on existing node.
    const current = node.annotations || [];
    node.annotations = [newAnnotation, ...current];
    
    appliedCount++;
  }

  figma.notify(`✅ ${appliedCount} native annotations applied successfully!`);
  return `Done. ${appliedCount} annotations inserted.`;
}

return applyNativeAnnotations();