4. The tree

4.1 tree#

"tree": {
  "seq": 12,
  "document": { },
  "pages": { },
  "nodes": { },
  "styles": { },
  "variableCollections": { },
  "variables": { },
  "libraries": { },
  "flows": { },
  "comments": { },
  "versions": { },
  "assets": { },
  "deletedComponents": { }
}

Every member is optional; a missing map is empty. A map is written as {} when empty.

Maps, not arrays. Collections that two people can grow at the same time are JSON objects keyed by id, ordered (where order matters) by a fractional index member. Two branches that add an entry then never edit the same line of the tree, and events can name any entry by id. The Plugin API layer presents them as Figma’s arrays (figma.root.children, collection.modes, collection.variableIds).

Lists of values are arrays. Fills, strokes, effects, export settings, layout grids, reactions and similar lists are arrays, set and replaced as a whole, exactly as Figma’s immutable arrays (CMD-15).

4.2 Document and pages#

document

Page (tree.pages, key: pg- id)

A document has at least one page (DOC-1). The top-level nodes of a page have the page id as parent. A page’s prototype flows are the flows whose pageId is the page (4.12).

4.3 The node map, parent and the fractional index#

tree.nodes maps every node id to its node. There are no nested children arrays. The tree of layers is given by two members of every node:

The fractional index (DOC-3) is a non-empty string over the 62 characters 0-9, A-Z, a-z. Siblings are ordered by comparing their index strings character by character by code point ("0" < "9" < "A" < "Z" < "a" < "z"), a shorter string before a longer one that starts with it. This is plain string comparison in JavaScript and byte comparison in any language; a reader needs nothing else.

• Ascending index is back to front, as Figma’s children: the first child is painted first, at the bottom; the last is on top. The Layers panel lists them reversed. In an auto layout frame, ascending index is also the flow order (first item first); itemReverseZIndex only changes the painting order.
• Writers generate keys between neighbours. To put a node between siblings with keys a and b, a writer picks any key k with a < k < b. To put it first or last, any key below the first or above the last. The extension uses the algorithm of the fractional-indexing package (generateKeyBetween), whose keys look like a0, a1, a0V, Zz. Other writers may use any scheme that respects the order; readers never parse a key.
• Moving a node changes only its own index (and parent, when it changes). No sibling is renumbered, so two branches that move or insert different nodes edit different lines.
• Ties are broken by id. Two branches can insert at the same place and generate the same key. Siblings with equal index are ordered by their ids, compared the same way. A writer that inserts between two siblings with equal keys first gives one of them a fresh key (a node.reorder in the same group).
• Keys grow. Repeated inserts at the same place make keys longer. Consolidation shortens long keys (section 7).

The same scheme orders pages, styles, variables within their collection, modes within their collection, flows within their page and annotation categories.

A node in the flat map, the button label of section 12:

"nd-2b7d9e4f6a10": {
  "type": "TEXT",
  "name": "Label",
  "parent": "nd-8a3f1c5e7b92",
  "index": "a0",
  "characters": "Button",
  "textStyleId": "st-4d6f8a0c2e1b",
  "fills": [{"type": "SOLID", "color": {"r": 1, "g": 1, "b": 1}}],
  "componentPropertyReferences": {"characters": "Label#a41c"}
}

The key of the map is the id; the node object does not repeat it. Readers add id to the node object in memory.

Constraints on the structure (repairs in section 6):

• A node’s parent exists, and following parent from any node ends at a page, without a cycle.
• SECTION nodes have a page or another section as parent.
• Children are allowed only under FRAME, GROUP, SECTION, COMPONENT, COMPONENT_SET, BOOLEAN_OPERATION, SLOT and (for slot content) instance slots (4.8). A GROUP or BOOLEAN_OPERATION has at least one child.
• COMPONENT_SET has only COMPONENT children.

4.4 Shared node properties#

Every node has type, name, parent and index. All other properties are optional and take the default shown when absent. A property that a node type does not have (for example characters on a FRAME) is kept but ignored.

4.4.1 Identity, visibility and geometry#

4.4.2 Constraints and layout as a child#

layoutGrow and layoutAlign of the Plugin API are derived from the sizing properties and not stored.

4.4.3 Auto layout (frames, components, component sets, instances)#

primaryAxisSizingMode and counterAxisSizingMode of the Plugin API are derived from layoutSizingHorizontal and layoutSizingVertical and not stored.

4.4.4 Appearance#

