Composition

#Overview

$type: "composition" is the SXL Studio contract that describes a Figma component as JSON. It is the single source of truth that turns design intent into repeatable Generate and Apply runs in Figma.

At a glance, a composition is built from these blocks:

#Updates

Release history for the Composition type. The newest release is on top; open an entry to see what changed.

#Where It's Used

Use Composition whenever you need predictable, repeatable component building in a design system.

Common use cases:

• generate new components / component sets from a token file;
• update existing components without rebuilding them (Apply);
• keep variant structure, slot content, and styling rules in one source;
• hand a deterministic component model to engineers and agents.

How SXL Studio works with it

1. You author JSON manually or bootstrap it from Get Code.
2. SXL Studio parses and validates the file.
3. Generate creates a new component/set, or Apply updates tracked nodes.
4. Tracking is stored in diff-id.json so updates stay stable between runs.

React / Vue 3 transformation

Composition JSON is machine-readable and stable enough for custom transformation scripts. The plugin uses it for Figma generation, and you can read structure + styles to map a component to your framework. In Dev Mode, SXL Studio also produces dedicated codegen output (including Vue 3) you can use as a reference.

#Generate

Generate builds a new component or component set from the JSON: it reads structure, expands props into variants, applies styles, and resolves token references ({path.to.token}) at build time. Use it for a component that does not exist in Figma yet.

Pre-check before Generate / Apply

Fix JSON editor errors before running. Typical causes:

• unresolved token references ({path.to.token});
• invalid alias syntax;
• schema violations (for example an invalid SLOT shape).

Recommended flow: open JSON → resolve all validation issues → save → run Generate or Apply.

Get Code

Get Code reads the selected Figma node(s) and generates a Composition JSON draft — a fast starting point you then refine by hand. With multi-select, output may contain $synthetic: true to indicate a synthetic set construction (informational only).

Grid settings

Grid controls how variants are laid out on the canvas in a generated component set. It changes placement only — never token semantics or the JSON contract.

• Columns / Rows assign variant axes explicitly; multiple axes in one zone nest from outer to inner.
• states axes are not placed in Columns / Rows — they render as a trailing state band below or to the right.
• spacing is split by meaning: variant gap, prop/group gap, component-set padding, label gap, and state-band gap.
• grid annotations render outside the set on the same placement tracks, so labels match preview and output.

#Apply

Apply updates an existing tracked component in place, using diff-id.json tracking so identity and instances are preserved.

Automatic mode picks the operation from context (selected anchor, tracking, local component presence).

#Target resolution and preservation

Every selected composition root is processed with its own explicit anchor. SXL Studio resolves the complete selection before the first canvas mutation, so a chain such as sm → md and md → lg cannot make the first rename steal the second JSON file's target.

• A unique live identity updates that Component or ComponentSet in place. Its Figma node ID stays stable, so existing instances keep their component link.
• In Automatic mode, a stale or cross-file identity with no live candidate in the current Figma document creates new output.
• An explicit Apply without a matching target asks you to select the intended root or use Generate. Ambiguous, conflicting, or incompletely scanned candidates stop before mutation.
• Apply preserves consumer overrides. It does not blanket-reset text, component properties, instance swaps, or properties the composition does not author.
• Generate and Apply from the plugin UI do not require Bridge. Remote Connect execution and Git Sync Local Storage still use Bridge for their own transport/storage contracts.

SXL Studio manages a portable source identity under $extensions["sxl.studio"].composition. Older JSON without this block remains supported; a successful Generate or anchored Apply attempts to backfill it without rewriting unrelated $extensions:

{
  "$extensions": {
    "sxl.studio": {
      "composition": {
        "id": "11111111-1111-4111-8111-111111111111",
        "roots": [
          {
            "nodeId": "21649:1480",
            "key": "figma-component-key",
            "type": "COMPONENT_SET"
          }
        ]
      }
    }
  }
}

This block is managed metadata, not an authoring input. If storage is temporarily unavailable, the canvas operation stays successful and reports a warning; identity persistence is retried on a later run.

