Kimi Design API Reference

@taco-slides/model TypeScript

556 of 633 exports documented · outline

The model package is the framework-neutral source of truth for a Kimi Design document. It defines the document types, loads and saves them, validates them, and records every edit as a list of operations with undo history. It contains no editor, renderer, or network code.

A document is normalized into flat maps keyed by ID: pageOrder, pages, nodes, and assets, plus a theme. Each page points to one root frame or group that never clips, so the page is an unbounded canvas. Containers own an ordered children list. Parent pointers are not stored, so the hierarchy has one source of truth. assertDocument rejects missing nodes, cycles, shared children, unreachable nodes, broken references, and malformed geometry.

Values returned by this package are deeply frozen. To change a document, pass DocumentOperations to applyOperations, or dispatch them to a DocumentStore, which also keeps the commit history used for undo, redo and branches.

Current versions

The versions this package writes today, read from the source when the page is built.

Documents and pages

A DesignDocument holds every page, node, asset and theme resource. Pages are ordered by pageOrder, and each page names its root node.

type DesignDocument = DesignDocumentV1

source

A Kimi Design document. Values returned by this package are deeply frozen; change one with applyOperations or through a DocumentStore.

interface DesignDocumentV1

source

The stored shape of a document at CURRENT_DOCUMENT_SCHEMA_VERSION. Use the DesignDocument alias in code.

The data is normalized into flat maps keyed by ID. assertDocument checks that every page root exists, every node is reachable from exactly one page and has at most one parent, there are no cycles, and that style, variable, connector, media-node and font references resolve. (ImagePaint.assetId is not checked against the asset map.)

readonly schemaVersion: typeof CURRENT_DOCUMENT_SCHEMA_VERSIONsource

readonly id: DocumentIdsource

readonly title: stringsource

readonly pageOrder: readonly PageId[]source

Every page ID exactly once, in display order.

readonly pages: Readonly<Record<string, Page>>source

readonly nodes: Readonly<Record<string, SceneNode>>source

Every node on every page, keyed by NodeId.

readonly assets: Readonly<Record<string, Asset>>source

Images, videos and fonts, keyed by AssetId.

readonly theme: DocumentThemesource

readonly components?: Readonly<Record<string, ComponentDefinition>>since 0.23.0source

Reusable layer trees, keyed by ComponentId. Omitted when empty. Each component’s layers live in nodes under its rootId, on no page.

readonly metadata?: Readonly<Record<string, JsonValue>>source

Free-form JSON data kept with the document. The model does not read it.

interface Page

source

One page of the document. A page is an unbounded canvas: its root container never clips, so top-level nodes may lie anywhere, and the root’s frame only records the visible extent (see pageRootFrame).

readonly id: PageIdsource

Matches the page’s key in DesignDocument.pages.

readonly name: stringsource

Must not be empty.

readonly rootId: NodeIdsource

The page’s root node: a frame or group with no parent.

readonly guides?: readonly Guide[]since 0.11.0source

Ruler guides on the page’s canvas, in page coordinates. Omitted when empty.

readonly variableModes?: VariableModessince 0.26.0source

The page’s mode per variable collection. Layers set to Auto inherit it; a collection left out uses the collection’s activeModeId.

readonly metadata?: Readonly<Record<string, JsonValue>>source

interface Guide

since 0.11.0source

A ruler guide: an editor-only straight line used to position objects. The renderer never paints it, so it never appears in exports.

readonly axis: "x" | "y"source

“x” is a vertical line at x = offset; “y” is a horizontal line at y = offset.

readonly offset: numbersource

Position along the axis in document units, relative to whatever holds the guide: the page origin for a page guide, or the frame’s top-left corner for a frame guide.

type DocumentSchemaVersion = number | SemanticVersion

source

A document schema version. Current documents use a SemanticVersion; the number form is only read from legacy files saved before version 0.0.0.

type SemanticVersion = `${number}.${number}.${number}`

source

A major.minor.patch version string, such as "0.14.0".

const CURRENT_DOCUMENT_SCHEMA_VERSION: "0.27.0"

source

The schema version this package reads and writes. deserializeDocument migrates older documents to it, and assertDocument rejects any other version.

function pageRootFrame( document: DesignDocument, pageId: PageId ): Rect | undefined

source

A page root’s frame is the page’s visible extent: the area the editor fits on screen and the renderer sizes its scene to. Page roots never clip, so top-level nodes may lie outside it.

Scene nodes

SceneNode is a union told apart by type: frame, group, text, code, shape, image, video and connector. Shapes are further told apart by shape. Every node has the fields of NodeBase; every node but a path is also placed by a frame and rotation (FramedNodeBase).

type SceneNode = | FrameNode | GroupNode | TextNode | CodeNode | ShapeNode | ImageNode | VideoNode | ConnectorNode | InstanceNode

source

Any node in a page’s tree, told apart by its type field. Nodes live in the flat DesignDocument.nodes map; containers list their children by ID and parents are not stored.

interface NodeBase

source

Fields every SceneNode has.

readonly id: NodeIdsource

Matches the node’s key in DesignDocument.nodes.

readonly name: stringsource

The layer name. Must not be empty.

readonly visible: booleansource

readonly locked: booleansource

Protects the node from edits on the editor canvas.

readonly opacity: numbersource

From 0 (transparent) to 1 (opaque).

readonly blendMode?: BlendModesince 0.8.0source

How the node composites onto what lies behind it; normal when omitted.

readonly mask?: booleansince 0.8.0source

A mask hides its later siblings outside its own painted alpha and paints nothing itself. A hidden mask masks nothing.

readonly aspectRatioLocked?: booleansince 0.1.1source

Keeps width and height proportional when the node is resized.

readonly variableBindings?: VariableBindingssource

Properties whose values come from theme variables.

readonly exportSettings?: readonly ExportSetting[]since 0.14.0source

The node’s Export section rows, in order. Omitted when empty.

readonly expressions?: NodeExpressionssince 0.24.0source

Computed fields: expression source text keyed by field, for nodes under a component root only (see ComputableField and computableFieldsOf). The plain field keeps the base value, which the expression reads as stored and which is shown when the expression does not check. A field holds a variable binding or an expression, never both. Omitted when empty.

readonly condition?: stringsince 0.24.0source

A boolean expression; when it is false the layer and its sublayers are left out of every instance. Only on layers under a component root, never on the root itself. An expression that does not check counts as no condition.

readonly constraints?: ResizeConstraintssince 0.25.0source

How the layer follows its frame when the frame is resized (see ResizeConstraints). Omitted means Left and Top: the layer keeps its position and size. Used for children of frames without auto layout and for absolute children of auto layout frames; ignored elsewhere. Never on a group: constraints set on a group are set on its layers, as in Figma.

readonly layoutPositioning?: "absolute"since 0.25.0source

"absolute" takes a child of an auto layout frame out of the flow, like Figma’s “Ignore auto layout”: the layout neither moves it nor counts it when hugging, and it follows the frame’s size changes by its constraints. Ignored when the parent has no auto layout.

readonly variableModes?: VariableModessince 0.26.0source

The mode this layer and its sublayers use for each variable collection (see VariableModes). A collection left out is Auto: the layer inherits the mode from its parent. On an instance, the modes apply to the component’s layers, so two instances of one component can show two modes.

readonly metadata?: Readonly<Record<string, JsonValue>>source

Free-form JSON data kept with the node. The model does not read it.

interface FramedNodeBase extends NodeBase

source

Fields of every node placed by a rectangle: all kinds except PathNode, which uses a transform matrix instead.

readonly frame: Rectsource

Position and unrotated size, in the parent’s coordinate system (relative to the parent’s frame’s top-left corner).

readonly rotation: numbersource

Degrees, clockwise on screen, about the frame’s center.

readonly flipX?: booleansource

Mirrors the rendered node around its local horizontal center.

readonly flipY?: booleansource

Mirrors the rendered node around its local vertical center.

Together, frame, rotation and the flips place a local point $\mathbf{p}$ (origin at the frame’s top-left corner) in the parent as

$$\mathbf{p}_\text{parent} = \begin{bmatrix} x + w/2 \\ y + h/2 \end{bmatrix} + R_\theta F \left(\mathbf{p} - \begin{bmatrix} w/2 \\ h/2 \end{bmatrix}\right), \quad R_\theta = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix}, \quad F = \begin{bmatrix} \pm 1 & 0 \\ 0 & \pm 1 \end{bmatrix}$$

where $\theta$ is rotation in radians and $F$ has $-1$ on the axis of each flip that is set. The flip happens first, then the rotation.

readonly resizing?: NodeResizingsince 0.15.0source

Fill sizing and size limits. Omitted when empty.

type ContainerNode = FrameNode | GroupNode

source

Nodes that have children. Test with isContainerNode.

const isContainerNode: (node: SceneNode) => node is ContainerNode

source

True for frames and groups, the nodes that have children.

interface FrameNode extends FramedNodeBase

source

A container with its own size, fills, strokes and effects, and optionally an auto layout. Each page’s root is a frame or group; a page root never clips.

readonly type: "frame"source

readonly children: readonly NodeId[]source

Child node IDs in paint order: the first child is at the back.

