Annotations

读取和管理设计标注及标注分类。

Type reference

// Annotations are designer-authored notes attached to nodes — specs, intent, constraints.
// Every node-returning endpoint includes an annotation brief: { label, properties?, categoryId? }.
// Use this endpoint for full CRUD and to manage annotation categories.
// Workflow: read annotations on a node with get, add new ones with add, manage categories with categories/create_category.
// Batch: get/set/add/remove accept items:[{id, ...}] for multi-node operations, or single-item params (id, label, etc).
// properties: measurement indicators Figma displays on the canvas — validated per node type and state.
// labelMarkdown: rich text label supporting **bold**, *italic*, `code`, [links](url).
// categoryId: group annotations by category (e.g. "Spacing", "Typography"). Create categories first.
// ---
// AnnotationPropertyType values (node-type-dependent — invalid ones are rejected with the available list):
//   Dimension: width, height, maxWidth, minWidth, maxHeight, minHeight
//   Paint: fills, strokes, effects, strokeWeight, cornerRadius, opacity
//   Text (TEXT nodes only): textStyleId, textAlignHorizontal, fontFamily, fontStyle, fontSize, fontWeight, lineHeight, letterSpacing
//   Layout (auto-layout only): itemSpacing, padding, layoutMode, alignItems
//   Instance (INSTANCE only): mainComponent
//   Grid (grid layout only): gridRowGap, gridColumnGap, gridRowCount, gridColumnCount, gridRowAnchorIndex, gridColumnAnchorIndex, gridRowSpan, gridColumnSpan
// AnnotationCategoryColor values: yellow, orange, red, pink, violet, blue, teal, green.
// Shared types:
// Color: hex "#RGB"|"#RGBA"|"#RRGGBB"|"#RRGGBBAA" or {r: 0-1, g: 0-1, b: 0-1, a?: 0-1}
// VariableAlias: {type: "VARIABLE_ALIAS", id: string}. The id must be a Figma VariableID; discover it via variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName/strokeVariableName when available; Paint[] VariableAlias is mainly for precise Paint[] round-trips and gradient stop bindings.
// Transform: [[number, number, number], [number, number, number]] (Figma Plugin API 2×3 matrix)
// BlendMode: "PASS_THROUGH"|"NORMAL"|"DARKEN"|"MULTIPLY"|"LINEAR_BURN"|"COLOR_BURN"|"LIGHTEN"|"SCREEN"|"LINEAR_DODGE"|"COLOR_DODGE"|"OVERLAY"|"SOFT_LIGHT"|"HARD_LIGHT"|"DIFFERENCE"|"EXCLUSION"|"HUE"|"SATURATION"|"COLOR"|"LUMINOSITY"
// ColorStop: {position: 0-1, color: Color, boundVariables?: {color?: VariableAlias}}
// GradientPaint: {type: "GRADIENT_LINEAR"|"GRADIENT_RADIAL"|"GRADIENT_ANGULAR"|"GRADIENT_DIAMOND", gradientTransform: Transform, gradientStops: ColorStop[], visible?: boolean, opacity?: number, blendMode?: BlendMode}. Use gradientTransform + gradientStops (basic left-to-right: [[1,0,0],[0,1,0]]); do not use CSS gradients or REST gradientHandlePositions.
// Paint: Paint[] authoring accepts only SOLID and GRADIENT_LINEAR/GRADIENT_RADIAL/GRADIENT_ANGULAR/GRADIENT_DIAMOND. SolidPaint: {type: "SOLID", color: Color, visible?: boolean, opacity?: number, blendMode?: BlendMode, boundVariables?: {color?: VariableAlias}}. GradientPaint authoring: {type: GRADIENT_*, gradientTransform: Transform, gradientStops: ColorStop[], visible?, opacity?, blendMode?}; bind variables on gradientStops[].boundVariables.color, not top-level gradient boundVariables. Do not pass IMAGE/VIDEO/PATTERN to create/update Paint[]; those may appear only in readback metadata from existing Figma content. Use imageUrl/images for image authoring. VIDEO/PATTERN authoring is not supported here. Do not use CSS gradients or REST gradientHandlePositions.

9 methods available.

get

read

