Danila Poyarkov 7ad6475e2b

feat: create, fill, and edit slots (#862 )

* feat(app): add slot property controls and a shared picker

AppPicker is a searchable, grouped list that opens beside the properties
panel, built on Reka's popover and listbox so search keeps arrow-key
navigation. It has comfortable rows with a thumbnail and description and
compact rows for plain names, plus an optional footer action.

The slot property row shows whether an instance's slot is Default or
Modified, its item count, its limits with a checklist popover, Add
instances on AppPicker, and Reset slot and Delete contents. These are
presentational; wiring them to the editor follows. Strings are English
only until the locale files catch up.

* feat(app): open variable, style, and instance-swap choices in the shared picker

The variable binding picker, the shared style fields, and instance-swap
properties now open AppPicker: a titled panel beside the properties panel
with search that keeps arrow-key navigation, a check on the current
choice, and footer actions. Variable binding keeps its detach and
create-variable actions. Instance-swap choices list the property's
preferred components first; instanceSwapOptions keeps the preferred flag
it already computed. AppPickerField gives select-shaped fields the same
picker with a combobox trigger.

* feat(core): edit instance slot content

Only an instance's slots take layers now. slotScope classifies a parent as
free, a slot of an instance, or the locked rest of an instance. Moves,
reorders, layer-panel drops, paste, duplicate, and instance creation
claim an untouched slot first, as Figma does on the first edit, and
refuse the locked part; drops over it land in the instance's parent.
Claiming keeps the layers but unlinks them from the component and moves
the instance's overrides on nested instances onto those instances.

Reset slot, Delete contents, and Add instance are editor actions, each
one undo step that restores the instance's subtree. A canvas drop or
reorder that claims a slot undoes together with the move.

* feat(app): show and edit slot properties of the selected instance

The component properties section lists each slot of the selected instance
with its state, item count and limits, and adds instances, resets or clears
its content through the editor's slot actions. The slot model lives in the
Vue SDK as useSlotProperties.

* feat(app): outline slots on the canvas and mark them in the layers panel

Hovering or selecting a component, an instance, or a layer inside a slot
draws its slots with a dashed pink outline and tints empty ones. Slot
frames are selected and hovered in pink and show a dashed-square icon in
the layers panel.

* test(app): cover slot outlines with canvas snapshots

* feat(app): translate slot and picker strings

* docs: note slot editing and the shared picker

* refactor: share slot test and story setup

* refactor(app): name the picker's header prop heading

* feat(core): create, configure, and remove slots on main components

A frame of a main component becomes a slot through a SLOT property
named after it; other sibling layers are first wrapped in an auto
layout frame. Slot settings and removal are single undo steps.
Instances now follow the component's property bindings on sync, so a
slot created or removed on the component reaches existing instances.
Slot helpers move to a slots domain folder in Scene Graph and Core.

* feat(app): create and configure slots from the menu and properties panel

Create slot joins the canvas context menu for layers of a main
component. A Slots section on main components and their frames
renames slots, sets their description, layer limits, and preferred
components, and removes them.

* fix: keep slot claims in the same undo step and refuse wraps inside instances

Creating an instance and pasting HTML now batch the slot claim with the
edit. Undoing an added slot instance restores the previous selection.
Grouping or wrapping layers in the locked part of an instance is
refused, and a section that cannot move no longer claims a slot. The
picker clears its search however it closes, and its close and slot
actions labels are translated.

* feat(core): create and inspect slots through the plugin API

component.createSlot() adds a 100x100 frame named Slot, Slot 2, and so
on, bound to a new SLOT property, as live Figma does. Slot frames read
type SLOT, resetSlot() restores an instance slot's component content,
and limitViolations reports BELOW_MIN, ABOVE_MAX, and
HAS_NON_PREFERRED for instance slots. addComponentProperty and
editComponentProperty take a description and slotSettings, a cloned
slot is a plain frame, and componentPropertyReferences uses property
keys in both directions. The limit checks move to Scene Graph so the
Vue SDK and the plugin API share them.

* fix: keep nested slot content across swaps and read nested instance properties

A nested instance points at the instance it was cloned from, so its
component properties resolved to nothing. Properties now resolve through
those links to the main component, and a swap or variant switch parks
the slot content nested instances own and restores it into nested
instances of the same names, as live Figma does. Plugin appendChild and
insertChild claim the slot they add to and refuse the locked part of an
instance with Figma's error.

* test(core): record resetSlot on a main component slot; fix the Slots roadmap row

* fix(core): refuse deleting layers outside an instance's slots

As in Figma, delete and plugin remove() leave an instance's own layers
and its slot frames alone, while removing slot content claims the slot
in the same undo step as the delete.

* test(app): wait for the bulk rename dialog to close before the next shortcut

* feat(app): unify add, remove, and settings controls in the properties panel

A section's + adds an item and a row's - removes it everywhere: grid
tracks and variant properties now follow the fill and effect lists, and
the header + of a component set adds Property 1 ready to rename instead
of an inline form. Removing a variant is Delete, as for any layer.
Row settings share the sliders icon, the variables button opens with
its own icon, every icon button requires a label, and the instance
header buttons use sentence case. Create Slot joins the app menu.

* docs: note the unified properties panel controls

* feat(app): animate floating panels alike and share the severity icon

Popovers, menus, selects, comboboxes, and pickers now fade and grow in
from the side they open on and fade out on close, from one motion
preset that respects reduced motion; tooltips keep the tooltip preset.
SeverityIcon and its colours move from the design check to shared
feedback UI, and slot limits use them, so a broken limit reads like a
design-check warning.

* docs: note consistent popover and menu animation

* feat(app): give every floating panel one surface and close it at once

Popovers, menus, selects, comboboxes, pickers, presence cards, chat
history, and the issue tooltip share one rounded surface with a 1px
ring that outlines it in both themes; one-line tooltips keep a compact
shape with the same edge. The select theme's radius and elevation
options and local shadow overrides are gone. Panels still grow in from
their side but now close immediately: a fading modal menu kept blocking
the canvas and shortcuts until it unmounted.

* fix(app): keep a reopened context menu open and name option-drag undo Duplicate

Closing the canvas menu hands focus back to the canvas; when that
landed just after a quick reopen, the new menu closed as focus moved
outside it. Shortcuts no longer wait for a panel that is already
closing, and an option-drag duplicate that claims a slot is undone as
Duplicate rather than Move.

* test(app): wait for menus and popovers to close before the next key

2026-10-04 17:02:28 +00:00

5.5 KiB

Raw Blame History

title	description
Scripting	Execute JavaScript with a Figma-compatible Plugin API to query, batch-modify, and generate designs.

Scripting

openpencil eval runs JavaScript against an OpenPencil document with a Figma-compatible figma global. Use it for headless batch edits, inspection, fixture setup, and automation without opening the editor UI.

Basic usage

openpencil eval design.fig -c "return figma.currentPage.children.length"

The -c flag accepts JavaScript. If the code does not start with return, OpenPencil wraps it in an async function and returns the value from that function when present.

openpencil eval design.fig -c "
  const frame = figma.createFrame()
  frame.name = 'Card'
  frame.resize(300, 200)
  frame.layoutMode = 'VERTICAL'
  frame.itemSpacing = 12
  return { id: frame.id, name: frame.name }
"

Query nodes

openpencil eval design.fig -c "
  return figma.currentPage
    .findAll((node) => node.type === 'FRAME' && node.name.includes('Button'))
    .map((button) => ({
      id: button.id,
      name: button.name,
      width: button.width,
      height: button.height
    }))
"

Modify and save

Use --write / -w to write changes back to the input file:

openpencil eval design.fig -c "
  figma.currentPage.children.forEach((node) => {
    node.opacity = 0.5
  })
" --write

Use --output / -o to write to a new file:

openpencil eval design.fig -c "figma.currentPage.name = 'Updated'" -o updated.fig

Read scripts from stdin

cat transform.js | openpencil eval design.fig --stdin --write

Live app mode

Omit the file path to run against the currently open document in the desktop app:

openpencil eval -c "return figma.currentPage.name"

The desktop app must be running with a document open.

Output

By default, non-TTY output is JSON. Use --json to force JSON output:

openpencil eval design.fig -c "return figma.currentPage.children.map((n) => n.name)" --json

Use --quiet / -q to suppress output when only writing a file.

Supported API surface

The API is intentionally close to Figma's Plugin API, but it maps to OpenPencil's scene graph and file format.

Document and pages

figma.root
figma.currentPage
figma.currentPage.selection
figma.getNodeById(id)
figma.createPage()

Node creation

figma.createFrame()
figma.createRectangle()
figma.createEllipse()
figma.createText()
figma.createLine()
figma.createPolygon()
figma.createStar()
figma.createVector()
figma.createComponent()
figma.createSection()

Tree operations

node.children
node.parent
node.appendChild(child)
node.insertChild(index, child)
node.clone()
node.remove()
node.findAll(callback?)
node.findOne(callback)
node.findChild(callback)
node.findChildren(callback?)
figma.group(nodes, parent)
figma.ungroup(node)

Components

figma.createComponentFromNode(node)
component.createInstance()
instance.mainComponent

Variables

figma.getLocalVariables(type?)
figma.getVariableById(id)
figma.getLocalVariableCollections()
figma.getVariableCollectionById(id)
figma.createVariable(name, type, collectionId, value?)
figma.setVariableValue(variableId, modeId, value)
figma.deleteVariable(id)
figma.createVariableCollection(name)
figma.deleteVariableCollection(id)
figma.bindVariable(nodeId, field, variableId)
figma.unbindVariable(nodeId, field)

Properties

Common node properties are readable/writable through the proxy, including:

Geometry: x, y, width, height, rotation, resize(width, height)
Appearance: fills, strokes, effects, opacity, visible, locked, blendMode, clipsContent
Radius: cornerRadius, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius
Text: characters, fontSize, fontName, fontWeight, alignment, line height, letter spacing, style-run helpers
Auto-layout: layoutMode, primaryAxisAlignItems, counterAxisAlignItems, itemSpacing, padding, sizing, and layout positioning fields
Stroke helpers: strokeWeight, strokeAlign, dashPattern

Utilities

figma.mixed
figma.createImage(data)
figma.loadFontAsync(fontName) no-ops because OpenPencil does not gate text edits on plugin font loading
figma.listAvailableFontsAsync() returns host-provided fonts when available
figma.getNodeByIdAsync(id) and instance.getMainComponentAsync() resolve to the same nodes as figma.getNodeById(id) and instance.mainComponent, for scripts written for Figma's dynamic-page mode
figma.notify(message) logs a warning in headless mode
instance.swapComponent(component) points an instance at another component
component.createSlot() adds a slot frame and its SLOT property; slot frames read type: 'SLOT', resetSlot() brings back an instance slot's component content, and limitViolations lists the limits an instance slot breaks. addComponentProperty and editComponentProperty take a description and, for slots, slotSettings
figma.viewport

Not yet Figma-compatible

These Figma APIs are not exposed as compatible helpers yet:

node.exportAsync()
node.setBoundVariable(field, variable)
figma.combineAsVariants(components, parent)
Figma style APIs such as figma.createPaintStyle() / figma.createTextStyle()
Full vector boolean operation parity

Use OpenPencil CLI export commands, core tools, or direct scene-graph helpers where available.

5.5 KiB Raw Blame History