Styles

管理本地颜色、文字、效果和网格样式。

Type reference

// Styles are named, reusable design properties that can be applied to nodes. Four types:
//   paint: named PaintStyle.paints (applied to fills/strokes), text: typography settings, effect: shadows/blurs, grid: layout grids.
// All ID params accept both IDs and display names (case-insensitive). Use whichever you have.
// ---
// leadingTrim: "CAP_HEIGHT" trims line-height to cap height (tighter text boxes), "NONE" is default.
// fontStyle: font variant name like "Bold", "Italic", "Bold Italic". Use fonts.list to find available styles.
// Paint styles: create/update paints: Paint[] authoring accepts only SOLID and gradients (GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND).
// Use gradientTransform + gradientStops; for a basic left-to-right gradient use gradientTransform:[[1,0,0],[0,1,0]]. Do not use CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables.
// styles.get/list readback may include IMAGE/VIDEO/PATTERN metadata from existing Figma content, but those are readback-only and cannot be passed back to create/update Paint[] authoring. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here.
// For VariableAlias ids in Paint[] (SOLID boundVariables.color or gradientStops[].boundVariables.color), inspect variables.get/list or variable_collections.get. Prefer colorVariableName/fillVariableName where available.
// Backward-compatible color/colorVariableName create/update shorthands still create a single SOLID paint.
//
// Effect object shape (for effect styles):
//   { type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR",
//     color?: Color, offset?: {x, y}, radius: number, spread?: number,
//     visible?: boolean, blendMode?: string }
//   DROP_SHADOW/INNER_SHADOW require color, offset, radius. LAYER_BLUR/BACKGROUND_BLUR require radius only.
//   Example: { type: "DROP_SHADOW", color: "#00000040", offset: {x:0,y:4}, radius: 8 }
//
// LayoutGrid object shape (for grid styles) follows Figma Plugin API conditional shapes:
//   Grid: { pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color }
//   Rows/Columns: { pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"STRETCH"|"CENTER", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color }
//   Important: alignment:"STRETCH" must omit sectionSize because Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.
//   Examples: stretch columns {pattern:"COLUMNS", alignment:"STRETCH", count:12, gutterSize:24, offset:80}; fixed columns {pattern:"COLUMNS", alignment:"MIN", count:12, gutterSize:24, offset:80, sectionSize:72}; square grid {pattern:"GRID", sectionSize:8}.
// 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.
// Effect: {type: "DROP_SHADOW"|"INNER_SHADOW"|"LAYER_BLUR"|"BACKGROUND_BLUR", radius: number, color?: {r,g,b,a} (0-1), offset?: {x, y}, spread?: number, visible?: boolean}
// 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.
// LayoutGrid is conditional: GridLayoutGrid {pattern:"GRID", sectionSize:number, visible?:boolean, color?:Color}; RowsColsLayoutGrid {pattern:"ROWS"|"COLUMNS", alignment?:"MIN"|"MAX"|"CENTER"|"STRETCH", gutterSize?:number, count?:number, offset?:number, sectionSize?:number, visible?:boolean, color?:Color}. For alignment:"STRETCH", omit sectionSize; Figma computes stretched row/column sizes. Use sectionSize only with fixed rows/columns (MIN/MAX/CENTER) or GRID.

5 methods available.

list

read

List local styles with optional type filter

Parameter	Type	Required	Description
type	"paint" | "text" | "effect" | "grid"	✗	Filter by style type
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

Field	Type	Description
totalCount	number	Total matching items
returned	number	Items in this page
offset	number
limit	number
items	object[]
↳ id	string
↳ name	string
↳ type	string

get

read

Get full style detail by ID

Parameter	Type	Required	Description
id	string	✓	Style ID or name
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.

Response

Field	Type	Description
id	string
name	string
type	string	PAINT | TEXT | EFFECT | GRID
paints	object[]	PaintStyle.paints for PAINT styles. Readback returns Figma Plugin API Paint[]; gradients include gradientTransform, gradientStops, opacity/blendMode, and stop boundVariables. Existing Figma content may return IMAGE/VIDEO/PATTERN metadata, but those are readback-only and cannot be passed to create/update Paint[] authoring, which accepts only SOLID and gradients.
boundVariables	object	PaintStyle.boundVariables, e.g. {paints:[{type:'VARIABLE_ALIAS', id:'...'}]}
fontFamily	string	Font family (TEXT styles)
fontSize	number	Font size (TEXT styles)
effects	array	Effects array (EFFECT styles)
layoutGrids	array	Layout grids (GRID styles)

create

create

Create local styles

Example

styles(method:"create", type:"paint", items:[{name:"Gradient/Primary", paints:[{type:"GRADIENT_LINEAR", gradientTransform:[[1,0,0],[0,1,0]], gradientStops:[{position:0,color:"#7D58ED"},{position:1,color:"#207CE5"}]}]}])

Type-specific fields go inside items[]; do not pass them at the top level.

