Instances

创建和管理组件实例。

Type reference

// depth: omit → id+name stubs | 0 → props + child stubs | N → recurse N | -1 → full tree
// fields: whitelist e.g. ["fills","opacity"] — id, name, type always included. Pass ["*"] for all.
// layoutSizingHorizontal/Vertical: FIXED | HUG | FILL — how the node sizes within auto-layout.
// Colors: fillVariableName/strokeVariableName bind by name — preferred over raw color values.
// Note: node-based endpoints (frames, text, instances, components) use `results` as the list key.
//   Standalone endpoints (styles, variables, variable_collections) use `items`. Components.list uses `items` (catalog view).
// ---
// visible: false hides the node. Omitted from response when true (the default).
// locked: true prevents editing in Figma UI. Omitted when false (the default).
// rotation: degrees (0-360). Omitted when 0.
// blendMode: layer blend mode. Omitted when PASS_THROUGH (the default).
// layoutPositioning: ABSOLUTE = floating inside auto-layout parent. Omitted when AUTO (the default).
// minWidth/maxWidth/minHeight/maxHeight: responsive constraints for auto-layout children.
// constraints: position behavior in non-auto-layout parents. Ignored inside auto-layout frames.
// bindings: bind design variables to node properties. field uses slash path: "fills/0/color" (first fill), "strokes/0/color", "opacity", "width", "height", "cornerRadius", "paddingLeft", "itemSpacing".
// explicitMode: pin a variable mode on this node. Use { collectionName, modeName } (preferred) or { collectionId, modeId }.
// properties: escape hatch — set any Figma node property directly. Use only when no dedicated field exists.
interface Node {
  id: string; name: string; type: string;
  visible?: boolean;       // omitted when true
  locked?: boolean;        // omitted when false
  opacity?: number;        // omitted when 1
  rotation?: number;       // omitted when 0
  blendMode?: string;      // omitted when PASS_THROUGH
  layoutPositioning?: "AUTO" | "ABSOLUTE";
  layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";
  layoutSizingVertical?: "FIXED" | "HUG" | "FILL";
  minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number;
  absoluteBoundingBox: { x: number; y: number; width: number; height: number };
  fills?: Paint[];         // solid: {type: "SOLID", color: {r, g, b, a}}
  strokes?: Paint[];
  effects?: Effect[];      // DROP_SHADOW | INNER_SHADOW | LAYER_BLUR | BACKGROUND_BLUR
  children?: NodeStub[];   // stubs: {id, name, type} — use depth to expand
}
// PatchItem uses flat params matching create shape — no nested sub-objects.
// Fill/stroke/corner/layout/text params are identical to frames.create and text.create.
// Unknown keys produce a warning, preventing silent failures.
// Instances are linked copies of components. Changes to the component propagate to all instances.
// Overrides: instance-level changes (text, fills, visibility) that differ from the component. Shown in overrides array.
// variantProperties: when creating from a component set, pick which variant e.g. {"Style":"Secondary","Size":"Large"}.
// ---
// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call instances.get(id) to discover exact keys before update.
// swap: change which component an instance points to while preserving compatible overrides.
// detach: permanently converts an instance to a regular frame, breaking the component link.
// reset_overrides: reverts all instance overrides to match the main component.
// Workflow (local components): components.list → instances.create with componentId + properties (one call).
// Workflow (external/published libraries): library(method:"components", query:"...") → instances.create with componentName + properties. The MCP resolves componentName → key and imports via figma.importComponentByKeyAsync — the raw key never enters agent context.
// Instances support frame-level overrides: layoutSizingHorizontal/Vertical (FIXED, FILL, HUG), opacity, width/height, min/max.
// Use layoutSizingHorizontal: "FILL" to make instances stretch in auto-layout parents.

11 methods available.

list

readinherited

Search for nodes (returns stubs only — use get with depth for full properties)