readonly layout: Layoutsource

How children are positioned: freely, or by a stack or grid auto layout.

readonly style?: VisualStylesource

readonly clipContent?: booleansource

Hides the parts of children that fall outside the frame.

readonly guides?: readonly Guide[]since 0.11.0source

Ruler guides that belong to this frame and move with it. The editor shows them only on top-level frames that are neither rotated nor flipped. Omitted when empty.

interface GroupNode extends FramedNodeBase

source

A container with no size of its own: its frame is always fitted to the union of its children’s bounds (see fitGroupToChildren). A group whose last child is removed by applyOperations is removed too.

readonly type: "group"source

readonly variableBindings?: GroupVariableBindingssource

Properties whose values come from theme variables. A group’s size is computed from its layers, so it cannot bind width or height.

readonly children: readonly NodeId[]source

Child node IDs in paint order: the first child is at the back.

readonly clipContent?: booleansource

interface TextNode extends FramedNodeBase

source

A text box made of styled paragraphs.

readonly type: "text"source

readonly paragraphs: readonly TextParagraph[]source

readonly verticalAlign: "top" | "middle" | "bottom"source

Where the text sits in the frame when the frame is taller than the text.

readonly overflow: "clip" | "visible"source

Whether text that does not fit the frame is cut off or still drawn.

readonly autoResize: "none" | "height" | "width-and-height"source

none keeps both frame dimensions fixed, height keeps the width and lets the height follow the text, and width-and-height lets both follow.

readonly wrap: "none" | "word" | "character"source

Where long lines may break: never, between words, or between any characters.

type TextualNode = TextNode

source

Nodes that hold editable rich text. Currently only TextNode.

const isTextualNode: (node: SceneNode) => node is TextualNode

source

True for nodes that hold rich text (TextNode).

interface CodeNode extends FramedNodeBase

source

A block of source code. Syntax highlighting is worked out when rendering; only the raw source is stored.

readonly type: "code"source

readonly source: stringsource

readonly language: stringsource

The language identifier used for highlighting. Must not be empty.

readonly fontFamily: stringsource

Applied uniformly to the full source rather than to individual text runs.

readonly fontSize: numbersource

Applied uniformly to the full source rather than to individual text runs. Positive.

readonly codeStyleId?: CodeStyleIdsource

The theme code style; the theme’s defaultCodeStyleId when omitted.

readonly codeStyleOverrides?: Partial< Pick< CodeStyle, "lineHeight" | "letterSpacing" | "background" | "foreground" | "syntax" > >source

Values that replace the code style’s for this node only.

readonly lineNumbers: boolean | numbersource

False hides line numbers, true starts at one, and a number sets the first line.

readonly autoResize: "none" | "height" | "width-and-height"since 0.1.3source

Same meaning as TextNode.autoResize.

readonly wordWrap: booleansource

Wraps long source lines to the frame width.

readonly stroke?: Strokesince 0.1.4source

A stroke drawn around the code block.

readonly decorations: readonly CodeDecoration[]source

interface CodeDecoration

source

A marked range of a CodeNode’s source.

readonly from: numbersource

Start offset into source, in UTF-16 code units.

readonly to: numbersource

End offset (exclusive), from from up to the source length.

readonly kind: "emphasis" | "addition" | "deletion" | "annotation"source

readonly label?: stringsource

type ShapeNode = | RectangleNode | EllipseNode | PolygonNode | StarNode | LineNode | PathNode

source

Every node with type: "shape", told apart by its shape field.

interface RectangleNode extends FramedNodeBase

source

A rectangle filling its frame; VisualStyle.cornerRadius rounds it.

readonly type: "shape"source

readonly shape: "rectangle"source

readonly style: VisualStylesource

interface EllipseNode extends FramedNodeBase

source

An ellipse filling its frame, or an arc, pie or ring of one.

readonly type: "shape"source

readonly shape: "ellipse"source

readonly style: VisualStylesource

readonly arc?: EllipseArcsince 0.12.0source

Omitted draws the whole ellipse.

interface EllipseArc

since 0.12.0source

Turns an ellipse into an arc, pie or ring, as Figma’s arc data does. Angles are degrees measured clockwise from the positive x axis on the ellipse’s parametric angle. The sweep runs from the starting to the ending angle and is at most one full turn in either direction.

readonly startingAngle: numbersource

readonly endingAngle: numbersource

readonly innerRadius: numbersource

Inner radius as a fraction of the outer radius, from 0 (a pie) to below 1 (a ring).

interface PolygonNode extends FramedNodeBase

since 0.12.0source

A regular polygon whose points are scaled to fill the frame, first point at the top center, as Figma draws it.

readonly type: "shape"source

readonly shape: "polygon"source

readonly pointCount: numbersource

Whole number of corners from 3 to 60.

readonly style: VisualStylesource

interface StarNode extends FramedNodeBase

since 0.12.0source

A star whose outer and inner points are scaled to fill the frame.

readonly type: "shape"source

readonly shape: "star"source

readonly pointCount: numbersource

Whole number of outer points from 3 to 60.

readonly innerRadius: numbersource

Inner point distance as a fraction of the outer radius, from 0 to 1.

readonly style: VisualStylesource

interface LineNode extends FramedNodeBase

since 0.12.0source

A single straight stroke. Like Figma, the frame has zero height: the line runs from the frame’s local (0, 0) to (width, 0), and rotation turns it about the frame center. An arrow is a line with an arrow cap.

readonly type: "shape"source

readonly shape: "line"source

readonly style: VisualStylesource

readonly startCap: StrokeCapsource

readonly endCap: StrokeCapsource

interface PathNode extends NodeBase

source

An editable vector shape. Unlike the other shapes it has no frame or rotation: transform places the network in the parent, and its bounds are derived from the transformed network (see getNodeBounds).

readonly type: "shape"source

readonly shape: "path"source

readonly vectorNetwork: VectorNetworksince 0.2.0source

The path’s geometry.

readonly transform: TransformMatrixsource

Maps network coordinates into the parent’s coordinate system.

readonly style: VisualStylesource

readonly startCap?: StrokeCapsince 0.22.0source

The end points of an open path whose segments form one chain, each in order from the end of the one before (see openPathChainEnds): the start cap sits on the first segment’s start and the end cap on the last segment’s end, the same styles a line has. Omitted is round, which every path drew before 0.22.0. Closed paths and paths with branches or several chains ignore them, and so does a path with an inside or outside stroke.

readonly endCap?: StrokeCapsince 0.22.0source

interface ImageNode extends FramedNodeBase

source

A placed image. The pixels live in an ImageAsset.

readonly type: "image"source

readonly assetId: AssetIdsource

Must name an asset of kind image.

readonly fit: MediaFitsource

readonly crop?: Rectsource

The part of the source image to show, in source pixels.

readonly alt: stringsource

Alternative text for accessibility; may be empty.

interface VideoNode extends FramedNodeBase

source

A placed video. The file lives in a VideoAsset.

readonly type: "video"source

readonly assetId: AssetIdsource

Must name an asset of kind video.

readonly fit: MediaFitsource

readonly crop?: Rectsource

The part of the video frame to show, in source pixels.

readonly alt: stringsource

Alternative text for accessibility; may be empty.

type MediaFit = "contain" | "cover" | "fill"

source

How an image or video fills its frame, as in CSS object-fit.

interface ConnectorNode extends FramedNodeBase

source

A stroked line or arrow between two points, each optionally attached to a node.

readonly type: "connector"source

readonly start: ConnectorEndpointsource

readonly end: ConnectorEndpointsource

readonly routing: "straight" | "elbow" | "curve"source

readonly stroke: Strokesource

readonly startCap: StrokeCapsince 0.20.0source

The end styles, the same set a line has (STROKE_CAPS). Before 0.20.0 a connector had only "none", "arrow" and "dot"; loading an older document turns "arrow" into "triangle-arrow" and "dot" into "circle-arrow".

readonly endCap: StrokeCapsource

readonly cornerRadius?: numbersince 0.21.0source

How far, in pixels, each bend of an elbow connector is rounded, as Figma’s ConnectorNode.cornerRadius. A bend never rounds past half of either part of the line it joins, so a short part keeps a smaller curve. The ends and end styles are not rounded. Straight and curved connectors have no bends and ignore it. Missing means 0: sharp bends. Not negative.

readonly cornerSmoothing?: numbersince 0.21.0source

How far each rounded bend of an elbow connector eases into the line, from 0 (a circular arc) to 1 (a continuous curve), the same fraction as a rectangle’s NodeVisualStyle.cornerSmoothing and drawn the same way. A smoothed bend takes up to (1 + cornerSmoothing) * cornerRadius of each part of the line it joins, capped at half of the shorter part, which also caps the smoothing. It has no effect without a corner radius, or on straight and curved connectors. Figma’s ConnectorNode has no smoothing; this extends it. Missing means 0.

interface ConnectorEndpoint

source

One end of a ConnectorNode.

An end with nodeId attaches to that layer, and the page compiler places it from the layer’s frame each time, so it follows the layer when the layer moves or resizes. Where on the layer it goes is set by at most one of:

• side: the middle of that side, and an elbow connector leaves the layer at a right angle to it. Figma calls this a magnet (TOP, RIGHT, BOTTOM or LEFT in the plugin API’s ConnectorEndpointConnectedWithMagnet). On an ellipse, polygon or star the end is where the shape’s outline meets the line from its centre toward that side, so it sits on the drawn shape.
• anchor: a corner or edge middle of a polygon, star or ellipse arc (ConnectorAnchor); the end leaves along the outline’s outward direction there.
• point: a fixed point on the layer, as FigJam places an end dropped with Command or Ctrl held (ConnectorEndpointConnectedWithPosition). Figma stores it in the layer’s pixels; here it is a fraction of the layer’s width and height, so the point keeps its place when the layer resizes.

With none of them (Figma’s AUTO magnet), the end goes where the layer’s outline faces the other end. x and y are the end’s position in the connector’s frame; for an attached end they record where it was last placed and are replaced when the connector is drawn.

readonly nodeId?: NodeIdsource

The node this end attaches to. It must be on the same page as the connector.

readonly x: numbersource

readonly y: numbersource

readonly side?: ConnectorSidesince 0.20.0source

The side of the attached layer this end is pinned to. Needs nodeId, and cannot be set together with point or anchor.

readonly anchor?: ConnectorAnchorsince 0.20.0source

The key point on the attached shape’s outline this end is pinned to. Needs nodeId, and cannot be set together with side or point.

readonly point?: { readonly x: number; readonly y: number }since 0.20.0source

The point on the attached layer this end is fixed to, as fractions of the layer’s width (x) and height (y) from its top-left corner: { x: 1, y: 0.5 } is the middle of the right side. Each fraction is between 0 and 1. Needs nodeId, and cannot be set together with side or anchor.

type ConnectorSide = "top" | "right" | "bottom" | "left"

since 0.20.0source

A side of a layer that an attached connector end is pinned to.

interface ConnectorAnchor

since 0.20.0source

A key point on a shape’s outline that an attached connector end is pinned to, found from the shape’s geometry each time the connector is drawn, so the end follows the shape when it moves, resizes or changes its points.

• vertex: corner index of the outline, counted as polygonPoints and starPoints list them (clockwise from the top point; a star’s outer tips are the even indices). On an ellipse arc, vertex 0 is where the arc starts and vertex 1 where it ends, on the outer rim.
• edge: the middle of the outline’s edge from vertex index to the next.

An index the shape does not have (for example after a polygon loses points), or an anchor on a layer without such points, leaves the end automatic, as if it had no anchor.

readonly kind: "vertex" | "edge"source

readonly index: numbersource

A whole number from 0.

type BlendMode = (typeof BLEND_MODES)[number]

source

const BLEND_MODES: readonly [ "normal", "darken", "multiply", "color-burn", "lighten", "screen", "color-dodge", "overlay", "soft-light", "hard-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity" ]

since 0.8.0source

Separable and non-separable compositing modes, in CSS mix-blend-mode terms.

Frames can position their children with an auto layout instead of by hand. A stack lays its children out in a row or a column and can wrap them onto more lines; a grid places them in equal columns. The frame chooses Fixed or Hug on each axis, while each child chooses whether to fill the space its parent gives it, and the size limits that apply, in NodeResizing. These follow Figma’s auto layout, including its rule that a frame stops hugging an axis that one of its stack children fills.

type Layout = AbsoluteLayout | AutoLayout

source

interface AbsoluteLayout

source

readonly kind: "absolute"source

type AutoLayout = StackAutoLayout | GridAutoLayout

source

interface StackAutoLayout extends AutoLayoutConstraints

source

A row ("horizontal") or column ("vertical") auto layout. The main axis runs along the stack; the cross axis runs across it.

readonly kind: "vertical" | "horizontal"source

readonly gap: numbersource

Space between children on the main axis.

readonly padding: LayoutPaddingsource

readonly align: "start" | "center" | "end"source

Where children sit on the cross axis within their line. A child stretches across the line with a cross-axis Fill in FramedNodeBase.resizing. Schema 0.15.0 removed the frame-wide "stretch".

readonly justify: | "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly"source

How children are spread on the main axis within each line. The space-* values replace gap with an automatic gap that is never negative: space-between puts all free space between children (a single child sits at the start), space-around puts half a gap before the first and after the last child, and space-evenly puts a whole gap there (both centre a single child). When children overflow, all three pack from the start. Schema 0.15.0 added "space-around" and "space-evenly".

readonly wrap?: booleansince 0.15.0source

Moves children that do not fit onto new lines: rows for a horizontal stack, columns for a vertical one. Omitted means a single line.

readonly wrapGap?: numbersince 0.15.0source

Space between wrapped lines. Omitted means the same as gap. Kept, but unused, while wrap is off.

readonly alignContent?: "auto" | "space-between"since 0.15.0source

How wrapped lines share the cross axis. "auto" (the default) packs the lines by align, or shares the free space equally between lines when every child fills the cross axis; "space-between" spreads the lines with an automatic gap that is never negative. Kept, but unused, while wrap is off.

interface GridAutoLayout extends AutoLayoutConstraints

source

readonly kind: "grid"source

readonly columns: numbersource

readonly columnGap: numbersource

readonly rowGap: numbersource

readonly padding: LayoutPaddingsource

interface AutoLayoutConstraints

source

The frame’s own sizing. Size limits moved to FramedNodeBase.resizing in 0.15.0.

readonly widthSizing: LayoutSizingsource

"hug" sizes the frame to its content on this axis. In a stack, a child that fills the same axis makes the frame keep its stored size instead, as Figma stops hugging in that case. A grid keeps hugging: its Fill children take their cell, whose size comes from the other children.

readonly heightSizing: LayoutSizingsource

interface LayoutPadding

source

readonly top: numbersource

readonly right: numbersource

readonly bottom: numbersource

readonly left: numbersource

type LayoutSizing = "fixed" | "hug"

source

How an auto layout frame sizes itself on one axis: keep its stored size, or hug its content. Filling the parent is set on the child instead, with FramedNodeBase.resizing.

interface NodeResizing

since 0.15.0source

How auto layout may size a node beyond its stored frame.

width or height set to "fill" makes a child of a stack or grid auto layout take the space its parent gives it on that axis: the Fill children of one line share the line’s free main-axis space equally, a cross-axis Fill takes the line’s cross size, and a grid child fills its cell. The flag has no effect outside an auto layout, on rotated nodes, on groups and on connectors. A node cannot fill an axis on which it hugs its own content (an auto layout frame’s "hug" sizing, or a text or code node’s autoResize).

The limits bound the size auto layout gives the node: a Fill child’s share, and an auto layout frame’s own Hug or Fixed size.

readonly width?: "fill"source

readonly height?: "fill"source

readonly minWidth?: numbersource

readonly maxWidth?: numbersource

readonly minHeight?: numbersource

readonly maxHeight?: numbersource

A few rules are shared with the editor’s drop slots so both break a wrapping row or column at the same children. stackLineBreaks splits the children into lines from the sizes stackLineBreakSize gives; fillsAxis and canFillParent say when a child takes a Fill size.

type LayoutAxis = "width" | "height"

source

A size axis of a node: its width or its height.

function nodeResizing(node: SceneNode): NodeResizing | undefined

source

The node’s Fill flags and size limits, or undefined for a path.

function canFillParent(node: SceneNode): boolean

source

Whether auto layout may give node a Fill size: its box must be its frame (no path, no rotation), and it must not be a group or connector, whose size comes from other nodes.

function fillsAxis(node: SceneNode, axis: LayoutAxis): boolean

source

Whether node fills its auto layout parent on axis.

function stackLineBreakSize(node: SceneNode, mainAxis: LayoutAxis): number

source

The main-axis size a stack child takes when lines are broken: its box size, or its minimum size when it fills the main axis.

function stackLineBreaks( layout: Pick<StackAutoLayout, "gap" | "justify" | "wrap">, availableMain: number, sizes: readonly number[] ): number[][]

source

Breaks a row or column into lines, as Figma’s wrap does: children stay in order and a child starts a new line when it would overflow availableMain (the frame’s main size without padding). An automatic gap (space between, around or evenly) counts as zero here. Without wrap there is one line.

sizes are the children’s main sizes from stackLineBreakSize. Returns the children’s indexes, grouped by line; no children gives no lines.

The layout itself runs whenever the editor edits the document: withAutoLayoutOperations adds the node replacements that keep every affected auto layout frame laid out. layoutFrameTree lays out one frame and the frames inside it, and applyFrameLayout places one frame’s children. createFrameLayout makes a new layout of a given kind.

function withAutoLayoutOperations( document: DesignDocument, operations: readonly DocumentOperation[] ): readonly DocumentOperation[]

source

operations followed by the node replacements that keep auto layout frames laid out after them: frames the operations touch are laid out again, deepest first, and nodes the operations leave filling a parent without auto layout become Fixed. In a document with components, a text whose content is computed is first sized for the text it shows (fitComputedTextContent), and the component cascade then runs (cascadeComponentChanges): instances of changed components are refitted to their hugging size, their dead override keys dropped, and their ancestors laid out again, nested components first. The operations come back unchanged when nothing needs it.