4.4.5 Bindings and modes#

A bound or styled property keeps a plain value next to the reference. itemSpacing stays written when boundVariables.itemSpacing exists; fills stays written when fillStyleId exists. The reference wins when it resolves; the plain value is the fallback when the variable or style is missing (deleted on another branch, library unavailable). Writers write the resolved value when they bind and do not update it afterwards. This is Figma’s model, and it keeps a file readable without resolving references.

4.4.6 Export settings#

exportSettings (EXP-1) is an array, default [], in Figma’s shape:

"exportSettings": [
  {"format": "PNG", "suffix": "@2x", "constraint": {"type": "SCALE", "value": 2}},
  {"format": "SVG", "svgOutlineText": true, "svgIdAttribute": false, "svgSimplifyStroke": true, "useAbsoluteBounds": false}
]

format is PNG, JPG, WEBP, SVG or PDF; constraint.type is SCALE, WIDTH or HEIGHT.

4.4.7 Prototype reactions#

reactions (PRO-1 – PRO-4) is an array, default [], in Figma’s shape. Durations and delays are in seconds, as in Figma.

"reactions": [
  {
    "trigger": {"type": "ON_CLICK"},
    "actions": [
      {
        "type": "NODE",
        "destinationId": "nd-6b8d0f2a4c1e",
        "navigation": "NAVIGATE",
        "transition": {"type": "SMART_ANIMATE", "easing": {"type": "EASE_OUT"}, "duration": 0.3},
        "preserveScrollPosition": false
      }
    ]
  }
]

A destinationId that names no node makes the action inert; the reader keeps it and ud lint reports it.

4.4.8 Developer handoff#

A code map entry:

"codeMap": {
  "component": "Button",
  "source": "src/ui/Button.tsx",
  "language": "tsx",
  "props": {
    "Size": {"prop": "size", "values": {"sm": "sm", "md": "md", "lg": "lg"}},
    "Label#a41c": {"prop": "children"},
    "Show icon#5d02": {"prop": "icon", "when": true}
  }
}

Keys of props are component property keys (4.8). Mappings in the ud.codeMap setting override the file.

4.4.9 Annotations as nodes#

Measurement annotations, connectors and sticky notes that stand on the canvas are nodes of their own (CONNECTOR, STICKY, 4.6.8). Annotations attached to a node are the annotations property above.

4.4.10 Plugin data#

Values are strings, as in Figma. Setting a value to "" removes the key (Figma’s rule); in a merge patch the key is set to null. Because the patch merges per key (5.9), two branches that write different keys both survive. Pages, styles, variables and collections have the same two properties.

4.5 Derived values#

These are computed by the core on every surface and never written (LAY-9, ARC-001):

A derived value found in the file (hand edit, older writer) is ignored and dropped at the next consolidation. ud get_metadata and ud inspect report derived values for readers that do not run the core.

4.6 Node types#

Node types and type-specific properties. Every type has the shared properties of 4.4 that apply to it.

4.6.1 Rectangle and image#

A rectangle’s corners are cornerRadius, the four corner properties and cornerSmoothing. An image is a rectangle with an image fill (4.7.4); the Image tool names it after the file. There is no image node type.

4.6.2 Ellipse#

arcData (DRW-3), Figma’s shape: {"startingAngle": 0, "endingAngle": 6.2831853, "innerRadius": 0}. The angles are in radians, as in Figma, so that the Plugin API maps one to one; this is the only angle in the format not in degrees. innerRadius is a ratio from 0 to 1 (donuts). Default: a full ellipse.

4.6.3 Polygon and star#

pointCount, integer 3 or more, default 3 for polygons and 5 for stars. innerRadius of a star is the ratio of inner to outer radius, 0 to 1, default 0.38.

4.6.4 Vector and vector network#

vectorNetwork (DRW-4) in Figma’s shape. Coordinates are px in the node’s own coordinate system.

"vectorNetwork": {
  "vertices": [
    {"x": 0, "y": 0},
    {"x": 24, "y": 0, "strokeCap": "ARROW_LINES"},
    {"x": 12, "y": 18, "cornerRadius": 2, "handleMirroring": "ANGLE_AND_LENGTH"}
  ],
  "segments": [
    {"start": 0, "end": 1},
    {"start": 1, "end": 2, "tangentStart": {"x": 0, "y": 8}, "tangentEnd": {"x": 6, "y": 0}},
    {"start": 2, "end": 0}
  ],
  "regions": [
    {"windingRule": "NONZERO", "loops": [[0, 1, 2]], "fills": [{"type": "SOLID", "color": {"r": 0, "g": 0, "b": 0}}]}
  ]
}