Adopt & Audit existing components

A component created manually before Composition JSON existed does not need to be deleted. Use the composition badge context menu:

Adopt is conservative: it keeps component identity (instances elsewhere keep their link), checks that variant names match the JSON matrix, and does not rewrite layers, styles, or properties until an audit/apply confirms the real structure.

#Root fields

The top-level keys of a composition file.

#Structure

structure is the layer tree the generator builds. Every node needs a tag and a class; everything else is optional.

Node fields

"structure": {
  "tag": "FRAME",
  "class": "root",
  "name": "Root",
  "children": []
}

Per-field JSON examples:

{ "tag": "FRAME", "class": "card" }

{ "tag": "TEXT", "class": "label", "name": "Label", "content": "Continue" }

{ "tag": "INSTANCE", "class": "icon", "ref": { "component": "circle-info", "properties": { "size": "md" } } }

{ "tag": "SLOT", "class": "content-slot", "slot": { "default": "WButton", "preferred": ["WButton", "WChip"] } }

{ "tag": "FRAME", "class": "row", "description": "Header row", "children": [{ "tag": "TEXT", "class": "title", "content": "Title" }] }

Supported tag values

Per-tag JSON examples:

{ "tag": "FRAME", "class": "card", "children": [] }

{ "tag": "TEXT", "class": "label", "content": "Continue" }

{ "tag": "COMPONENT", "class": "chip" }

{ "tag": "INSTANCE", "class": "cta", "ref": { "component": "WButton", "properties": { "variant": "primary" } } }

{ "tag": "ICON", "class": "leading-icon", "ref": { "component": "circle-info" } }

{ "tag": "SLOT", "class": "content-slot", "slot": { "default": "WButton" } }

{ "tag": "RECTANGLE", "class": "bg" }

{ "tag": "ELLIPSE", "class": "avatar-mask" }

{ "tag": "LINE", "class": "divider" }

{
  "tag": "VECTOR",
  "class": "body-shape",
  "vectorPaths": [{ "data": "M 0 140 L 564 140 L 540 0 L 24 0 Z", "windingRule": "NONZERO" }],
  "viewBox": [0, 0, 564, 140]
}

Use VECTOR when a shape is not a rectangle, ellipse, or line — a slanted button body, a wave, a tab notch, a custom badge. It accepts SVG-like vectorPaths or a Figma-like vectorNetwork for editable vertices, and takes the same visual styles as other shapes. Vertex rounding can be tokenized from styles via vectorCornerRadii.

Slanted button pattern

Keep editable shape geometry in structure, and drive color/size/rounding from styles. The middle stays a normal auto-layout FRAME so text and icons behave normally.

{
  "tag": "FRAME",
  "class": "wrap",
  "children": [
    { "tag": "VECTOR", "class": "left-shape", "vectorNetwork": { "vertices": [{ "x": 18, "y": 56 }, { "x": 0, "y": 56 }, { "x": 10, "y": 0 }, { "x": 18, "y": 0 }], "segments": [{ "start": 0, "end": 1 }, { "start": 1, "end": 2 }, { "start": 2, "end": 3 }, { "start": 3, "end": 0 }], "regions": [{ "windingRule": "NONZERO", "loops": [[0, 1, 2, 3]] }] } },
    { "tag": "FRAME", "class": "content", "children": [{ "tag": "TEXT", "class": "label", "content": "PRIMARY" }] }
  ]
}

".left-shape": { "widthType": "fixed", "heightType": "fixed", "width": 18, "height": 56, "fill": "{button.bg.accent}", "vectorCornerRadii": [0, "{radius.md}", "{radius.md}", 0] }

vectorCornerRadii accepts an array (by vertex order) or an object ({ "1": "{radius.md}" }). Vertex indexes are zero-based. VECTOR is not a raw SVG import — put curves, skew, and cut-outs into vectorPaths / vectorNetwork.

SLOT modes and rules