function layoutFrameTree( nodes: Record<string, SceneNode>, frameId: NodeId, changed: Set<NodeId> = new Set() ): Set<NodeId>

source

Lays out the auto layout frame frameId in nodes (changed in place), then lays out again each child frame whose size it changed, so Fill sizes reach nested auto layouts, and each auto layout frame that constraints resized. Returns the IDs of every node it changed. The caller lays out hugging descendants first, deepest first, so their sizes are known.

function applyFrameLayout( frame: FrameNode, childNodes: readonly SceneNode[], layout: Layout ): AppliedFrameLayout

source

Lays out one frame’s direct children with layout and returns the frame with its new size and the moved or resized children. Child frames are not laid out again here; layoutFrameTree does that.

interface AppliedFrameLayout

source

A frame and its children after applyFrameLayout has placed them.

readonly frame: FrameNodesource

readonly children: ReadonlyMap<NodeId, SceneNode>source

function createFrameLayout( kind: Layout["kind"], gap = DEFAULT_AUTO_LAYOUT_GAP ): Layout

source

A new layout of the given kind. Auto layouts start with a fixed width, a hugged height, no padding and gap between children (a grid uses it for both its column and row gaps).

function frameLayoutGap(layout: Layout): number

source

The gap a layout keeps between children: a stack’s gap or a grid’s column gap. Without an auto layout it is DEFAULT_AUTO_LAYOUT_GAP.

const DEFAULT_AUTO_LAYOUT_GAP: 24

source

The gap, in pixels, a new auto layout starts with.

Resize constraints say how a layer follows its frame when the frame is resized, with Figma’s five options on each axis: Left, Right, Left and right, Center and Scale horizontally, and their vertical counterparts. They apply to the children of frames without auto layout and to the absolute children of auto layout frames (layoutPositioning: "absolute", Figma’s “Ignore auto layout”), which the layout leaves out of its flow. constrainChildren places a frame’s children for a change of its size; the editor’s frame resize, the selection box and group resizing all use it, and so does layoutFrameTree when a layout changes a frame’s size. scaleLayerInParent scales one layer the way a resized box does.

interface ResizeConstraints

since 0.25.0source

A layer’s resize constraints, Figma’s five options on each axis. They act on the layer’s axis-aligned bounds in its frame (see constrainChildren).

readonly horizontal: HorizontalConstraintsource

readonly vertical: VerticalConstraintsource

type HorizontalConstraint = "left" | "right" | "left-right" | "center" | "scale"

since 0.25.0source

How a layer’s horizontal position and width follow its frame’s width. "left", "right" and "center" keep the width and the distance to the left edge, the right edge or the center line; "left-right" keeps both distances, so the width changes with the frame; "scale" keeps the layer’s position and width as shares of the frame’s width.

type VerticalConstraint = "top" | "bottom" | "top-bottom" | "center" | "scale"

since 0.25.0source

How a layer’s vertical position and height follow its frame’s height; the vertical counterpart of HorizontalConstraint.

const DEFAULT_RESIZE_CONSTRAINTS: ResizeConstraints

since 0.25.0source

The constraints a layer has when it stores none: Left and Top, Figma’s default, which keeps the layer’s position and size.

function nodeConstraints(node: SceneNode): ResizeConstraints

since 0.25.0source

A layer’s constraints, with DEFAULT_RESIZE_CONSTRAINTS when it stores none.

function followsConstraints(parent: FrameNode, child: SceneNode): boolean

since 0.25.0source

Whether a child of parent is placed by its constraints when parent resizes: every child of a frame without auto layout, and only the absolute children (layoutPositioning: "absolute") of an auto layout frame, whose other children the layout places.

function constrainChildren( nodes: NodeRecord, parentId: NodeId, from: FrameSize, to: FrameSize ): readonly SceneNode[]

since 0.25.0source

Places each child of the frame parentId for a resize of that frame from from to to, by the child’s constraints (NodeBase.constraints), as Figma does when a frame is resized. nodes holds the frame and its descendants before the change; the frame’s own record is only read for its children and layout, so it may hold either size.

• Constraints act on each child’s axis-aligned bounds in the frame. A child whose bounds change size is resized like a layer in a resized selection box (scaleLayerInParent): a rotated or flipped layer keeps its rotation and flips, and a frame’s own children follow by their constraints in turn.
• An auto layout frame’s flow children are left to its layout; only its absolute children move (followsConstraints). A child auto layout frame whose size changes is not laid out again here: the caller does that, as layoutFrameTree or the editor’s auto layout step do.
• A group has no constraints of its own. The layers of an upright group (not rotated or flipped) are placed one by one by their own constraints relative to the frame, and the group is fitted to them again. A rotated or flipped group moves and resizes as one layer, by the option its layers share on each axis, or Left or Top when they differ.

Returns every changed node, children before descendants, each at most once. An unchanged size returns an empty list.

The instance resolver calls this to lay out a resized instance whose component root has no auto layout: constrainChildren(nodes, rootId, componentRoot.frame, instance.frame), writing the result into its node record before it lays out auto layout frames with layoutFrameTree.

interface FrameSize

since 0.25.0source

A frame’s size before or after a resize. Constraints only need sizes: children are placed relative to their frame’s top-left corner, so where the frame moves on the page does not matter.

readonly width: numbersource

readonly height: numbersource

function scaleLayerInParent( nodes: NodeRecord, node: SceneNode, scaleX: number, scaleY: number ): readonly SceneNode[]

since 0.25.0source

Scales a layer’s position and size by (scaleX, scaleY) about its parent’s origin, in the parent’s coordinates, the way resizing a group or a selection box moves the layers inside it. Positions, sizes and vector geometry scale; stroke widths, corner radii, effects and font sizes do not.

• A rotated layer keeps its rotation and takes the size whose bounds are its old bounds scaled, when the rotation allows it (see the source of rotatedSize for the fallback near 45 degrees).
• A group’s descendants scale with it.
• A frame’s box scales and its children follow by their constraints (constrainChildren); an auto layout places its other children later.
• Text or code that grew with its content gets a fixed size.

Returns the layer followed by every changed descendant. nodes must hold the layer’s descendants.

The sizing helpers read and change a node’s Fixed, Hug or Fill sizing on each axis, keeping the rules of Figma’s resizing menu: only auto layout frames, instances of a component with auto layout, text and code can hug, and only children of an auto layout frame can fill. nodeAxisSizing is the one reader and withAxisSizing the one writer of Fixed and Hug: an instance’s sizing is its override of its component root’s sizing, so both take the document. withManualSize is the one place a size changed by hand (a resize, the Scale tool, a size variable) gets the sizing that keeps it: commands and drag previews pass their node through it.

type AxisSizing = "fixed" | "hug" | "fill"

source

How a node is sized on one axis, as the width and height menus show it (Figma’s resizing menu): a stored size, its content’s size, or the space its auto layout parent gives it.

type SizingAxis = "width" | "height"

source

The axis a sizing applies to.

function nodeAxisSizing( document: DesignDocument, node: SceneNode, axis: SizingAxis ): AxisSizing

source

The node’s sizing on an axis: the one reader of it. Nodes that cannot hug or fill are Fixed. An auto layout frame’s is its layout’s; text and code read their automatic sizing. An instance has no layout of its own: its sizing is its override of its component root’s sizing (LayerSizingOverride, stored under the root’s path), and the root’s own sizing where it has none, which is what the instance resolver lays it out with. Fill is the node’s own resizing for every kind of node.

function canHugAxis(document: DesignDocument, node: SceneNode): boolean

source

Auto layout frames hug their children, text and code blocks hug their content, and an instance hugs as its component root does: only when the root has auto layout.

function canFillAxis( document: DesignDocument, node: SceneNode, axis: SizingAxis, parent: SceneNode | undefined = parentNodeOf(document, node.id) ): boolean

source

Whether the node can fill its parent on an axis: it must be a child of an auto layout frame, and not a path, group or connector, a rotated node, or (for the height) a line, whose height is always zero. Figma offers Fill container only on children of auto layout frames.

function withoutFill(node: SceneNode, axis: SizingAxis): SceneNode

source

The node without a Fill flag on the axis.

function withoutAnyFill(node: SceneNode): SceneNode

source

The node without any Fill flag, keeping its size limits.

function withAxisSizing( document: DesignDocument, node: SceneNode, axis: SizingAxis, sizing: "fixed" | "hug" ): SceneNode

source

The node with its sizing on axis set to Fixed or Hug: the one writer of it, the counterpart of nodeAxisSizing. An auto layout frame stores it in its layout; an instance stores it as its override of its component root’s sizing. A node that has neither (a shape, a frame without auto layout, an instance of a component without auto layout) is returned as it is, and so is text or code, whose automatic sizing has rules of its own (sizingReplacements). Fill is not touched: see withoutFill.

type ManualSizeChange = "resize" | "scale" | "variable"

source

How a layer’s size was changed by hand, as opposed to by a layout, a constraint or its content:

• "resize": a resize handle, a typed W or H, the box around a selection, a moved end of a line.
• "scale": the Scale tool, on one layer or on the box around a selection.
• "variable": a size variable bound to W or H.