Parameter	Type	Required	Description
query	string	✗	Name search query (case-insensitive substring match)
types	string[]	✗	Filter by node types (e.g. ["FRAME", "TEXT"])
parentId	string	✗	Search only within this subtree
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
offset	number	✗	Skip N items for pagination (default 0) (default: 0)
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Paginated node search results (uses results not items)

Field	Type	Description
totalCount	number	Total matching nodes
returned	number	Nodes in this page
offset	number
limit	number
results	object[]	Matching node stubs
↳ id	string
↳ name	string
↳ type	string
↳ parentId	string
↳ parentName	string
↳ bounds	object
↳ x	number
↳ y	number
↳ width	number
↳ height	number

delete

editinherited

Delete nodes

Parameter	Type	Required	Description
id	string	✗	Single node ID
items	object[]	✗	Batch: [{id}, ...]
↳ id	string	✗

Response

Field	Type	Description
results	string[]	Array of "ok" per item

clone

createinherited

Duplicate nodes — produces a same-type copy (frame→frame, instance→instance, component→component). Instance clones reference the same source component; they do not duplicate the component definition.

Parameter	Type	Required	Description
id	string	✗	Node ID
name	string	✗	Rename the clone (set before appending to parent — required when cloning a variant into its component set to avoid duplicate names)
parentId	string	✗	Parent node ID. Omit to place at current page root.
x	number	✗	X position (default: 0)
y	number	✗	Y position (default: 0)
items	object[]	✗	Batch: [{id, name?, parentId?, x?, y?}, ...]. Alternative to single-item params.
↳ id	string	✓	Node ID to clone
↳ name	string	✗	Rename the clone
↳ parentId	string	✗	Target parent
↳ x	number	✗
↳ y	number	✗
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

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

audit

readinherited

Run lint on a node — returns severity-ranked findings

Parameter	Type	Required	Description
id	string	✓	Node ID to audit
rules	string[]	✗	Rules to check. Default: ["all"]. Categories: "component", "composition", "token", "naming", "wcag".
maxDepth	number	✗	Max tree depth (default: 10)
maxFindings	number	✗	Max findings (default: 50)
minSeverity	"error" | "unsafe" | "heuristic" | "style" | "verbose"	✗	Minimum severity to report (default: style). Set to 'verbose' to include AAA contrast and line-height checks.
skipInstances	boolean	✗	Skip instance internals — findings inside instances are owned by the component (default: true)

Response

Field	Type	Description
nodeId	string
nodeName	string
categories	array	Sorted by severity (error > unsafe > heuristic > style)

reparent

editinherited

Move nodes into a new parent

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, parentId, index?}
↳ id	string	✓
↳ parentId	string	✓
↳ index	number	✗

Response

Field	Type	Description
results	string[]	Array of "ok" per item

get

read

Get instance detail with component properties and overrides

Parameter	Type	Required	Description
id	string	✓	Instance node ID
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.
verbose	boolean	✗	Include all properties (bounding box, constraints, text style details). Default false — returns slim, actionable output.

Response

Field	Type	Description
results	array	Serialized node(s) with componentProperties, overrides
_truncated	boolean

create

create

Create component instances

