set_annotation

Auto-generate your docs

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

string

required

The ID of the node to annotate (can be any visible node: FRAME, COMPONENT, INSTANCE, TEXT, etc.)

string

required

The annotation text in markdown format. Supports:

Bold: **text**
Italic: *text*
Links: [text](url)
Code: `code`
Lists, headers, and more

string

The ID of an existing annotation to update. Omit to create a new annotation.

string

The ID of the annotation category. Use get_annotations() with includeCategories: true to retrieve available categories.

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"
});

const result = await set_annotation({
  nodeId: "123:456",
  annotationId: "existing-annotation-id",
  labelMarkdown: "Updated annotation text",
  categoryId: "design-spec"
});

const result = await set_annotation({
  nodeId: "123:456",
  labelMarkdown: `**Component Usage**
  
  Use for primary CTAs. See [design system](https://example.com/ds).
  
  - Max width: 320px
  - Min height: 44px
  - Use \`variant="primary"\` prop`,
  categoryId: "implementation"
});

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

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

get_annotations

Retrieve existing annotations and categories

set_multiple_annotations

Batch annotate multiple nodes

scan_nodes_by_types

Find nodes that need annotations

⌘I

Document & Selection

Creating Elements

Text Operations

Styling

Layout & Organization

Auto Layout

Components & Styles

Annotations

Prototyping & Connections

Export

Connection Management

AI Prompts

Parameters

Response

Usage

Markdown Formatting Examples

Basic formatting

Structured annotations

Workflow: Single Node Annotation

Use Cases

Design specifications

Implementation notes

Interactive prototyping notes

Best Practices

get_annotations

set_multiple_annotations

scan_nodes_by_types

​Parameters

​Response

​Usage

​Markdown Formatting Examples

​Basic formatting

​Structured annotations

​Workflow: Single Node Annotation

​Use Cases

​Design specifications

​Implementation notes

​Interactive prototyping notes

​Best Practices

​Related Tools

get_annotations

set_multiple_annotations

scan_nodes_by_types

Parameters

Response

Usage

Markdown Formatting Examples

Basic formatting

Structured annotations

Workflow: Single Node Annotation

Use Cases

Design specifications

Implementation notes

Interactive prototyping notes

Best Practices

Related Tools