Components

创建和管理可复用组件和变体集。

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.
// Components are reusable design elements. Instances stay linked to the component and inherit changes.
// Workflow: create component (with properties) → add children → create instances via instances.create.
// ---
// A component set (variant set) groups related components as variants (e.g. Button/Primary, Button/Secondary).
// Property types: BOOLEAN (toggle visibility), TEXT (editable text), INSTANCE_SWAP (swap child instance), VARIANT (variant picker).
// exposeText: when creating from_node, text children become editable TEXT properties on the component.
// Auto-bind: TEXT properties auto-bind to text children with matching names (case-insensitive).
// Example: properties:[{propertyName:"Label", type:"TEXT", defaultValue:"Click"}] binds to a child text node named "Label".
// text.create accepts componentPropertyName to bind on creation — walks up ancestors to find the nearest component.
//   For nested text (text inside frames inside a component), componentPropertyName resolves via ancestor walk. Alternatively, pass componentId explicitly.
//   For existing nodes with many text children, prefer components(method:"create", type:"from_node", exposeText:true) — it auto-discovers, creates TEXT properties, and binds all text nodes in one operation.
// Property keys: read returns clean names ("Label"), write requires the #suffix ("Label#1:0"). Call components.get(id) to discover exact keys before edit/delete.
// ComponentItem accepts the same params as FrameItem (layout, fill, stroke, sizing, min/max).
// A component IS a frame — create it directly with all layout properties, then add children.
// SIZING: Components with text need a width constraint — set width + layoutSizingHorizontal:"FIXED".
//   Without it, text won't wrap and the component grows unboundedly.
//   HUG on both axes is only correct for intrinsically-sized elements (buttons, badges, icons).
// action: "add" (default) — requires type + defaultValue. "edit" — pass defaultValue to change value, name to rename property. "delete" — just propertyName#suffix.
// action: "rename_variant" — renames a variant option VALUE (not the property). Pass defaultValue=current option name, name=new option name.
// For VARIANT properties: "edit" with defaultValue reorders children to set the default variant.
// Adding variants: clone an existing variant into the set with a new name. See guidelines(topic:"component-structure") for workflow.

9 methods available.

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

list

read

List local component names (variant sets as single entries)

Parameter	Type	Required	Description
query	string	✗	Name search query (case-insensitive substring match)
offset	number	✗	Skip N items for pagination (default 0) (default: 0)
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Field	Type	Description
totalCount	number	Total matching items
returned	number	Items in this page
offset	number
limit	number
items	object[]

get

read

Get component detail — property definitions + optional node tree for structural inspection

Parameter	Type	Required	Description
id	string	✗	Component or component set ID
names	string[]	✗	Batch lookup by name (case-insensitive). Either id or names is required.
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	object[]	Component summaries (without depth) or full node trees with properties merged (with depth)
↳ id	string
↳ name	string
↳ description	string
↳ properties	object	Property definitions — {name: {type, defaultValue, options?}}
_truncated	boolean

Example response

{
  "results": [
    {
      "id": "1:23",
      "name": "Push Button",
      "properties": {
        "Label": {
          "type": "TEXT",
          "defaultValue": "Button"
        },
        "Style": {
          "type": "VARIANT",
          "defaultValue": "Primary",
          "options": [
            "Primary",
            "Secondary"
          ]
        },
        "Size": {
          "type": "VARIANT",
          "defaultValue": "Medium",
          "options": [
            "Small",
            "Medium",
            "Large"
          ]
        }
      }
    }
  ]
}

create

create

Create components

No parameters.

Discriminated by type. Available types:

component

Create component with full frame properties (layout, fill, stroke, sizing). A component IS a frame — build directly, no need to create a frame first.