function withManualSize( document: DesignDocument, before: SceneNode, after: SceneNode, change: ManualSizeChange, axes: readonly SizingAxis[] = changedSizeAxes(before, after) ): SceneNode

source

after, the node before with a size changed by hand, with the sizing that change leaves: the one place the rule “a size set by hand is kept” is written. Every command that changes a size by hand, and every preview of one, passes its node through here, so the release commits what the drag drew and the next layout does not undo it.

• A resize, on each axis whose size changed: Fill and Hug become Fixed (an instance’s Hug too) and a size variable on the axis is dropped.
• The Scale tool, on each axis whose size changed: an instance’s Hug becomes Fixed, since its layers are its component’s and do not scale. A frame keeps Hug: its children scaled with it, so it hugs the scaled size. Fill and a size variable are left as they are.
• A size variable: Fill and Hug become Fixed on axes, which the caller names because the variable’s value may equal the size the node has.

A size that a layout, a constraint or the node’s content gives is not a change by hand and does not come here: the sizing stays.

function withManualSizes( document: DesignDocument, nodes: readonly SceneNode[], change: ManualSizeChange, only?: ReadonlySet<NodeId> ): readonly SceneNode[]

source

nodes, the output of a resize or a scale of layers of document, each passed through withManualSize against the node it replaces. only limits the rule to the layers the user changed, where the others were only carried along (the descendants of a resized group or selection).

function withoutStretchWhereHugging( document: DesignDocument, node: SceneNode ): SceneNode

source

The node without a stretching constraint on an axis it hugs: what the rule “no node hugs and stretches on the same axis” does to one node. Commands do not call it; stretchWhereHuggingReplacements applies the rule to every edit, on the axes the edit brings to break it.

function stretchWhereHuggingReplacements( previous: DesignDocument, next: DesignDocument, changedNodeIds: ReadonlySet<NodeId> ): readonly SceneNode[]

source

The one place the rule “no node has a stretching constraint (Left and right, Top and bottom, Scale) on an axis whose sizing is Hug” is enforced. applyOperations calls it for every batch of operations, so every command, preview, paste, undo-able edit and replayed commit passes through it and no command applies the rule itself.

next is previous after the batch and changedNodeIds the nodes the batch wrote. The nodes looked at are the ones whose sizing or constraints can have changed:

• every changed node that still exists (its own layout, automatic text sizing, overrides, component or constraints may be new);
• every instance, at any depth and on any page or inside any component, of a component whose root or root sizing changed. An instance with a sizing override on the axis keeps its own sizing, so only the ones that follow the component can lose a constraint.

Only a break of the rule that the batch brings is removed: an axis of a node that hugs and stretches in next and did not in previous (the node is new, or it kept the rule on that axis there). A node that already hugged and stretched on an axis in previous, as a document stored before the rule existed can hold, is left on that axis exactly as the batch leaves it, so a batch that does not touch the break, or keeps it, can be reversed exactly.

Returned are those nodes, each with the stretching constraint turned into Left or Top on the axes that newly break the rule, in a stable order (the batch’s own, then the document’s). The sizing is never changed here, so one pass is enough. The cost is two sizing reads per changed node, two more for one that breaks the rule, and one comparison per component; the walk over every node of the document happens only for a batch that changed a component root’s sizing.

function sizingReplacements( document: DesignDocument, nodeIds: readonly NodeId[], axis: SizingAxis, sizing: AxisSizing ): ReadonlyMap<NodeId, SceneNode>

source

The nodes that change when nodeIds are set to sizing on axis, by id. Nodes that cannot take that sizing are left out.

An instance follows every rule here as an auto layout frame does, through nodeAxisSizing and withAxisSizing, except the last part of the Hug rule: its layers are its component’s, so their Fill is not changed.

• Fill turns the node’s own Hug on the axis into Fixed (text and code stop sizing that axis to their content), drops a size variable on the axis, and turns a hugging stack parent Fixed on the axis, as Figma does: “If any child objects within an auto layout frame are set to Fill container, the parent frame will no longer hug contents and become Fixed for the axis.”
• Hug on an auto layout frame turns its stack children that fill the axis into Fixed. A grid keeps its Fill children: they take their cell.
• Fixed and Hug drop the node’s own Fill on the axis.

Hug leaves a stretching constraint on the axis for applyOperations to turn into Left or Top, as it does after every edit (stretchWhereHuggingReplacements).

function resizingReplacements( document: DesignDocument, nodeId: NodeId, resizing: NodeResizing | undefined ): ReadonlyMap<NodeId, SceneNode>

source

The nodes that change when a node’s Fill flags and size limits are replaced with resizing (undefined removes them all). A newly set Fill follows the same rules as choosing Fill container in the sizing menu.

function isAutoLayoutFrame(node: SceneNode | undefined): node is AutoLayoutFrame

source

Whether the node is a frame with a stack or grid auto layout.

function parentNodeOf( document: DesignDocument, nodeId: NodeId ): SceneNode | undefined

source

The container that holds the node, or undefined for a page’s top level node.

function documentWithNodes( document: DesignDocument, nodes: ReadonlyMap<NodeId, SceneNode> ): DesignDocument

source

The document with nodes replacing their stored versions.

Paints, strokes and styles

Fills and strokes take a Paint: a solid color, a gradient, or an image. Every paint can be hidden (visible: false) and can blend with the paints below it on the same layer (blendMode), as in Figma; see PaintVisibility. VisualStyle collects a node’s fills, strokes, corners and effects. Rectangles and frames can round each corner on its own with CornerRadii; styleCornerRadii reads the four radii a style paints with. A stroke can likewise give each side its own weight with StrokeSides; strokeSideWeights reads the four weights a stroke paints with.

interface VisualStyle

source

readonly styleId?: NodeStyleIdsource

readonly fills?: readonly Paint[]source

readonly strokes?: readonly Stroke[]since 0.5.0source

Ordered strokes painted after the fills, first entry at the bottom.

readonly cornerRadius?: numbersource

One radius for every corner. Rectangles and frames use cornerRadii instead when it is present; polygons, stars and paths round every vertex with it.

readonly cornerRadii?: CornerRadiisince 0.16.0source

Independent corner radii for rectangles and frames. When present it replaces cornerRadius on those nodes; other shapes ignore it. The editor clears cornerRadius when it writes this field, so one of the two describes the corners.

readonly cornerSmoothing?: numbersince 0.9.0source

Corner smoothing from 0 (circular corners) to 1 (fully continuous curvature), as in Figma. It only changes corners that have a radius, and each smoothed corner consumes up to (1 + smoothing) * radius of edge.

For a rectangle, the renderer first limits the radius $r$ and smoothing $s$ to the budget $B = \tfrac12 \min(w, h)$, then works out how much of each edge the corner uses:

$$r' = \min(r, B), \qquad s' = \min\bigl(s, \max(0, B / r' - 1)\bigr), \qquad p = \min\bigl((1 + s')\,r',\ B\bigr)$$

Walking into the corner, a cubic curve eases off the edge, a circular arc of radius $r'$ turns through $90(1 - s')$ degrees, and a mirrored cubic eases onto the next edge. With $\beta = 45 s'$ degrees, the arc covers $\ell$ along each edge and the cubic control distances are

$$\ell = \sqrt{2}\, r' \sin\!\Bigl(\frac{90(1 - s')}{2}\Bigr), \quad c = r' \tan\!\Bigl(\frac{\beta}{2}\Bigr) \cos\beta, \quad d = c \tan\beta, \quad b = \frac{p - \ell - c - d}{3}, \quad a = 2b$$

so $a + b + c + d + \ell = p$. At $s' = 0$ this is a plain quarter circle.

readonly shadows?: readonly Shadow[]source

readonly layerBlur?: numbersince 0.7.0source

Gaussian blur radius applied to the node and its descendants as one layer.

readonly backgroundBlur?: numbersince 0.7.0source

Gaussian blur radius applied to whatever lies behind the node’s shape.

interface CornerRadii

since 0.16.0source

Separate radii for the four corners of a rectangle or frame, as in Figma’s topLeftRadius, topRightRadius, bottomRightRadius and bottomLeftRadius. Each is a non-negative number of units; the renderer limits each one to half the shorter side, the same limit as a uniform radius, so neighbouring corners never overlap.

readonly topLeft: numbersource

readonly topRight: numbersource

readonly bottomRight: numbersource

readonly bottomLeft: numbersource

const CORNER_KEYS: readonly ["topLeft", "topRight", "bottomRight", "bottomLeft"]

source

The four corners in Figma’s panel order: top left, top right, bottom right, bottom left.

type CornerKey = (typeof CORNER_KEYS)[number]

source

One corner of a rectangle or frame, as named in CornerRadii.

function styleCornerRadii( style: | Pick<VisualStyle, "cornerRadius" | "cornerRadii"> | undefined ): CornerRadii

source

The radii a rectangle or frame paints with: cornerRadii when present, otherwise the uniform cornerRadius (zero when absent) on every corner.

function uniformCornerRadii(radius: number): CornerRadii

source

Four equal radii.

function cornerRadiiAreUniform(radii: CornerRadii): boolean

source

True when all four corners have the same radius.

function cornerRadiiAreRounded(radii: CornerRadii): boolean