Parameter	Type	Required	Description
type	"paint" | "text" | "effect" | "grid"	✓	Selects which item shape to use
items	object[]	✓	One or more type-specific item objects. Put fields from the selected type table inside each item; do not pass them at top level.

Discriminated by type. Available types:

Each table below describes one object inside items[] for that type.

paint

Paint/color style

styles(method:"create", type:"paint", items:[{name:"Surface/Primary", colorVariableName:"bg/surface"}])

Parameter	Type	Required	Description
name	string	✓	Style name
paints	object[]	✗	PaintStyle.paints authoring array. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName shorthands. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"create").
color	string	✗	Single-solid shorthand color. Optional when colorVariableName or paints is provided.
colorVariableName	string	✗	Single-solid shorthand: bind to a COLOR variable by name (style tracks the variable). Can be used alone — color is resolved from the variable.
description	string	✗	Style description

text

Text style

styles(method:"create", type:"text", items:[{name:"Heading/Medium", fontFamily:"Inter", fontStyle:"Medium", fontSize:20, lineHeight:{value:28, unit:"PIXELS"}}, {name:"Body/Regular", fontFamily:"Inter", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}, {name:"Body/Medium", fontFamily:"Inter", fontStyle:"Medium", fontSize:14, lineHeight:{value:20, unit:"PIXELS"}}])

Parameter	Type	Required	Description
name	string	✓	Style name
fontFamily	string	✓	Font family
fontStyle	string	✗	Font style (default: Regular)
fontSize	number	✓	Font size
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"	✗
paragraphIndent	number	✗	Paragraph indent (px)
paragraphSpacing	number	✗	Paragraph spacing (px)
leadingTrim	"CAP_HEIGHT" | "NONE"	✗	Leading trim mode
description	string	✗	Style description

effect

Effect style

styles(method:"create", type:"effect", items:[{name:"Shadow/Medium", effects:[{type:"DROP_SHADOW", color:"#00000040", offset:{x:0,y:4}, radius:8}]}])

Parameter	Type	Required	Description
name	string	✓	Style name
effects	array	✓	Array of Effect objects
description	string	✗	Style description

grid

Grid/layout grid style

styles(method:"create", type:"grid", items:[{name:"Grid/Desktop 12", layoutGrids:[{pattern:"COLUMNS", alignment:"STRETCH", count:12, gutterSize:24, offset:80}]}])

Parameter	Type	Required	Description
name	string	✓	Style name
layoutGrids	array	✓	Array of LayoutGrid objects. Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize.
description	string	✗	Style description

Response

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

update

edit

Update styles by ID or name

Example

styles(method:"update", items:[{id:"Gradient/Primary", paints:[{type:"GRADIENT_LINEAR", gradientTransform:[[1,0,0],[0,1,0]], gradientStops:[{position:0,color:"#7D58ED"},{position:1,color:"#207CE5"}]}]}])

Parameter	Type	Required	Description
type	"paint" | "text" | "effect" | "grid"	✗	Style type hint for strict validation (optional, auto-detected)
items	object[]	✓	Array of {id, ...fields} to update
↳ id	string	✓	Style ID or name
↳ name	string	✗	Rename the style
↳ description	string	✗	Style description
↳ paints	object[]	✗	Replace PaintStyle.paints. Accepts only SOLID and GRADIENT_LINEAR/RADIAL/ANGULAR/DIAMOND, using gradientTransform + gradientStops, opacity/blendMode, and gradientStops[].boundVariables.color. Mutually exclusive with color/colorVariableName. Do not pass IMAGE/VIDEO/PATTERN, CSS gradients, REST gradientHandlePositions, or top-level gradient boundVariables. Use imageUrl/images for image authoring on nodes; VIDEO/PATTERN authoring is not supported here. For examples call styles(method:"help", topic:"update").
↳ color	string	✗	New single-solid color shorthand (paint styles)
↳ colorVariableName	string	✗	Bind to a COLOR variable by name using single-solid shorthand (paint styles)
↳ fontFamily	string	✗
↳ fontStyle	string	✗
↳ fontSize	number	✗
↳ 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"	✗
↳ paragraphIndent	number	✗	Paragraph indent (px)
↳ paragraphSpacing	number	✗	Paragraph spacing (px)
↳ leadingTrim	"CAP_HEIGHT" | "NONE"	✗
↳ effects	array	✗	Array of Effect objects
↳ layoutGrids	array	✗	Array of LayoutGrid objects (grid styles). Conditional shapes: GRID requires sectionSize and does not use alignment/count/gutterSize/offset; ROWS/COLUMNS use alignment/count/gutterSize/offset, and sectionSize only for fixed alignments MIN/MAX/CENTER. For alignment:STRETCH, omit sectionSize.

Response

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

delete

edit

Delete styles

Parameter	Type	Required	Description
id	string	✗	Style ID or name
items	object[]	✗	Batch: [{id}, ...]
↳ id	string	✓	Style ID or name

Response

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