Parameter	Type	Required	Description
name	string	✓	Component name
parentId	string	✗	Parent node ID. Omit to place at current page root.
x	number	✗	X position (default: 0)
y	number	✗	Y position (default: 0)
width	number	✗	Width in px (omit to shrink-to-content via HUG)
height	number	✗	Height in px (omit to shrink-to-content via HUG)
rotation	number	✗	Rotation in degrees (0-360)
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
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'
imageUrl	string	✗	Image source — 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
imageScaleMode	"FILL" | "FIT" | "CROP" | "TILE"	✗	How the image is scaled within the frame (default: FILL)
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	✗
layoutMode	"NONE" | "HORIZONTAL" | "VERTICAL"	✗	Layout direction (default: auto — NONE when width+height set, otherwise inferred from layout props)
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)
overflowDirection	"NONE" | "HORIZONTAL" | "VERTICAL" | "BOTH"	✗	Scroll overflow in prototype (default: NONE)
layoutPositioning	"AUTO" | "ABSOLUTE"	✗	ABSOLUTE = floating inside auto-layout parent
layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
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
annotations	object[]	✗	Set annotations — [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
description	string	✗	Component description (shown in Figma's component panel)
children	object[]	✗	Inline child nodes — build nested trees in one call. Types: text: {type:"text", text, componentPropertyName?, fontFamily?, fontSize?, fontWeight?, fontStyle?, fontColor?, layoutSizingHorizontal?}. frame: {type:"frame", name?, layoutMode?, fillColor?, width?, layoutSizingHorizontal?, children?}. instance: {type:"instance", componentId, componentPropertyName?, variantProperties?, properties?}. component: {type:"component", name, children?}. All params from text/frame endpoints are supported on their respective types. componentPropertyName auto-creates and binds a TEXT (text) or INSTANCE_SWAP (instance) property. Always set layoutSizingHorizontal + layoutSizingVertical on children inside auto-layout parents (FILL, HUG, or FIXED). Example: children:[{type:"text", text:"Label", componentPropertyName:"Label", fontSize:14, fontColorVariableName:"text/primary", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}, {type:"frame", name:"Actions", layoutMode:"HORIZONTAL", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG", itemSpacing:8, children:[{type:"instance", componentId:"1:2", componentPropertyName:"Action", layoutSizingHorizontal:"FILL", layoutSizingVertical:"HUG"}]}]
properties	object[]	✗	Component properties to define at creation: [{propertyName, type, defaultValue}]. TEXT properties for inline children with componentPropertyName are created automatically.
↳ propertyName	string	✓	Property name
↳ type	"BOOLEAN" | "TEXT" | "INSTANCE_SWAP"	✓	Property type
↳ defaultValue	string | boolean	✓	Default value
↳ preferredValues	array	✗	Preferred values for INSTANCE_SWAP

from_node

Convert existing nodes to components. Text children auto-exposed as editable properties (exposeText: true).

Parameter	Type	Required	Description
nodeId	string	✓	Node ID to convert
name	string	✗	Rename the component (default: keeps the node's current name)
exposeText	boolean	✗	Auto-expose text as editable properties (default: true)

variant_set

Combine components into a variant set. The resulting set is a frame — accepts all frame properties for layout/styling.

Parameter	Type	Required	Description
name	string	✗	Node name
parentId	string	✗	Parent node ID. Omit to place at current page root.
x	number	✗	X position (default: 0)
y	number	✗	Y position (default: 0)
width	number	✗	Width in px (omit to shrink-to-content via HUG)
height	number	✗	Height in px (omit to shrink-to-content via HUG)
rotation	number	✗	Rotation in degrees (0-360)
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
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'
imageUrl	string	✗	Image source — 'pexel:<id>' for Pexels photos, a public URL, or a local file path. SVGs are inserted as vectors; raster images become IMAGE fills.
imageScaleMode	"FILL" | "FIT" | "CROP" | "TILE"	✗	How the image is scaled within the frame (default: FILL)
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	✗
layoutMode	"NONE" | "HORIZONTAL" | "VERTICAL"	✗	Layout direction (default: auto — NONE when width+height set, otherwise inferred from layout props)
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)
overflowDirection	"NONE" | "HORIZONTAL" | "VERTICAL" | "BOTH"	✗	Scroll overflow in prototype (default: NONE)
layoutPositioning	"AUTO" | "ABSOLUTE"	✗	ABSOLUTE = floating inside auto-layout parent
layoutSizingHorizontal	"FIXED" | "HUG" | "FILL"	✗
layoutSizingVertical	"FIXED" | "HUG" | "FILL"	✗
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
annotations	object[]	✗	Set annotations — [{label?, labelMarkdown?, properties?, categoryId?}]. Properties validated per node type.
componentIds	string[]	✗	Existing component IDs to combine (min 2). Alternative to children.
variantPropertyName	string	✗	Rename the auto-generated variant property (default: 'Property 1')
children	object[]	✗	Inline variant components. Each must be {type:"component", name, children?, ...frame_params}. All variants must share the same child structure. Alternative to componentIds — do not combine both.

Response

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

commit

edit

Commit a staged component — unwraps from [STAGED] container into the original target location.

Parameter	Type	Required	Description
id	string	✓	Staged node ID to commit

Response

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

update

edit

Add, edit, or delete component properties

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, propertyName, action?, type?, defaultValue?, name?, preferredValues?}
↳ id	string	✓	Component or component set ID
↳ propertyName	string	✓	Property name with #suffix for edit/delete (e.g. "Label#1:0"). Call components.get to find exact keys. For add, plain name works.
↳ action	"add" | "edit" | "delete" | "rename_variant"	✗	"add" (default): requires type + defaultValue. "edit": pass defaultValue to change default, name to rename property. "delete": just propertyName. "rename_variant": pass defaultValue=current option name, name=new option name.
↳ type	"BOOLEAN" | "TEXT" | "INSTANCE_SWAP" | "VARIANT"	✗	Property type (required for add)
↳ defaultValue	string | boolean	✗	Default value (add/edit). For rename_variant: the CURRENT option name to rename
↳ name	string	✗	New name — for edit: renames the property itself, for rename_variant: the new option value name
↳ preferredValues	array	✗	Preferred values for INSTANCE_SWAP
depth	number	✗	Response detail: omit for id+name only. 0=properties + child stubs. N=recurse N levels. -1=unlimited.

Response

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

delete

edit

Delete components or component sets

Parameter	Type	Required	Description
id	string	✓	Component or component set ID

Response

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