source

True when any corner is rounded.

function scaleCornerRadii(radii: CornerRadii, factor: number): CornerRadii

source

Multiplies every radius by factor, as the scale tool does.

type Paint = SolidPaint | GradientPaint | ImagePaint

source

interface PaintVisibility

since 0.18.0source

Fields every paint shares, as in Figma’s Paint: whether it shows and how it blends with the paints below it on the same layer.

readonly visible?: booleansince 0.18.0source

False hides the paint without removing it, like the eye button in Figma’s fill and stroke lists. Defaults to true.

readonly blendMode?: BlendModesince 0.18.0source

How the paint blends with the paints below it on the same layer: the fills under a fill, or the fills and strokes under a stroke. Uses the same modes as a node’s blendMode. Defaults to "normal".

interface SolidPaint extends PaintVisibility

source

readonly kind: "solid"source

readonly color: stringsource

readonly opacity?: numbersource

type GradientPaint = | LinearGradientPaint | RadialGradientPaint | AngularGradientPaint

source

interface LinearGradientPaint extends PaintVisibility

source

readonly kind: "linear-gradient"source

readonly angle: numbersource

readonly stops: readonly GradientStop[]source

readonly opacity?: numbersource

interface RadialGradientPaint extends PaintVisibility

since 0.6.0source

A gradient that spreads outward from a center point.

readonly kind: "radial-gradient"source

readonly center?: PaintAnchorsource

Defaults to the center of the bounds.

readonly radius?: PaintAnchorsource

Ellipse radii as fractions of the bounds; defaults to half the width and height.

readonly stops: readonly GradientStop[]source

readonly opacity?: numbersource

interface AngularGradientPaint extends PaintVisibility

since 0.6.0source

A gradient that sweeps around a center point.

readonly kind: "angular-gradient"source

readonly center?: PaintAnchorsource

Defaults to the center of the bounds.

readonly angle?: numbersource

Start angle in degrees, clockwise from the positive x axis; defaults to 0.

readonly stops: readonly GradientStop[]source

readonly opacity?: numbersource

interface GradientStop

source

readonly offset: numbersource

readonly color: stringsource

interface PaintAnchor

since 0.6.0source

A point in the painted shape’s bounds, as fractions of its width and height.

readonly x: numbersource

readonly y: numbersource

interface ImagePaint extends PaintVisibility

since 0.6.0source

Paints an image asset.

readonly kind: "image"source

readonly assetId: AssetIdsource

readonly fit?: ImagePaintFitsource

Defaults to cover.

readonly opacity?: numbersource

type ImagePaintFit = "contain" | "cover" | "fill"

since 0.6.0source

How an image paint is scaled into the painted shape’s bounds.

interface Stroke

source

readonly paint: Paintsource

readonly width: numbersource

The weight of every side. With sides, the editor keeps it at the largest side weight.

readonly dash?: readonly number[]source

readonly position?: StrokePositionsince 0.0.1source

Defaults to center when omitted by an older operation or document.

readonly sides?: StrokeSidessince 0.17.0source

Separate weights for the top, right, bottom and left sides, replacing width on rectangles and frames. Other shapes, connectors and code blocks ignore it. A side of weight 0 paints nothing, and the corners between sides of different weights follow the shape’s corners.

readonly join?: StrokeJoinsince 0.22.0source

How the stroke turns a corner where two segments meet, as Figma’s strokeJoin. Omitted keeps what the layer drew before 0.22.0: round on paths, ellipses, polygons, stars, lines and connectors, and on rectangles drawn as paths (rounded or with gradient, image or several fills); miter on frames, other rectangles and code blocks. See defaultStrokeJoin. Rectangles and frames with side weights ignore it.

readonly miterAngle?: numbersince 0.22.0source

The miter angle in degrees, as Figma’s “Miter angle” (the REST API’s strokeMiterAngle): a miter join whose corner is sharper than this is drawn beveled. Only a miter join uses it. It is more than 0 and at most 180; omitted is DEFAULT_STROKE_MITER_ANGLE, Figma’s default of about 28.96 degrees, which is a miter limit of 4 (limit = 1 / sin(angle / 2)).

readonly dashCap?: DashCapsince 0.22.0source

The ends of every dash of a dashed stroke, as Figma’s “Dash cap”. None stops a dash flat; round and square extend it by half the stroke width. Omitted keeps what the layer drew before 0.22.0: round on the layers whose join defaults to round, none on the others (see defaultDashCap). A solid stroke ignores it.

type StrokePosition = "center" | "inside" | "outside"

since 0.0.1source

Which side of the outline a stroke is drawn on.

interface StrokeSides

since 0.17.0source

Stroke weights for the four sides of a rectangle or frame. Unlike Figma, which keeps one set of side weights per node, each stroke in VisualStyle.strokes carries its own.

readonly top: numbersource

readonly right: numbersource

readonly bottom: numbersource

readonly left: numbersource

const STROKE_SIDE_KEYS: readonly ["top", "right", "bottom", "left"]

source

The four stroke sides in the order the wire and the panel use.

type StrokeSideKey = (typeof STROKE_SIDE_KEYS)[number]

source

One side of a stroke, as named in StrokeSides.

function strokeSideWeights(stroke: Pick<Stroke, "width" | "sides">): StrokeSides

source

The weight of each side a stroke paints with: sides, or width on all four.

function widestStrokeSide(sides: StrokeSides): number

source

The largest of the four side weights.

type StrokeCap = (typeof STROKE_CAPS)[number]

source

const STROKE_CAPS: readonly [ "none", "round", "square", "line-arrow", "triangle-arrow", "reversed-triangle", "circle-arrow", "diamond-arrow" ]

since 0.12.0source

Stroke end caps as Figma names them. None ends the stroke flat at the endpoint; round and square extend it by half the stroke width; the arrow caps draw a head in the stroke’s paint whose size follows the stroke width. Lines and connectors share these end styles and draw them the same way. Heads are always solid, even on a dashed stroke.

A stroke also sets how its corners join, how each dash of a dashed stroke ends, and the miter angle below which a miter join is beveled, as in Figma’s Stroke settings. A stroke that sets none of these draws as layers did before schema 0.22.0: defaultStrokeJoin and defaultDashCap give those defaults. Figma sets a miter angle where Skia takes a miter limit; miterLimitFromAngle and miterAngleFromLimit convert between them. Only an open path with one unbranched chain of segments takes end points (openPathChain).

type StrokeJoin = (typeof STROKE_JOINS)[number]

source

How a stroke’s corners join: sharp (miter), cut off (bevel) or round.

const STROKE_JOINS: readonly ["miter", "bevel", "round"]

since 0.22.0source

The stroke joins, as Figma names them (MITER, BEVEL, ROUND).

type DashCap = (typeof DASH_CAPS)[number]

source

How each dash of a dashed stroke ends: flat at the dash (none), round or square.

const DASH_CAPS: readonly ["none", "round", "square"]

since 0.22.0source

The ends of each dash of a dashed stroke, as in Figma’s Dash cap menu.

const DEFAULT_STROKE_MITER_ANGLE: number

since 0.22.0source

Figma’s default miter angle in degrees, 2 * asin(1 / 4): the angle at which a miter limit of 4 bevels.

function strokeMiterAngle(stroke: Pick<Stroke, "miterAngle">): number

source

A stroke’s miter angle, or Figma’s default when it has none.

function miterLimitFromAngle(angle: number): number

since 0.22.0source

The miter limit a miter angle gives, as SVG and Skia use it: the longest a miter may be, as a multiple of half the stroke width, before the join is beveled. A corner sharper than angle degrees has a longer miter.

function miterAngleFromLimit(limit: number): number

source

The miter angle, in degrees, that a miter limit of at least 1 gives.

function defaultStrokeJoin( node: SceneNode, style: VisualStyle | undefined ): StrokeJoin

since 0.22.0source

The join a stroke of node draws with when it names none: what the layer drew before schema 0.22.0, round on layers stroked along a path and miter on layers stroked around a box. style is the layer’s resolved style.

function defaultDashCap( node: SceneNode, style: VisualStyle | undefined ): DashCap

since 0.22.0source

The dash ends a dashed stroke of node draws with when it names none: round on layers stroked along a path and none on layers stroked around a box, as before schema 0.22.0.

const DEFAULT_PATH_STROKE_CAP: StrokeCap

source

The end style an open path draws when it names none: round, as before 0.22.0.

function openPathChain(network: VectorNetwork): readonly VectorSegment[] | null

since 0.22.0source

The segments of network when they form one open chain in order: each segment starts where the one before it ends, and the first segment’s start and the last segment’s end are each touched by that segment only. Only such a path takes end points (PathNode.startCap and endCap). Returns null for a closed, branched or empty network.

interface Shadow

source

readonly kind?: ShadowKindsince 0.7.0source

Defaults to a drop shadow when omitted by an older document.

readonly x: numbersource

readonly y: numbersource

readonly blur: numbersource

readonly spread: numbersource

readonly color: stringsource

type ShadowKind = "drop" | "inner"

since 0.7.0source

A drop shadow paints behind the node; an inner shadow paints inside it.

Vector networks