Parameter	Type	Required	Description
items	object[]	✓	Array of {componentId, variantProperties?, x?, y?, parentId?, layoutSizingHorizontal?, ...}
↳ visible	boolean	✗	Show/hide (default true)
↳ locked	boolean	✗	Lock/unlock (default false)
↳ opacity	token	✗	Opacity (0-1) or variable name
↳ 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"	✗
↳ effectStyleName	string	✗	Effect style name (e.g. 'Shadow/Card') for shadows, blurs
↳ layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
↳ layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
↳ layoutPositioning	"AUTO" | "ABSOLUTE"	✗	ABSOLUTE = floating inside auto-layout parent
↳ minWidth	number	✗	Min width for responsive auto-layout
↳ maxWidth	number	✗	Max width for responsive auto-layout
↳ minHeight	number	✗	Min height for responsive auto-layout
↳ maxHeight	number	✗	Max height for responsive auto-layout
↳ componentId	string	✗	Local component or component set ID. Pass this OR componentKey.
↳ componentKey	string	✗	Published library component key — imports from a team library via importComponentByKeyAsync. Discover keys via library(method:"components", ...); the library tool auto-resolves names → keys so you normally pass componentName instead.
↳ componentName	string	✗	Name of a component previously discovered via the library tool. Resolved to a componentKey MCP-side — the agent never handles the raw key. Preferred over componentKey for context hygiene.
↳ sizing	"contextual"	✗	"contextual": infer FILL/HUG from parent layout (e.g. FILL horizontally in a VERTICAL auto-layout parent). Omit to inherit sizing from the component definition.
↳ variantProperties	object	✗	Pick variant e.g. {"Style":"Secondary"}
↳ properties	object	✗	Set component properties inline e.g. {"Label":"Click me", "ShowIcon":true}. Same as instances.update properties.
↳ name	string	✗	Instance layer name
↳ x	number	✗
↳ y	number	✗
↳ width	number	✗	Override width (resize)
↳ height	number	✗	Override height (resize)
↳ explicitMode	object	✗	Pin variable mode at creation — use { collectionName, modeName } (preferred) or { collectionId, modeId }. Useful for library components with Light/Dark modes.
↳ parentId	string	✗	Parent node ID. Omit to place at current page root.
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

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

update

edit

