Converting legacy annotations

Overview

Many design teams create annotations manually using text nodes with numbered markers (e.g., “1”, “2”, “3”) and corresponding description text. Figma’s native annotation system provides a more structured way to annotate designs with better organization, filtering, and collaboration features. This workflow helps you convert legacy manual annotations into Figma’s native annotation system while maintaining the connection between markers and their targets.

Why convert to native annotations

Better organization

Native annotations support categories, filtering, and structured metadata that manual text nodes cannot provide.

Improved collaboration

Team members can filter annotations by type, resolve them, and track changes more effectively.

Cleaner canvas

Remove clutter from your design canvas while preserving all annotation content and context.

Richer formatting

Native annotations support markdown formatting for better readability and structure.

Legacy annotation patterns

Common manual annotation patterns include:

Numbered text markers (“1”, “2”, “3”) placed near UI elements
Corresponding description text in a sidebar or separate frame
Lines or arrows connecting markers to their targets
Color coding for different annotation types

Conversion workflow

Scan for annotation markers

Use scan_text_nodes to identify numbered markers and description text in your design.

scan_text_nodes({
  chunkSize: 50,
  delayMs: 100
})

Look for patterns like:

Single-digit or numbered text nodes (markers)
Longer text nodes nearby (descriptions)

Identify target elements

Use scan_nodes_by_types to find the UI elements that annotations refer to.

scan_nodes_by_types({
  nodeTypes: ["FRAME", "COMPONENT", "INSTANCE", "RECTANGLE"],
  chunkSize: 50
})

This helps you build a map of potential annotation targets.

Match markers to targets

Analyze the spatial relationships, naming patterns, or explicit connections to match each marker with its target element.Matching strategies:

Proximity: Markers are usually near their targets
Naming: Target nodes may include marker numbers in their names
Path analysis: Check parent-child relationships
Line connections: Follow connector lines if present

Categorize annotations

Determine the appropriate category for each annotation based on its content.

get_annotations()

Common categories:

IMPORTANT: Critical design decisions or constraints
NOTE: Supplementary information
QUESTION: Items needing feedback or clarification

Create native annotations

Use set_multiple_annotations to batch create native annotations with proper linking.

set_multiple_annotations({
  annotations: [
    {
      nodeId: "target-element-id-1",
      text: "Description text with **markdown** support",
      category: "IMPORTANT"
    },
    {
      nodeId: "target-element-id-2",
      text: "Another annotation",
      category: "NOTE"
    }
  ]
})

Verify and clean up

Check that all annotations are properly linked to their targets and visible in Figma’s annotation panel.

get_annotations()

Once verified, delete the legacy annotation nodes:

delete_multiple_nodes({
  nodeIds: ["legacy-marker-1", "legacy-marker-2", "legacy-text-1"]
})

Matching strategies

Proximity-based
Name pattern
Path analysis

Calculate the distance between marker nodes and potential targets. The closest eligible node is likely the target.

function findClosestTarget(markerNode, candidateNodes) {
  const markerX = markerNode.x;
  const markerY = markerNode.y;
  
  let closest = null;
  let minDistance = Infinity;
  
  for (const candidate of candidateNodes) {
    const dx = candidate.x - markerX;
    const dy = candidate.y - markerY;
    const distance = Math.sqrt(dx * dx + dy * dy);
    
    if (distance < minDistance) {
      minDistance = distance;
      closest = candidate;
    }
  }
  
  return closest;
}

Look for matching patterns in node names. For example, a marker “3” might target a node named “Button-3” or “Feature 3”.

function matchByName(markerText, candidateNodes) {
  const markerNumber = markerText.trim();
  
  return candidateNodes.find(node => {
    return node.name.includes(markerNumber) || 
           node.name.includes(`#${markerNumber}`);
  });
}

Check if the marker and target share a common parent or are in the same component.

function matchByPath(markerNode, candidateNodes) {
  const markerParent = markerNode.parent;
  
  return candidateNodes.filter(node => {
    return node.parent === markerParent;
  });
}

Best practices

Always verify that native annotations are correctly linked before deleting legacy annotation nodes. Keep a backup of your design or work on a copy first.

Batch operations: Use set_multiple_annotations for better performance when converting many annotations
Preserve context: Include any relevant context from the legacy annotations in the new annotation text
Use markdown: Take advantage of markdown formatting for better readability
Category consistency: Establish consistent category usage across your team
Verify all links: Ensure every annotation has a valid target node before cleanup
Document the process: Keep notes on your matching logic for future conversions

Tool sequence

join_channel - Connect to Figma
get_document_info - Understand the design structure
scan_text_nodes - Find marker and description text
scan_nodes_by_types - Identify annotation targets
get_annotations - Review existing annotations and categories
set_multiple_annotations - Create native annotations in batch
get_annotations - Verify all annotations are linked
delete_multiple_nodes - Remove legacy annotation nodes

Example conversion

Before:

[Text node: "1"] ----→ [Button: "Submit"]
[Text node: "This button submits the form"]

[Text node: "2"] ----→ [Input field]
[Text node: "Email validation required"]

After:

Native annotation on "Submit" button:
  Category: NOTE
  Text: "This button submits the form"

Native annotation on Input field:
  Category: IMPORTANT
  Text: "Email validation required"

get_annotations - Get all annotations in the document
set_annotation - Create or update a single annotation
set_multiple_annotations - Batch create/update annotations
scan_text_nodes - Find text nodes with chunking
scan_nodes_by_types - Find nodes by type
delete_multiple_nodes - Clean up legacy annotations

annotation_conversion_strategy - Strategy for converting manual annotations to native annotations

Use Cases

Overview

Why convert to native annotations

Better organization

Improved collaboration

Cleaner canvas

Richer formatting

Legacy annotation patterns

Conversion workflow

Matching strategies

Best practices

Tool sequence

Example conversion

Build docs developers (and LLMs) love

Use Cases

​Overview

​Why convert to native annotations

Better organization

Improved collaboration

Cleaner canvas

Richer formatting

​Legacy annotation patterns

​Conversion workflow

​Matching strategies

​Best practices

​Tool sequence

​Example conversion

​Related tools

​Related prompts

Build docs developers (and LLMs) love

Overview

Why convert to native annotations

Legacy annotation patterns

Conversion workflow

Matching strategies

Best practices

Tool sequence

Example conversion

Related tools

Related prompts