A path stores an editable vector network: vertices, segments between them, optional tangent constraints, and filled regions made of directed loops. SVG path data is only an interchange format.

interface VectorNetwork

since 0.2.0source

The vertices, segments and filled regions that make up a path’s shape.

readonly vertices: readonly VectorVertex[]source

readonly segments: readonly VectorSegment[]source

readonly constraints?: readonly VectorTangentConstraint[]source

Omitted is equivalent to an empty constraint list.

readonly regions: readonly VectorRegion[]source

Ordered from back to front for painting.

interface VectorVertex

since 0.2.0source

A point in a VectorNetwork, in network coordinates.

readonly id: VectorVertexIdsource

readonly x: numbersource

readonly y: numbersource

readonly cornerRadius?: numbersince 0.10.0source

Corner radius at this vertex, overriding the node style’s corner radius. Only a vertex joining exactly two segments rounds; the renderer clamps the radius to half of the shorter adjacent segment.

type VectorSegment = | VectorLineSegment | VectorCubicSegment | VectorEllipticalArcSegment

since 0.2.0source

An edge between two vertices of a VectorNetwork.

interface VectorLineSegment extends VectorSegmentBase

source

readonly kind: "line"source

interface VectorCubicSegment extends VectorSegmentBase

source

readonly kind: "cubic"source

readonly startHandle: VectorHandlesource

readonly endHandle: VectorHandlesource

interface VectorEllipticalArcSegment extends VectorSegmentBase

source

Compatibility geometry for exact migration and SVG interchange. The editor initially creates and directly edits line and cubic segments only.

readonly kind: "elliptical-arc"source

readonly radiusX: numbersource

readonly radiusY: numbersource

readonly xAxisRotation: numbersource

readonly largeArc: booleansource

readonly sweep: booleansource

interface VectorHandle

source

readonly id: VectorHandleIdsource

readonly dx: numbersource

Horizontal control-point offset relative to the segment endpoint.

readonly dy: numbersource

Vertical control-point offset relative to the segment endpoint.

interface VectorTangentConstraint

source

Couples two endpoint handles that meet at one vertex. Pairwise constraints let branched networks describe independent smooth continuations without assigning one ambiguous smoothing mode to the whole vertex.

readonly vertexId: VectorVertexIdsource

readonly handleIds: readonly [VectorHandleId, VectorHandleId]source

readonly mode: "angle" | "angle-and-length"source

Keep only the angle mirrored, or mirror both angle and handle length.

interface VectorRegion

since 0.2.0source

A filled area of a VectorNetwork, bounded by loops of segments.

readonly id: VectorRegionIdsource

readonly windingRule: "nonzero" | "evenodd"source

readonly loops: readonly VectorRegionLoop[]source

readonly fills?: readonly Paint[]source

Omitted inherits the path’s resolved fills; an empty array disables fill.

interface VectorRegionLoop

source

readonly segments: readonly VectorSegmentReference[]source

readonly implicitClose?: truesource

Closes an open chain for filling without adding or stroking another edge, matching SVG’s implicit fill closure for open subpaths.

interface VectorSegmentReference

source

readonly segmentId: VectorSegmentIdsource

readonly direction: "forward" | "reverse"source

type VectorWindingRule = VectorRegion["windingRule"]

source

function vectorNetworkFromSvgPathData( pathData: string, windingRule: VectorWindingRule = "nonzero" ): VectorNetwork

source

Converts an SVG path into deterministic, node-local vector-network topology. Relative, shorthand, horizontal, vertical, and quadratic commands are normalized. Elliptical arcs remain exact compatibility segments.

function vectorRegionToSvgPathData( network: VectorNetwork, region: VectorRegion ): string

source

Projects one fillable region to SVG path data.

function vectorRegionPathDataById( network: VectorNetwork, regionId: string ): string | undefined

source

Projects the first matching region, useful for callers that retain a region ID.

function vectorNetworkToStrokePathData(network: VectorNetwork): string

source

Projects every network edge once for SVG-compatible stroking and bounds. Region loops preserve authored chains where possible; remaining graph edges become individual subpaths because SVG cannot encode a branched join.

function transformVectorPoint( x: number, y: number, transform: TransformMatrix ): { readonly x: number; readonly y: number }

source

Applies an SVG-compatible affine matrix to a point.

function scaleVectorNetwork( network: VectorNetwork, scale: { readonly x: number; readonly y: number }, anchor: { readonly x: number; readonly y: number } ): VectorNetwork

source

Scales a vector network in its own coordinate space around one anchor. An elliptical arc keeps its exact shape: see scaleEllipticalArc.

function assertValidPathData(pathData: string): void

source

function isClosedPathData(pathData: string): boolean

source

Returns true when every subpath closes back to its starting point.

Text

Text nodes hold paragraphs of styled runs. A run names a theme TextStyle and may carry direct overrides; paragraphs add alignment, spacing, indents and list markers.

interface TextParagraph

source

One paragraph of a TextNode: its runs plus paragraph-level layout.

readonly runs: readonly TextRun[]source

readonly direction?: "auto" | "ltr" | "rtl"source

Auto resolves direction from paragraph content when omitted or set explicitly.

readonly align?: "left" | "center" | "right" | "justify"source

readonly spacingBefore?: numbersource

readonly spacingAfter?: numbersource

readonly indent?: { readonly left: number; readonly right: number; readonly firstLine: number; }source

readonly list?: { readonly kind: "ordered" | "unordered"; readonly level: number; readonly start?: number; readonly marker?: TextListMarker; }source

Makes the paragraph a list item.

interface TextRun

source

A span of text sharing one style.

readonly text: stringsource

readonly styleId?: TextStyleIdsource

The theme text style; the theme’s defaultTextStyleId when omitted.

readonly overrides?: TextStyleOverridessource

Direct formatting on top of the style.

interface TextListMarker

source

The bullet or number shown before a list paragraph, and how it is styled.

readonly text?: stringsource

Custom marker text; must not be empty when given.

readonly styleId?: TextStyleIdsource

readonly overrides?: TextStyleOverridessource

readonly gap?: numbersource

Space between the marker and the paragraph text. Non-negative.

interface TextStyle

source

readonly name: stringsource

readonly fontFamily: stringsource

readonly fontAssetId?: AssetIdsource

readonly fontFallbackAssetIds?: readonly AssetId[]source

Ordered embedded font assets tried after fontAssetId.

readonly language?: stringsource

Canonically-cased BCP 47 language tag used for shaping and line breaking.

readonly fontSize: numbersource

readonly fontWeight: numbersource

readonly lineHeight: numbersource

readonly letterSpacing?: numbersource

readonly color: stringsource

readonly italic?: booleansource

readonly underline?: booleansource

readonly strikethrough?: booleansince 0.2.0source

Draws a line through the text.

readonly openTypeFeatures?: Readonly<Record<string, boolean | number>>since 0.2.0source

Explicit deviations from a font’s OpenType feature defaults.

readonly fontVariations?: Readonly<Record<string, number>>since 0.2.0source

Explicit variable-font axis coordinates keyed by four-byte OpenType tag.

type TextStyleOverrides = & Partial<Omit<TextStyle, "name" | "fontAssetId" | "fontFallbackAssetIds">> & { readonly fontAssetId?: AssetId | null; readonly fontFallbackAssetIds?: readonly AssetId[]; }

since 0.2.1source

Direct text formatting authored on one run or list marker.

Font resources need explicit clearing semantics because omitting an override inherits the selected theme style. A null primary clears an inherited fontAssetId, while an empty fallback list clears inherited fallbacks.

function assertTextStyleOverrides( value: unknown ): asserts value is TextStyleOverrides

source

Validates a standalone authored run or list-marker text-style override.

const MAX_TEXT_FONT_FALLBACK_ASSETS: 4095

source

Canonical upper bound; retained text also carries one primary font asset.

type OpenTypeTag = Brand<string, "OpenTypeTag">

since 0.2.0source

A four-character OpenType feature or axis tag. Make one with openTypeTag.

function openTypeTag(value: string): OpenTypeTag

source

OpenType feature and variation tags are exactly four printable ASCII bytes.

Assets and fonts

Images, videos and fonts live in the document’s asset map and are referenced by AssetId. A font comes from Google Fonts (GoogleFontsSource) or from the fonts installed on the computer (LocalFontSource); a local font is named but its file is never stored in the document.

type Asset = ImageAsset | VideoAsset | FontAsset

source

A file stored in DesignDocument.assets, told apart by its kind field.

interface ImageAsset

source

An image file used by ImageNode and ImagePaint.

readonly id: AssetIdsource

Matches the asset’s key in DesignDocument.assets.

readonly kind: "image"source

readonly mimeType: stringsource

readonly source: AssetSourcesource

readonly width?: numbersource

Intrinsic width in pixels, when known.

readonly height?: numbersource

Intrinsic height in pixels, when known.

interface VideoAsset

source

A video file used by VideoNode.

readonly id: AssetIdsource

Matches the asset’s key in DesignDocument.assets.

readonly kind: "video"source

readonly mimeType: stringsource

readonly source: AssetSourcesource

readonly width?: numbersource

Intrinsic width in pixels, when known.

readonly height?: numbersource