• vertices[]: x, y; optional strokeCap, strokeJoin, cornerRadius, handleMirroring (NONE, ANGLE, ANGLE_AND_LENGTH).
• segments[]: start and end are vertex indexes; tangentStart and tangentEnd are handle offsets, absent for a straight segment. A vertex used by more than two segments is a branch.
• regions[]: closed areas, each a list of loops of segment indexes, with windingRule (NONZERO, EVENODD) and optional fills and fillStyleId. An area that is in no region is not filled: this is how a fill is toggled per area.

The whole network is one property: an edit replaces it. An arrow drawn with the Arrow tool (DOC-2) is a VECTOR with two vertices whose end vertex has an arrow strokeCap.

4.6.5 Boolean operation#

booleanOperation: "UNION", "SUBTRACT", "INTERSECT", "EXCLUDE", default "UNION" (DRW-5). Children stay editable; the result is derived. Flatten replaces the node by a VECTOR (a node.delete and a node.create in one group).

4.6.6 Text with styled runs#

Node-level text properties apply to the whole text. styledRuns (TXT-2) lists ranges whose properties differ:

"styledRuns": [
  {"start": 0, "end": 9, "fontName": {"family": "Inter", "style": "Bold"}},
  {"start": 20, "end": 35, "fills": [{"type": "SOLID", "color": {"r": 0.23, "g": 0.36, "b": 0.97}}], "hyperlink": {"type": "URL", "value": "https://softforge.dev"}},
  {"start": 36, "end": 80, "listOptions": {"type": "UNORDERED"}, "indentation": 1}
]

• start and end are offsets in UTF-16 code units, end exclusive, as Figma’s setRange… functions.
• Runs are sorted by start and do not overlap. A run carries only the properties that differ from the node.
• A run may carry: fontName, fontSize, fontVariations, letterSpacing, lineHeight, textCase, textDecoration, fills, fillStyleId, textStyleId, hyperlink, openTypeFeatures, boundVariables; and, covering whole paragraphs only, listOptions ({type: "ORDERED" or "UNORDERED" or "NONE"}), indentation, paragraphSpacing, paragraphIndent.
• characters and styledRuns belong together: a writer that changes the text writes both in the same set. A reader that finds runs beyond the end of the text cuts them to the text, and drops runs that become empty (9.2).

4.6.7 Slot#

SLOT (CMP-5) is a frame-like container inside a component. It has the frame properties and slotPropertyKey, the key of the SLOT component property that exposes it. Its children in the main component are the default content. In an instance, content placed into the slot is stored as real nodes (4.8).

4.6.8 Slice, connector and sticky note#

• SLICE: geometry and exportSettings; not rendered.
• CONNECTOR (DOC-2): connectorStart and connectorEnd, each {"endpointNodeId": id, "magnet": "AUTO" or "TOP" or "LEFT" or "BOTTOM" or "RIGHT" or "CENTER"} or {"position": {x, y}}; connectorLineType (ELBOWED, STRAIGHT, CURVED); connectorStartStrokeCap, connectorEndStrokeCap; text (a nested text object with characters and text properties); strokes as usual.
• STICKY (DOC-2): text as above, fills, authorVisible (boolean), authorName (string).

4.7 Paints and effects#

4.7.1 Colours and units#

Where Figma uses an RGB colour with a separate opacity, so does the file: the color of a SOLID paint is {r, g, b} without a, and its transparency is the paint’s opacity. Everywhere else (gradient stops, effects, layout grids, variable values of type COLOR) a colour has a. A reader that finds a in a solid paint’s color multiplies it into the paint’s opacity.

Numbers are written with at most 6 significant decimals; writers round, readers accept any JSON number.

4.7.2 Paint#

Every paint has type and optional visible (default true), opacity (default 1) and blendMode (default "NORMAL").

4.7.3 Variable-bound paints#

A paint bound to a variable keeps its plain colour as the fallback (4.4.5):

{"type": "SOLID", "color": {"r": 0.231, "g": 0.357, "b": 0.965}, "boundVariables": {"color": {"type": "VARIABLE_ALIAS", "id": "vr-7b9d1f3a5c7e"}}}

A variable from a library is named by a qualified id, "lib-…/vr-…" (4.11).

