Skip to main content
Creates a new annotation or updates an existing one. Annotations are Figma’s native way to add design notes, implementation details, or any contextual information directly to design elements.

​
Parameters

​
nodeId
string
required
The ID of the node to annotate (can be any visible node: FRAME, COMPONENT, INSTANCE, TEXT, etc.)
​
labelMarkdown
string
required
The annotation text in markdown format. Supports:
  • Bold: **text**
  • Italic: *text*
  • Links: [text](url)
  • Code: `code`
  • Lists, headers, and more
​
annotationId
string
The ID of an existing annotation to update. Omit to create a new annotation.
​
categoryId
string
The ID of the annotation category. Use get_annotations() with includeCategories: true to retrieve available categories.
​
properties
array
Additional properties for the annotation. Each property is an object with a type field.
properties: [{ type: "propertyType" }]

​
Response

Returns a JSON object containing:
  • success: Boolean indicating operation success
  • annotationId: ID of the created or updated annotation
  • nodeId: ID of the annotated node
  • message: Status message

​
Usage

const result = await set_annotation({
  nodeId: "123:456",
  labelMarkdown: "**Login Button**: Triggers authentication flow",
  categoryId: "dev-notes"
});

​
Markdown Formatting Examples

​
Basic formatting

**Bold text** for emphasis
*Italic text* for subtlety
[Link to docs](https://example.com)
`code snippets` inline

​
Structured annotations

**Button Component**

Implementation notes:
- Use `onClick` handler for primary action
- Supports `disabled` state
- See [Storybook](https://storybook.example.com)

Design tokens:
- Color: `$primary-blue`
- Padding: `16px 24px`

​
Workflow: Single Node Annotation

Typical workflow for annotating a single element: 
// 1. Get the node to annotate
const selection = await get_selection();
const targetNode = selection[0];

// 2. Get available categories
const { categories } = await get_annotations({
  nodeId: targetNode.id,
  includeCategories: true
});

// 3. Apply annotation
const result = await set_annotation({
  nodeId: targetNode.id,
  labelMarkdown: "**Header Component**: Main navigation bar",
  categoryId: categories[0].id  // Use first available category
});

console.log(`Annotation created: ${result.annotationId}`);

​
Use Cases

​
Design specifications

Document design decisions and constraints: 
await set_annotation({
  nodeId: cardComponentId,
  labelMarkdown: `**Card Specifications**
  
  - Border radius: 8px
  - Shadow: 0 2px 8px rgba(0,0,0,0.1)
  - Padding: 24px
  - Max width: 400px`,
  categoryId: "design-spec"
});

​
Implementation notes

Provide context for developers: 
await set_annotation({
  nodeId: formFieldId,
  labelMarkdown: `**Validation Rules**
  
  - Required field
  - Min 8 characters
  - Must include special character
  - See [validation docs](https://docs.example.com)`,
  categoryId: "dev-notes"
});

​
Interactive prototyping notes

Document interaction behaviors: 
await set_annotation({
  nodeId: buttonId,
  labelMarkdown: `**Interaction**
  
  On click:
  1. Show loading state
  2. Submit form data
  3. Navigate to /dashboard
  
  Error handling: Display toast notification`,
  categoryId: "interaction"
});

​
Best Practices

  1. Use structured markdown: Leverage headers, lists, and formatting for clarity
  2. Be concise: Keep annotations focused on essential information
  3. Link to docs: Use markdown links to reference external documentation
  4. Choose appropriate categories: Use categories to organize annotation types
  5. Update existing annotations: Use annotationId to update rather than duplicate

​
Related Tools

get_annotations

Retrieve existing annotations and categories

set_multiple_annotations

Batch annotate multiple nodes

scan_nodes_by_types

Find nodes that need annotations

Build docs developers (and LLMs) love

Get started for freeTalk to us