Read all annotations on a node (full detail with resolved category names)

Example

annotations(method:"get", id:"1:23")

Parameter	Type	Required	Description
id	string	✗	Node ID
categoryId	string	✗	Filter — only return annotations in this category
items	object[]	✗	Batch: [{id, categoryId?}, ...]
↳ id	string	✓
↳ categoryId	string	✗

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ name	string
↳ annotations	object[]
↳ index	number
↳ label	string
↳ labelMarkdown	string
↳ properties	string[]
↳ category	object
↳ id	string
↳ label	string
↳ color	string

list

read

Search annotations across a subtree, optionally filtered by category

Example

annotations(method:"list", parentId:"1:2", categoryId:"113:0")

Parameter	Type	Required	Description
parentId	string	✗	Root node to search within (default: current page)
categoryId	string	✗	Filter by category ID
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Field	Type	Description
results	object[]	Annotations found across the subtree
↳ nodeId	string
↳ nodeName	string
↳ nodeType	string
↳ index	number
↳ label	string
↳ labelMarkdown	string
↳ properties	string[]
↳ category	object
↳ id	string
↳ label	string
↳ color	string
count	number
_truncated	boolean

set

edit

Replace all annotations on a node

Example

annotations(method:"set", id:"1:23", annotations:[{label:"Spacing: 16px", properties:["padding"]}])

Parameter	Type	Required	Description
id	string	✗	Node ID
annotations	object[]	✗	Array of annotation objects to set (replaces all existing)
↳ label	string	✗	Plain text label
↳ labelMarkdown	string	✗	Rich text label (Markdown)
↳ properties	string[]	✗	Measurement property types to display
↳ categoryId	string	✗	Category ID
items	object[]	✗	Batch: [{id, annotations: [...]}, ...]
↳ id	string	✓
↳ annotations	array	✓	Annotations to set on this node

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ count	number

add

edit

Add an annotation to a node

Example

annotations(method:"add", id:"1:23", labelMarkdown:"**Width**: 320px fixed", properties:["width"])

Parameter	Type	Required	Description
id	string	✗	Node ID
label	string	✗	Plain text label (use label or labelMarkdown, not both)
labelMarkdown	string	✗	Rich text label with Markdown formatting
properties	string[]	✗	Measurement property types to display on canvas
categoryId	string	✗	Category ID to group this annotation
items	object[]	✗	Batch: [{id, label?, labelMarkdown?, properties?, categoryId?}, ...]
↳ id	string	✓
↳ label	string	✗
↳ labelMarkdown	string	✗
↳ properties	string[]	✗
↳ categoryId	string	✗

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ index	number
↳ count	number

remove

edit

Remove an annotation from a node by index

Example

annotations(method:"remove", id:"1:23", index:0)

Parameter	Type	Required	Description
id	string	✗	Node ID
index	number	✗	Annotation index to remove (from get response)
items	object[]	✗	Batch: [{id, index}, ...]
↳ id	string	✓
↳ index	number	✓

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ removed	boolean
↳ count	number

categories

read

List all annotation categories in the file

Example

annotations(method:"categories")

No parameters.

Response

Field	Type	Description
categories	object[]
↳ id	string
↳ label	string
↳ color	string
↳ isPreset	boolean

create_category

create

Create a new annotation category

Example

annotations(method:"create_category", label:"Spacing", color:"blue")

Parameter	Type	Required	Description
label	string	✓	Category label
color	"yellow" | "orange" | "red" | "pink" | "violet" | "blue" | "teal" | "green"	✓	Category color

Response

Field	Type	Description
id	string
label	string
color	string

update_category

edit

Update an annotation category’s label or color

Example

annotations(method:"update_category", id:"cat:123", label:"Layout", color:"teal")

Parameter	Type	Required	Description
id	string	✓	Category ID
label	string	✗	New label
color	"yellow" | "orange" | "red" | "pink" | "violet" | "blue" | "teal" | "green"	✗	New color

Response

Field	Type	Description
id	string
label	string
color	string

delete_category

edit

Delete an annotation category

Example

annotations(method:"delete_category", id:"cat:123")

Parameter	Type	Required	Description
id	string	✓	Category ID to delete

Response

Field	Type	Description
deleted	boolean