SLOT has strict modes: reference mode (a slot config with an optional ref template) or children mode (inline children). Never both.

{
  "tag": "SLOT",
  "class": "content-slot",
  "slot": { "default": "WButton", "preferred": ["WButton", "WChip"] },
  "ref": { "component": "WButton", "properties": { "size": "md" } }
}

{
  "tag": "SLOT",
  "class": "rows",
  "children": [{ "tag": "FRAME", "class": "row", "children": [] }]
}

Constraints: a SLOT cannot have both slot and non-empty children; SLOT.ref is only valid in reference mode. A SLOT with exactly one INSTANCE child (with ref, no slot) is treated as reference-mode shorthand.

ref for INSTANCE / SLOT

ref.styles is for the materialized referenced INSTANCE root. Use it when the default instance itself needs layout or paint bindings, for example an icon size binding inside a SLOT. It supports the same style aliases and token refs as normal styles, including widthType, heightType, width, height, fill, and color.

The host style block still styles the composition node itself. In reference-mode slots, use refStyles inside a normal style block when variants need to override the referenced root. refStyles merges over ref.styles and is applied only while the current slot child still matches ref.component; it is not cascaded to a preferred/user swap such as WBadge.

{
  "tag": "SLOT",
  "class": "leading-slot",
  "slot": { "default": "circle-info", "preferred": ["circle-info", "WBadge"] },
  "ref": {
    "component": "circle-info",
    "properties": { "style": "filled" },
    "styles": {
      "widthType": "fixed",
      "heightType": "fixed",
      "width": "{sz.fixed.reg.xs}",
      "height": "{sz.fixed.reg.xs}"
    }
  }
}

"styles": {
  "$placement=inner .leading-slot": {
    "refStyles": {
      "width": "{sz.fixed.reg.3xs}",
      "height": "{sz.fixed.reg.3xs}"
    }
  }
}

ref.nested — target nested instances by layer name:

"nested": {
  "Badge": {
    "properties": { "label": "3" },
    "icon": { "component": "fire-3", "properties": { "style": "filled" } }
  }
}

ref.slots — override slots inside the referenced instance (op: replace, append, patch):

"slots": {
  "footer": {
    "op": "replace",
    "nodes": [{ "component": "WButton", "name": "apply", "properties": { "variant": "primary" } }]
  }
}

A component-set variant can wrap a different existing component by overriding its ref from a variant selector, so one INSTANCE node serves the whole wrapper set:

"styles": {
  "$item=neutral-secondary-sm .item": {
    "ref": { "component": "WButton", "properties": { "style": "neutral", "variant": "secondary", "size": "sm" } }
  }
}

#Props

props declares every allowed value for each axis; each combination becomes one generated variant.

"props": {
  "size": ["sm", "md", "lg"],
  "state": ["default", "hover", "active"],
  "compact": [true, false]
}

Behavior: selector matching compares values as strings; an axis with default uses it as fallback for missing value-specific rules, otherwise the first value is the fallback. Keep the axis count intentional — variant combinations grow multiplicatively.

states (mutually-exclusive axes)

states lists axes from props that behave like mutually-exclusive UI conditions (:disabled, :loading) rather than combinable variants. They are excluded from the cartesian product — each non-default value adds a single variant on top of the defaults.

"props": {
  "_state": ["default", "hover", "focus", "select"],
  "loading": ["false", "true"],
  "disabled": ["false", "true"]
},
"states": ["loading", "disabled"]

Without states this is a 4 × 2 × 2 = 16-variant matrix; with states it compacts to 6 (4 interaction variants + loading=true + disabled=true). Rules: the off value is the axis's first value; every name in states must exist in props; Apply re-compacts an existing set declaratively. Keep normal visual choices (size, variant, tone, theme) in props only.

Codegen mapping:

• React / Vue: an axis whose options are exactly false / true becomes a boolean prop (e.g. loading?: boolean);
• DivKit: component sets are emitted through card.states / state_id; states only controls which variants are materialized, it does not generate a fake custom_type;
• a _-prefixed axis (e.g. _state) is an internal interaction-state axis, excluded from the public codegen API (the consumer's own :hover / :focus CSS drives it); non-_ axes like loading / disabled are emitted as real props.

The extended object form with combineWith (crossing a state with structural axes) is reserved but not yet implemented — using it raises a validation error.

#Component Properties

componentProperties defines native Figma properties exposed on instances.

One example per type:

"title": { "type": "TEXT", "layer": "title", "defaultValue": "Promo title" }

"showMeta": { "type": "BOOLEAN", "layer": "meta", "defaultValue": true }

"icon": { "type": "INSTANCE_SWAP", "layer": "icon", "defaultValue": "circle-info", "preferred": ["circle-info", "star"] }

"media": { "type": "SLOT", "layer": "media-slot", "defaultValue": "WImageTile" }

"badge": { "type": "NESTED_INSTANCE", "layer": "Badge" }

layer rule: for TEXT, BOOLEAN, INSTANCE_SWAP, SLOT use the structure class; for NESTED_INSTANCE use the real nested Figma layer name.

#Styles

styles controls layer appearance, layout, and per-variant overrides. A key is a CSS-like class (.card), a legacy class (card), or a variant selector ($state=hover .card); blocks can be nested. Every property below is shown with its exact JSON spelling, grouped by purpose:

"styles": {
  ".root": { "direction": "row", "gap": 8, "padding": "12 16" },
  "$state=hover .root": { "background": "{color.brand.hover}" }
}

Selectors and cascade

• base styles apply first; matching selectors apply by specificity (more conditions win);
• same specificity → later JSON declaration wins;
• descendant selectors resolve through dot paths (.footer .item → footer.item);
• when a class repeats in different branches, prefer a full path (.header .item) over a bare .item.

"styles": {
  ".wrap": {
    "padding": 8,
    ".item": { "widthType": "fill" },
    "$state=active": { ".item": { "opacity": 1 } }
  }
}

Container and auto-layout

".header": { "direction": "row", "justifyContent": "space-between", "alignItems": "center", "gap": 8, "padding": "12 16" }

Layer size

targetAspectRatio is an accepted alias of aspectRatio.

Positioning

".badge": { "position": "absolute", "top": 8, "right": 8 }

Grid layout

Set when direction is grid.

Background, fill, color

color is CSS-like currentColor: on TEXT it sets the text fill; on ICON / icon instances it recolors the glyph (fill-based icons get a fill, stroke-based icons get a stroke). Token refs keep the variable binding; literal colors replace it. fill and strokes are lower-level — use them to target shape fills or a direct stroke. For a stroke-only icon, "fill": "none" keeps just the stroke paint.

Gradient background:

".hero": { "background": "linear-gradient(135deg, #7B5CFA 0%, #FA5CB4 100%)" }

Multi-layer background (image + overlay):

".media-slot": {
  "background": [
    { "type": "image", "url": "https://images.unsplash.com/photo-1498050108023-c5249f4df085", "scaleMode": "FILL", "opacity": 0.72, "blendMode": "NORMAL" },
    "rgba(0,0,0,0.24)"
  ]
}

Borders, stroke, corners

".card": { "border": "1px solid #E7EAF1", "borderRadius": 20 },
"$state=active .card": { "outline": "2px solid #0D6EFD", "outlineOffset": "2px" }

Shadows and effects

".card": { "boxShadow": [{ "x": 0, "y": 8, "blur": 24, "spread": 0, "color": "rgba(16,24,40,0.14)" }] },
"$state=hover .card": { "boxShadow": [{ "x": 0, "y": 14, "blur": 36, "spread": 0, "color": "rgba(16,24,40,0.20)" }] }

Typography

Set on a TEXT node.

".title": { "fontFamily": "Inter", "fontWeight": 600, "fontSize": 18, "lineHeight": "24px", "textAlign": "left", "textSizing": "height-auto" }

The composite typography / font key applies a full text style at once.

Visibility and reset

• visible: false keeps the layer in the variant but hides it in Figma;
• display: "none" omits the branch from the resolved variant;
• if both are set, display: "none" wins. When a later selector re-shows a branch, include the size/layout it needs.

"$loading=true": {
  ".button": {
    ".label": { "visible": false },
    ".spinner": { "display": "flex", "visible": true, "width": "{button.size.icon}" }
  }
}

CSS-like clearing values (write these to reset a property):

Instance control

Set on an INSTANCE node.

".action-main": { "component": "WButton", "instanceProperties": { "variant": "primary", "size": "md", "label": "Continue" } }

".badge": { "nestedInstanceProperties": { "Badge": { "label": "2" } } }

Variable modes and Figma metadata

".root": {
  "explicitVariableModes": { "Themes": "Dark" },
  "layoutGrids": [{ "pattern": "GRID", "sectionSize": 8, "color": { "r": 0, "g": 0, "b": 1, "a": 0.12 } }],
  "exportSettings": [{ "format": "PNG", "suffix": "@2x", "constraint": { "type": "SCALE", "value": 2 } }]
}

Clear an explicit mode for a collection with null, false, "none", "auto", or "unset".

#Transitions

Prototype transitions are defined at the composition root (shorthand or object form), never as a layer style key.

Shorthand — order is trigger animation duration easing [direction]:

"transitions": { "hover-in": "on-hover smart-animate 200ms ease-out" }

Object form with a condition:

"transitions": {
  "hover-in": {
    "trigger": "on-hover",
    "animation": "smart-animate",
    "duration": "200ms",
    "easing": "ease-out",
    "direction": "right",
    "condition": { "variable": "motion.enabled", "op": "==", "value": true }
  }
}

#Theme binding

themeBinding maps a variant axis (usually theme) to variable-collection modes for correct light/dark rendering.

"themeBinding": {
  "target": "root",
  "prop": "theme",
  "modes": {
    "light": { "type": "local", "collection": "Themes", "mode": "Light" },
    "dark": { "type": "local", "collection": "Themes", "mode": "Dark" }
  },
  "applyTo": ["variables", "typography", "textStyles", "effectStyles", "paintStyles"]
}

prop must exist in props. A mode source has type (local / library), collection, mode, and optional library. Each modes.<value> is either a flat source or a wrapped { primary, fallback[] }.

#Advanced fields

Embedded size / style

A composition file can embed DTCG size and style token blocks for self-contained component packs (namespaced by component name). They are optional and do not affect layout on their own.

"size": { "md": { "height": "40px", "paddingX": "16px" } },
"style": { "primary": { "bg": "{color.brand.primary}" } }

Slot-host pipeline

For host/item systems (segmented controls, tabs, item groups), slotHostPipeline wires a host set to its item set. slotItemComponentSetName is required. If any composition file defines slotHostPipeline, the legacy WSegmentControl defaults are not applied — declare every host/item set you rely on.

"slotHostPipeline": {
  "hostComponentSetName": "WSegmentControl",
  "hostCompositionTokenName": "WSegmentControl",
  "slotName": "item-group",
  "slotItemComponentSetName": "WSegmentControlItem"
},
"segmentIconPostPassRefMarkers": ["WSegmentControl", "WSegmentControlItem"]

Both keys are also accepted under a $figma wrapper ($figma.slotHostPipeline, $figma.segmentIconPostPassRefMarkers).

#Full example

A complete component set touching most features: multi-axis props, componentProperties, a SLOT and an INSTANCE, selector overrides, root transitions, and themeBinding.

{
  "$type": "composition",
  "name": "WPromoCard",
  "$description": "Promo card with media slot, action and variant states.",
  "props": {
    "theme": ["light", "dark"],
    "size": ["sm", "md"],
    "state": ["default", "hover", "disabled"]
  },
  "states": ["disabled"],
  "componentProperties": {
    "title": { "type": "TEXT", "layer": "title", "defaultValue": "Promo title" },
    "showMeta": { "type": "BOOLEAN", "layer": "meta", "defaultValue": true },
    "media": { "type": "SLOT", "layer": "media-slot", "defaultValue": "WImageTile" }
  },
  "structure": {
    "tag": "FRAME",
    "class": "card",
    "name": "Card",
    "children": [
      { "tag": "SLOT", "class": "media-slot", "slot": { "default": "WImageTile" } },
      { "tag": "TEXT", "class": "title", "content": "Promo title" },
      { "tag": "TEXT", "class": "meta", "content": "Meta" },
      { "tag": "INSTANCE", "class": "cta", "ref": { "component": "WButton", "properties": { "variant": "primary" } } }
    ]
  },
  "styles": {
    ".card": {
      "direction": "column",
      "gap": 12,
      "padding": 16,
      "background": "{card.bg}",
      "borderRadius": 16,
      "widthType": "fixed",
      "width": 320
    },
    "$size=sm .card": { "width": 260 },
    "$state=hover .card": { "boxShadow": [{ "x": 0, "y": 12, "blur": 32, "spread": 0, "color": "rgba(0,0,0,0.18)" }] },
    "$state=disabled .card": { "opacity": 0.56 },
    ".title": { "fontFamily": "Inter", "fontWeight": 600, "fontSize": 16 }
  },
  "transitions": { "hover-in": "on-hover smart-animate 160ms ease-out" },
  "themeBinding": {
    "target": "root",
    "prop": "theme",
    "modes": {
      "light": { "type": "local", "collection": "Themes", "mode": "Light" },
      "dark": { "type": "local", "collection": "Themes", "mode": "Dark" }
    },
    "applyTo": ["variables", "textStyles", "effectStyles"]
  }
}

Adaptation checklist: replace component names (WImageTile, WButton) with names from your library; create a Themes collection or drop themeBinding; start with Generate, then iterate with Apply; keep name stable on nested-targeted nodes.

#For agents & transformers

A) Figma → Composition JSON