4.7.4 Image paint#

{
  "type": "IMAGE",
  "imageHash": "sha256-9c2f0e6b1a7d3c5e8f4b2a1d0c9e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e",
  "scaleMode": "FILL",
  "rotation": 0,
  "filters": {"exposure": 0, "contrast": 0.1, "saturation": 0, "temperature": 0, "tint": 0, "highlights": 0, "shadows": 0}
}

4.7.5 Effect#

Figma’s shape (STY-6):

Each effect may carry boundVariables for color, radius, spread, offsetX, offsetY.

4.8 Components, instances, overrides and slots#

Main component. A COMPONENT node is a frame that other nodes can instantiate (CMP-1). It and its descendants are ordinary nodes in the node map. A COMPONENT_SET holds COMPONENT children that are its variants (CMP-4); a variant’s properties come from its name, Size=md, State=Default.

Component property definitions (CMP-5) are on the component, or on the component set for a set:

"componentPropertyDefinitions": {
  "Size": {"type": "VARIANT", "defaultValue": "md", "variantOptions": ["sm", "md", "lg"]},
  "Label#a41c": {"type": "TEXT", "defaultValue": "Button", "description": "Button text"},
  "Show icon#5d02": {"type": "BOOLEAN", "defaultValue": false},
  "Icon#77b0": {"type": "INSTANCE_SWAP", "defaultValue": "nd-0e2c4a6b8d1f", "preferredValues": [{"type": "COMPONENT", "key": "nd-0e2c4a6b8d1f"}]},
  "Content#c3e1": {"type": "SLOT", "description": "Body of the card"}
}

Keys are Figma’s: a variant property is its plain name; any other property is <name>#<4 hex digits>, the suffix chosen at random when the property is created so that renaming the property keeps its key. Layers inside the component refer to these keys through componentPropertyReferences (4.4.5). For a variant property, variantOptions is derived from the variants’ names and written only by consolidation.

Instance. An INSTANCE node shows a copy of its main component. Its sublayers are not stored; they are derived from the main component every time it is read, which is what makes a main component change reach every instance at once (CMP-2).

Override paths. A sublayer of an instance is named by the ids of the nodes from the main component down to it, joined by /. For a layer nd-b directly inside the main component the path is nd-b. For a layer nd-d inside a nested instance nd-c whose component contains nd-d, the path is nd-c/nd-d.

"overrides": {
  "nd-2b7d9e4f6a10": {"fills": [{"type": "SOLID", "color": {"r": 0.1, "g": 0.1, "b": 0.1}}]},
  "nd-5a1c3e7f9b20/nd-0d2f4b6a8c1e": {"visible": false},
  "nd-5a1c3e7f9b20": {"componentId": "nd-1e3a5c7d9f02"}
}

• An override is a merge patch of the sublayer’s properties (5.9): it holds only what differs.
• componentId in an override swaps a nested instance (CMP-3, CMP-6).
• The derived id of a sublayer is <instance id>/<override path>, for example nd-e7a9c1b3d5f0/nd-2b7d9e4f6a10. The Plugin API returns it as the sublayer’s id, ud accepts it wherever a node id is accepted, and setting a property on it writes an instance.override event.
• An override whose path no longer matches a layer of the main component (the layer was deleted, or the instance was swapped) is kept but has no effect; it applies again if the layer returns. ud lint reports such dormant overrides; instance.reset removes them.

Slots. Content placed into a slot of an instance (CMP-5) is stored as ordinary nodes whose parent is the derived id of the slot: "parent": "nd-e7a9c1b3d5f0/nd-7f9b1d3c5e2a". When the instance has content in a slot, that content replaces the slot’s default content. If the slot disappears from the main component, its content nodes are orphans (6.5).

Detach. instance.detach turns the instance into a FRAME with the same id and writes its derived sublayers as real nodes with new ids (5.11.4).

4.9 Styles#

tree.styles maps st- ids to styles (VAR-1).

Nodes refer to styles with fillStyleId, strokeStyleId, effectStyleId, textStyleId and gridStyleId, and keep the plain values next to the reference (4.4.5). A change of a style changes every user at once, because the style wins when it resolves.

4.10 Variables, collections, modes and aliases#

Variable collection (tree.variableCollections, key vc- id, VAR-2):

Variable (tree.variables, key vr- id):

Resolution. The value of a variable for a node is found as follows:

1. The mode: the nearest explicitVariableModes entry for the variable’s collection, on the node or an ancestor, then on the page; else the collection’s defaultModeId.
2. The value: valuesByMode[mode]; if absent, valuesByMode[defaultModeId]; if absent, the type’s zero (transparent black, 0, "", false), with a warning from ud lint.
3. An alias is resolved again from step 1, for the aliased variable’s collection, with the same node. A chain longer than 32 or a cycle resolves to the type’s zero and is reported (9.2). Writers refuse to create a cycle (VAR-3).

valuesByMode merges per mode (5.9): two branches that set the Light and the Dark value of one variable both survive.

4.11 Libraries#

A file that publishes a library has document.library (4.2). A file that uses one lists it in tree.libraries (VAR-7):

Qualified ids. A reference to something in a library is the library id, a slash and the id inside the library: lib-1f3b5d7a9c0e/nd-8a3f1c5e7b92, lib-1f3b5d7a9c0e/vr-7b9d1f3a5c7e. It is accepted wherever the local id would be: componentId, style ids, variable aliases, boundVariables.

Imported copies. imported keeps everything this file uses from the library, so the file renders when the library is missing, on another branch or not yet updated:

"imported": {
  "nodes": { "nd-8a3f1c5e7b92": { }, "nd-2b7d9e4f6a10": { } },
  "styles": { "st-4d6f8a0c2e1b": { } },
  "variableCollections": { "vc-2c4e6a8b0d1f": { } },
  "variables": { "vr-7b9d1f3a5c7e": { } }
}

Each map has the shape of the tree’s map of the same name, with the library’s ids. For a component, the copy holds the component and all its descendants. The copies are what instances and references use; the library file itself is read only to find updates. When the library’s current tree hash differs from acceptedHash, the editor shows “Updates available” (VAR-8); accepting writes a library.accept event that carries the new copies and the new hash.

4.12 Prototype flows#

tree.flows maps fl- ids to flows (PRO-6, DOC-1):

Figma’s page.flowStartingPoints is derived from the page’s flows.

4.13 Comments#

tree.comments maps cn- ids to comments (COL-3):

Replies are ordered by at, then by id. A thread whose anchor node was deleted keeps its last absolute position on its page.

4.14 Named versions#

tree.versions maps vs- ids to named versions (COL-2):

The version is the document as it was just before its version.save event, in file order. A seq would not name that state across branches (two branches give one number to different events), so the hash does; it also tells whether a working copy is still at the version (--if-version, CLI-001).

Consolidation keeps versions (COL-2). The document as it was at a version is computed from the WAL when the version.save event is still in it; otherwise it is read from the git history of the file, from the last commit whose file still holds the version.save event (ud versions show <id>), and checked against treeHash. A version older than both is listed but cannot be previewed.

4.15 Asset metadata#

tree.assets maps content hashes to metadata of the files in the assets folder (section 8):

The bytes are never in the design file (NFR-3).

4.16 Deleted components#

tree.deletedComponents maps the id of a deleted main component (COMPONENT or COMPONENT_SET) to a snapshot of its subtree, taken when it was deleted while instances still used it (CMP-2):

"deletedComponents": {
  "nd-8a3f1c5e7b92": {
    "deletedAt": "2026-10-08T09:00:00.000Z",
    "deletedBy": "Grace",
    "nodes": {
      "nd-8a3f1c5e7b92": {"type": "COMPONENT", "name": "Button", "parent": "pg-6f7e8d9c0b1a", "index": "a0", "…": "…"},
      "nd-2b7d9e4f6a10": {"type": "TEXT", "name": "Label", "parent": "nd-8a3f1c5e7b92", "index": "a0", "…": "…"}
    }
  }
}

• Instances keep rendering. An instance whose componentId names an entry here derives its sublayers from the snapshot exactly as from a live component, overrides included, and the editor marks it “Deleted component”. The same file therefore renders the same whatever the reader has seen before (2.1), and the snapshot survives consolidation (section 7).
• The snapshot is a copy, not a component. It is not on any page, is not offered in the Assets panel, and no event changes it. instance.detach works on such an instance as on any other.
• Restore. component.restore (5.11.3) puts the nodes back into tree.nodes with their ids and removes the entry, as Figma’s “Restore component”. Ids are never reused (5.5), so the ids are free.
• Dropped when unused. Consolidation drops an entry no instance refers to any more (7).

How the snapshot gets there is in node.delete (5.11.2).