Intrinsic height in pixels, when known.

interface FontAsset

source

One font face, referenced by TextStyle.fontAssetId, TextStyle.fontFallbackAssetIds and CodeStyle.fontAssetId.

readonly id: AssetIdsource

Matches the asset’s key in DesignDocument.assets.

readonly kind: "font"source

readonly mimeType: stringsource

Must be font/woff2 when the source is Google Fonts, and font/ttf or font/otf when the source is a local font.

readonly source: FontAssetSourcesource

readonly family: stringsource

readonly weight: numbersource

From 1 to 1000, as in CSS font-weight.

readonly style: "normal" | "italic" | "oblique"source

type AssetSource = | { readonly kind: "url"; readonly url: string } | { readonly kind: "data"; readonly data: string }

source

Where an asset’s bytes come from: a URL, or data stored in the document.

type FontAssetSource = AssetSource | GoogleFontsSource | LocalFontSource

since 0.13.0source

Where a font’s files come from.

interface GoogleFontsSource

since 0.13.0source

A font family served by Google Fonts as many small WOFF2 files, each covering part of Unicode (declared by unicode-range in the Google Fonts CSS). The app keeps the list of files for each built-in family and loads only the files that contain characters the document uses.

readonly kind: "google-fonts"source

readonly family: stringsource

The Google Fonts family name, such as “Noto Sans SC”.

interface LocalFontSource

since 0.19.0source

A font installed on the computer of the person who chose it, read through the browser’s Local Font Access API (window.queryLocalFonts()). The document names the font but does not carry its file, so the list of fonts installed on a computer never enters a document; only the fonts that its text uses are named. On a computer where the font is not installed, the app shows the text as using a missing font.

readonly kind: "local"source

readonly family: stringsource

The installed family name, such as “Helvetica Neue”.

readonly postScriptName: stringsource

The face’s PostScript name, which identifies it among installed fonts.

readonly styleName: stringsource

The installed style name, such as “Bold Italic”.

readonly sha256: stringsource

SHA-256 of the face’s font file, as 64 lowercase hexadecimal digits. An installed face with the same PostScript name but other bytes is a different version of the font, which can lay text out differently.

Theme, styles and variables

The theme holds shared node, text and code styles, named colors, and variable collections. A node may bind a supported property to a variable; the bound value is also written on the node, so detaching keeps the look.

interface DocumentTheme

source

The document’s shared styles, named colors and variables. Nodes refer to them by ID and may keep direct overrides on top.

readonly defaultTextStyleId: TextStyleIdsource

The text style used by runs that name none.

readonly defaultCodeStyleId: CodeStyleIdsource

The code style used by code nodes that name none.

readonly colors: Readonly<Record<string, string>>source

Named colors, keyed by name.

readonly nodeStyles: Readonly<Record<string, NodeStyle>>source

readonly textStyles: Readonly<Record<string, TextStyle>>source

readonly codeStyles: Readonly<Record<string, CodeStyle>>source

readonly variableCollections?: Readonly<Record<string, VariableCollection>>source

Variable collections stored in this document. Libraries shared between documents are intentionally out of scope.

interface NodeStyle extends Omit<VisualStyle, "styleId">

source

readonly name: stringsource

interface CodeStyle

source

Provides palette colors and the typography defaults used for new code nodes.

readonly name: stringsource

readonly fontFamily: stringsource

readonly fontAssetId?: AssetIdsource

readonly fontSize: numbersource

readonly lineHeight: numbersource

readonly letterSpacing?: numbersince 0.1.2source

Extra space added between characters.

readonly background: stringsource

readonly foreground: stringsource

readonly syntax: Readonly<Record<string, string>>source

interface VariableCollection

source

readonly name: stringsource

readonly defaultModeId: VariableModeIdsource

readonly activeModeId?: VariableModeIdsource

The mode this document shows where no page or layer chooses one (see VariableModes). It defaults to defaultModeId when omitted.

readonly modeOrder: readonly VariableModeId[]source

readonly modes: Readonly<Record<string, VariableMode>>source

readonly variables: Readonly<Record<string, VariableDefinition>>source

interface VariableMode

source

readonly name: stringsource

type VariableDefinition = | VariableDefinitionBase<"color", string> | VariableDefinitionBase<"number", number> | VariableDefinitionBase<"string", string> | VariableDefinitionBase<"boolean", boolean>

source

type VariableType = "color" | "number" | "string" | "boolean"

source

type VariableValue = string | number | boolean

source

type VariableProperty = | "visibility" | "opacity" | "width" | "height" | "cornerRadius" | "fillColor" | "strokeColor" | "strokeWidth" | "gap" | "wrapGap" | "columnGap" | "rowGap" | "paddingTop" | "paddingRight" | "paddingBottom" | "paddingLeft" | "fontFamily" | "fontSize" | "fontWeight" | "lineHeight" | "letterSpacing" | "textColor"

source

type VariableBindings = Readonly<Partial<Record<VariableProperty, VariableId>>>

source

const VARIABLE_PROPERTY_TYPES: Readonly<Record<VariableProperty, VariableType>>

source

interface LocatedVariable

source

readonly collectionId: stringsource

readonly collection: VariableCollectionsource

readonly variableId: VariableIdsource

readonly variable: VariableDefinitionsource

function findVariable( theme: DocumentTheme, variableId: VariableId | string ): LocatedVariable | undefined

source

function resolveVariableValue( theme: DocumentTheme, variableId: VariableId | string, modes?: VariableModes ): VariableValue | undefined

source

The variable’s value in the mode its collection shows under modes (the modes in effect at a layer, see variableModesAt): the inherited choice, else the collection’s active mode, else its default mode. A mode without a value reads the default mode’s value.

function listVariablesForProperty( theme: DocumentTheme, property: VariableProperty ): readonly LocatedVariable[]

source

function variableSupportsProperty( variable: VariableDefinition, property: VariableProperty ): boolean

source

function nodeSupportsVariableProperty( node: SceneNode, property: VariableProperty ): boolean

source

### Variable modes

A page, frame, group, component or instance can choose a mode per variable collection in variableModes. A collection it leaves out is Auto: the layer inherits the mode from its parent, up to the page, and a page without one uses the collection’s activeModeId. An instance’s modes apply to its component’s layers. Stored bound values are written for the active modes; the resolver and the page compiler write them again for layers under other modes.

type VariableModes = Readonly<Record<string, VariableModeId>>

since 0.26.0source

A variable mode per collection, keyed by collection ID. A collection left out is Auto: the layer takes the mode of its parent, up to the page, and a page without one uses the collection’s activeModeId (else its defaultModeId). Omitted when empty.

function inheritVariableModes( parent: VariableModes | undefined, own: VariableModes | undefined ): VariableModes | undefined

since 0.26.0source

The modes a layer uses: its parent’s modes with the layer’s own choices on top. A collection the layer leaves out (Auto) keeps the parent’s mode. Returns parent itself when own chooses nothing.

function variableModeFor( collectionId: string, collection: VariableCollection, modes?: VariableModes ): VariableModeId

since 0.26.0source

The mode a collection shows under modes: the inherited choice, else the collection’s activeModeId, else its defaultModeId.

function variableModesAt( document: DesignDocument, nodeId: NodeId ): VariableModes | undefined

since 0.26.0source

The modes in effect at a stored node: the page’s modes, then each ancestor’s, then the node’s own. A layer of a component (outside any page) starts from the document’s active modes at the component root; an instance applies its own modes on top when it is resolved. Undefined means every collection shows its active mode.

function inheritedVariableModes( document: DesignDocument, nodeId: NodeId ): VariableModes | undefined

since 0.26.0source

The modes a stored node inherits: variableModesAt its parent, or the page’s modes for a page root. The node’s own choices are not included.

function locatedVariableValue( located: LocatedVariable, modes?: VariableModes ): VariableValue | undefined

since 0.26.0source

resolveVariableValue for a variable already found with findVariable.

function applyVariableBindings( document: DesignDocument, node: SceneNode, modes: VariableModes | undefined ): SceneNode

since 0.26.0source

Writes each of the node’s variable bindings in the modes modes into the bound field (see withVariableValue). A binding to a missing variable, or one the node cannot take, is skipped. A text layer that sizes itself is measured again. Returns node itself when it has no bindings.

function withVariableValue( theme: DocumentTheme, node: SceneNode, property: VariableProperty, value: VariableValue ): SceneNode

since 0.26.0source

Writes one variable value into the node field it is bound to, the way the editor does when a variable is applied: a color drives the bottom fill or the first stroke, a radius sets every corner, a text property restyles every run. Sizes and opacity are clamped. A value of the wrong type changes nothing.

function bindingsDependOnModes( theme: DocumentTheme, node: SceneNode, modes: VariableModes | undefined ): boolean

since 0.26.0source

Whether a node’s variable bindings read any collection in a mode other than its active mode under modes. Stored values are written for the active modes, so only such a node needs applyVariableBindings.

function variableModesKey( theme: DocumentTheme, modes: VariableModes | undefined ): string

since 0.26.0source

A stable text form of modes for cache keys: the collections in sorted order. Modes that match a collection’s active mode are left out, so Auto and an explicit choice of the active mode give the same key.