Set instance properties

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, properties: {"Label#1:0":"text"}, fillColor?: ...}
↳ fills	array	✗	Fill paints array — e.g. [{type: 'SOLID', color: '#hex'}] or [] for transparent. Primary way to set fills.
↳ fillColor	string	✗	Shorthand — sets a single solid fill (auto-binds to matching variable/style)
↳ fillStyleName	string	✗	Paint style name for fill
↳ fillVariableName	string	✗	Color variable by name e.g. 'bg/primary'
↳ strokes	array	✗	Stroke paints array — e.g. [{type: 'SOLID', color: '#hex'}] or [] to clear. Primary way to set strokes.
↳ strokeColor	string	✗	Shorthand — sets a single solid stroke (auto-binds to matching variable/style)
↳ strokeStyleName	string	✗	Paint style name for stroke
↳ strokeVariableName	string	✗	Color variable by name for stroke
↳ strokeWeight	token	✗	All sides (number) or variable name (string). Per-side: strokeTopWeight, strokeBottomWeight, strokeLeftWeight, strokeRightWeight.
↳ strokeTopWeight	token	✗
↳ strokeBottomWeight	token	✗
↳ strokeLeftWeight	token	✗
↳ strokeRightWeight	token	✗
↳ strokeAlign	"INSIDE" | "OUTSIDE" | "CENTER"	✗	Stroke position (default: INSIDE)
↳ cornerRadius	token	✗	All corners (number) or variable name (string). Per-corner: topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius.
↳ topLeftRadius	token	✗
↳ topRightRadius	token	✗
↳ bottomRightRadius	token	✗
↳ bottomLeftRadius	token	✗
↳ visible	boolean	✗	Show/hide (default true)
↳ locked	boolean	✗	Lock/unlock (default false)
↳ opacity	token	✗	Opacity (0-1) or variable name
↳ 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"	✗
↳ effectStyleName	string	✗	Effect style name (e.g. 'Shadow/Card') for shadows, blurs
↳ layoutMode	"NONE" | "HORIZONTAL" | "VERTICAL"	✗	Layout direction (default: NONE)
↳ layoutWrap	"NO_WRAP" | "WRAP"	✗	Wrap children to new rows (HORIZONTAL layout only — Figma does not support WRAP on VERTICAL layouts). Use column frames inside a HORIZONTAL parent for vertical grid patterns.
↳ padding	token	✗	All edges (number) or variable name (string). Per-edge: paddingTop, paddingRight, paddingBottom, paddingLeft.
↳ paddingTop	token	✗
↳ paddingRight	token	✗
↳ paddingBottom	token	✗
↳ paddingLeft	token	✗
↳ primaryAxisAlignItems	"MIN" | "MAX" | "CENTER" | "SPACE_BETWEEN"	✗
↳ counterAxisAlignItems	"MIN" | "MAX" | "CENTER" | "BASELINE"	✗
↳ itemSpacing	token	✗	Spacing between children (number or variable name string, default: 0)
↳ counterAxisSpacing	token	✗	Gap between wrapped rows (requires layoutWrap: WRAP)
↳ strokesIncludedInLayout	boolean	✗	Include stroke width in layout measurements (default: false)
↳ layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
↳ layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
↳ layoutPositioning	"AUTO" | "ABSOLUTE"	✗	ABSOLUTE = floating inside auto-layout parent
↳ minWidth	number	✗	Min width for responsive auto-layout
↳ maxWidth	number	✗	Max width for responsive auto-layout
↳ minHeight	number	✗	Min height for responsive auto-layout
↳ maxHeight	number	✗	Max height for responsive auto-layout
↳ fontSize	number	✗	Font size
↳ fontFamily	string	✗	Font family
↳ fontStyle	string	✗	Font variant e.g. "Bold", "Italic" — overrides fontWeight
↳ fontWeight	number	✗	100-900. Ignored when fontStyle is set.
↳ lineHeight	any	✗	number | {value, unit: "PIXELS"|"PERCENT"|"AUTO"}
↳ letterSpacing	any	✗	number | {value, unit: "PIXELS"|"PERCENT"}
↳ textCase	"ORIGINAL" | "UPPER" | "LOWER" | "TITLE" | "SMALL_CAPS" | "SMALL_CAPS_FORCED"	✗
↳ textDecoration	"NONE" | "UNDERLINE" | "STRIKETHROUGH"	✗
↳ fontColor	string	✗	Shorthand — sets text color (auto-binds to matching variable/style)
↳ fontColorVariableName	string	✗	Bind color variable by name e.g. 'text/primary'
↳ fontColorStyleName	string	✗	Apply paint style — overrides fontColor
↳ textStyleId	string	✗	Apply text style by ID — overrides fontSize/fontWeight
↳ textStyleName	string	✗	Text style by name (case-insensitive)
↳ textAlignHorizontal	"LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED"	✗
↳ textAlignVertical	"TOP" | "CENTER" | "BOTTOM"	✗
↳ textAutoResize	"NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT" | "TRUNCATE"	✗
↳ id	string	✓	Instance node ID
↳ properties	object	✗	Component property key→value map
↳ componentProperties	object	✗	Alias for properties (matches instances.get response shape)
↳ name	string	✗	Rename node
↳ rotation	number	✗	Degrees (0-360)
↳ x	number	✗
↳ y	number	✗
↳ width	number	✗
↳ height	number	✗
↳ clearFill	boolean	✗	Remove all fills
↳ effects	object[]	✗	Effect array (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR)
↳ constraints	object	✗
↳ horizontal	"MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE"	✗
↳ vertical	"MIN" | "CENTER" | "MAX" | "STRETCH" | "SCALE"	✗
↳ bindings	object[]	✗	Bind variables to properties. field path examples: 'fills/0/color', 'strokes/0/color', 'opacity', 'width', 'cornerRadius', 'itemSpacing'.
↳ field	string	✓
↳ variableName	string	✗
↳ variableId	string	✗
↳ explicitMode	object	✗	Pin variable mode — use { collectionName, modeName } (preferred) or { collectionId, modeId }
↳ exportSettings	object[]	✗	Export settings

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

swap

edit

Swap instance component (preserves overrides)

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, componentId}
↳ id	string	✓	Instance node ID
↳ componentId	string	✓	New component or component set ID

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

detach

edit

Detach instances from their component (converts to frame)

Parameter	Type	Required	Description
items	object[]	✓	Array of {id}
↳ id	string	✓	Instance node ID

Response

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

reset_overrides

edit

Reset all overrides on instances to match their main component

Parameter	Type	Required	Description
items	object[]	✓	Array of {id}
↳ id	string	✓	Instance node ID

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item