1. Set $type: "composition" and a stable name.
2. Build props only from real variant axes; add states for mutually-exclusive conditions.
3. For each node write a valid tag and class; add stable name for nested-targeted nodes.
4. For instances write ref.component and only valid primitive ref.properties.
5. For slots use reference mode (slot) or children mode (children), never both.
6. Put all visual/layout rules into styles (base + selector overrides).
7. Use root-level transitions and themeBinding, not layer-level hacks.
8. Validate that referenced components/tokens exist.

B) Composition JSON → React / Vue

1. Read structure as the element tree; use class/path keys for style resolution.
2. Resolve variant selectors ($prop=value .class) against incoming props.
3. Respect branch visibility (display: "none").
4. Treat ref.component → component import, ref.properties → passed props.
5. Treat componentProperties, themeBinding, slotHostPipeline, and $figma as design-time metadata unless your runtime supports them.
6. Preserve token refs ({...}) or pre-resolve them through your token engine.

C) Pre-flight validation

• structure exists and every node has tag + class;
• styles exists and only contains object values;
• themeBinding.prop exists in props;
• no removed legacy keys (adapters, sizeStyles, colorStyles);
• no SLOT mode conflict (slot with non-empty children).

Author key → Figma runtime key (reference)

Author value → Figma enum (reference)

Notes: token references ({...}) are preserved and resolved at apply time; numeric and unit strings (px, rem, deg) are normalized to numbers where needed.

#Limitations & warnings

• Unsupported property/node combinations are ignored.
• Third-party/library instance internals can be partially protected by Figma.
• NESTED_INSTANCE and ref.nested rely on stable layer names.
• Large props matrices produce heavy variant counts — use states where appropriate.
• Figma Generate/Apply silently skips unknown style keys without blocking documented properties and aliases. Keep unknown keys only when another output, such as code generation, consumes them.
• Removed legacy keys error on parse: adapters, sizeStyles, colorStyles. component: false is incompatible with non-empty props.

#Related pages

• Tokens overview
• Token JSON format
• All token types
• Composition in Dev Mode (Get Code)