Deskhand

Server version, WebSocket port, connection state and connected document info.

Takes no parameters.

File info, current page and selection. Call once per conversation; every tool reports NOT_CONNECTED if the plugin is down.

Takes no parameters.

Recent selection changes, newest first, with timestamps. Default: the user's own selections; source: 'all' adds those made by bridge commands. Served from a server buffer, so it works after the plugin disconnects. If the default returns nothing, retry with source: 'all'.

Check the bridge end to end: versions, plugin handshake, buffered events, reverse round-trip timing. Call when a tool fails or after an upgrade.

Takes no parameters.

Deskhand licence state: trial days left, masked key, last check.

Takes no parameters.

Activate a Deskhand licence key.

Run JavaScript in the Figma plugin: an async function body with figma (Plugin API) and bridge (log, sleep, icon, text, instance, image, snapshot; progress/cancelled in jobs). Return plain data, never nodes (EXECUTE_BAD_RETURN). Errors: EXECUTE_SYNC_API, EXECUTE_SYNTAX, EXECUTE_FAILED. job: true past 30 s, then figma_job_status (waits). screenshot renders it. Recipes: figma_get_design_rules.

Waits for a figma_execute job to end (up to waitMs), then returns state (running | done | error | cancelled | timeout), progress and the result or error. Jobs live for the server session.

Ask a running figma_execute job to stop (sets the flag bridge.cancelled() returns; scripts that never check it run to completion). Poll figma_job_status.

List pages (ids and names). The active page is in figma_get_context.

Takes no parameters.

Full node details by id: geometry, fills, strokes, effects, auto-layout, text, constraints, boundVariables, explicitVariableModes, childIds. Default-valued props are omitted unless verbose. Composite instance ids (I<inst>;<child>) resolve; unknown ids land in notFound. Find ids with figma_search_nodes/figma_get_children first.

Set fill color. Accepts hex shorthand or fills array.

Set stroke color and/or weight. Per-side weights (strokeTopWeight etc., for border-top-only dividers) work on RECTANGLE and frame-like nodes only. Omit `strokes` to change weights only.

Create a rectangle.

Set text content. Auto-loads fonts.

Duplicate nodes.

Delete nodes.

Move nodes. Use relative=true for offset.

Resize nodes to explicit pixels. To fit a child to its parent prefer figma_set_layout_align STRETCH (keeps size binds). Instance sublayers are rejected (INSTANCE_SUBLAYER_RESTRICTED): resize the master. Size binds are re-applied; the result is read back: RESIZE_NO_OP for a no-op, a clamp is a warning.

Set or clear minWidth/maxWidth/minHeight/maxHeight: a number sets, null clears, omit leaves it. Applies to auto-layout frames and their direct children (others get a warning). Verified by readback (LIMIT_NOT_APPLIED / LIMIT_NOT_CLEARED). A variable-bound field keeps its bound value; unbind with figma_unbind_variable.

Set opacity (0-1).

Show or hide nodes via node.visible; don't bind a BOOLEAN variable or set opacity to 0 for this.

Set whether frame-like nodes (FRAME, COMPONENT, COMPONENT_SET, INSTANCE, SLOT, SLIDE) clip children to their bounds; others error.

Set corner radius. Use individual values for asymmetric.

Group nodes.

Ungroup nodes.

Create a frame.

Create a text node.

Set selection. Empty array clears.

Switch to a different page in the Figma document.

Export a node as PNG, SVG, JPG or PDF to disk and return { path, format, scale, bytes }; read the file to view it. outputPath sets the destination; returnBase64: true inlines raw data instead. To see the render in context use figma_screenshot.

Render a node (or the selection) as PNG and return it inline, with path, pixel size and scale. Scale is reduced to fit maxPixels (default 1,000,000); the inline image stays under 200 KB (one retry at half scale), larger renders stay on disk. Use after layout changes: readback cannot see overlap, clipping or mid-word breaks.

Pixel-diff a built frame against a reference node. Both render at the reference's effective scale; returns mismatchPercent, a per-quadrant breakdown (tl/tr/bl/br), the size delta and paths to the diff/ref/built PNGs. A mismatch in one quadrant usually means one misplaced element.

Export many nodes in one call, each at a scale or targetWidth (scale = targetWidth / node width, clamped 0.01–4). Files go to outputDir (default: a fresh folder under ~/.deskhand/exports/) named by namePattern with tokens {name} {id} {scale} {ext} {index}. One row per item (path and size, or an error); nothing is inlined.

Check icon concepts against the bundled Lucide set before drawing anything; never hand-draw glyphs. Aliases resolve (close → x), then exact names; otherwise you get real-name suggestions: pick one, do not invent. Insert with figma_place_icon or bridge.icon.

Insert a Lucide icon as a vector frame named icon/<concept>. Resolves like figma_resolve_icon. Appended to parentId (or the current page) at x/y, scaled and stroked.

Insert an iOS chrome template (status-bar 393×54, home-indicator 393×34, keyboard 393×291), named chrome/<kind>. With parentId it scales to the parent width, top or bottom unless y is given.

Per-screen quality gate: lint one frame → { pass, findings, counts, fixes }; a finding carries its own fix only when it differs from fixes[code]. Errors: invisible text, overflow, zero-size, collapsed auto-layout, low contrast. Warnings: misaligned rows, hand-drawn icons, placeholder avatars, raw fills/text, detached instances. Capped at 200, errors first.

Read the brand the open file already defines: local paint/text/effect styles, every component and set (keys, variant properties, all pages) and common frame sizes; samples fills and fonts when there are no styles. Use its colours, type and components in everything you build. Cached under ~/.deskhand/brands/ so bridge.instance(name) can import components later.

Takes no parameters.

Fill a node with an image from an absolute path (~/ allowed) or http(s) URL: PNG, JPEG, GIF or WebP, up to 4096 px per side and 20 MB. Replaces the fills with one IMAGE fill. Use for photos, avatars and reference art instead of placeholder shapes; bridge.image does the same in scripts.

Save a restorable copy of a node before a risky edit: cloned onto a "🗄 Bridge Snapshots" page with parent/index/position recorded. Keeps the newest 10 per file. Restore with figma_restore_snapshot or bridge.snapshot() in scripts.

Undo to a snapshot: removes the current node (if present) and moves the saved clone back to its recorded parent/index/position/name. New id: restoredId — update ids you held. Snapshot is consumed. SNAPSHOT_NOT_FOUND if unknown or the clone was deleted.

List saved snapshots in this file, newest first, with whether each clone still exists. Returns { count, page, snapshots }.

Takes no parameters.

One cookbook section as markdown: rules plus a runnable figma_execute recipe. Sections: helpers, auto-layout, components, variants, text, lint, jobs, reference-match. Read it before building that kind of thing. Whole cookbook: skill://deskhand/COOKBOOK.md. Needs no plugin.

Create ellipse. Use arcData for arcs/rings.

Set effects. Replaces existing.

Configure auto-layout on a frame: direction, sizing modes, alignment, padding, spacing, wrap. Size variable binds are captured and re-applied (rebound/warnings). See skill://deskhand/SKILL.md.

List all local styles (colors, text, effects, grids). To find specific styles by name use figma_search_styles: fewer tokens.

Apply a local style (paint, text, stroke, effect, grid) to a node using Figma's async setters. The applied id is read back: appliedStyleId with verified: true, or STYLE_NOT_APPLIED.

Create a component.

Create a component instance.

All local variables and collections: types (COLOR, FLOAT, STRING, BOOLEAN), modes, values. Paged: limit (default 100) and offset; next gives the following page.

Search variables by name pattern (e.g. "tailwind/orange/*"). Compact results, far fewer tokens than figma_get_local_variables.

Search nodes by name within a scope (parentId required). Preferred for finding frames, sections or elements; compact results (~50 tokens/node).

Search local components by name. Returns compact metadata.

Search local styles by name; cheaper than figma_get_local_styles.

Immediate children of a node — more efficient than figma_get_nodes for browsing hierarchy. Default limit 100, with truncated/next for paging. Compact results include x/y for layout. Composite instance-sublayer parent IDs resolve too.

Set a variable's value for a mode, or bind it to a node property or local style (styleId + field). Text styles bind font/spacing fields; paint styles bind 'paints'. Verified by readback (BIND_NOT_APPLIED otherwise). width/height on an instance sublayer: INSTANCE_SUBLAYER_RESTRICTED, bind the master.

Create a line.

Set resize constraints on a node: how it resizes when its parent frame resizes. Only for nodes inside frames (not auto-layout frames).

Detach an instance into a regular frame: keeps overrides, severs the link to the main component.

Set how a child behaves in an auto-layout frame: alignment (STRETCH), growth (fill container) and absolute positioning.

Rename one or more nodes (a batch shares one name).

Change a node's z-order among its siblings. position is the FINAL index (0 = back/bottom, childCount-1 = front/top); 'back' and 'front' also work. Out-of-range values are clamped. Verified by readback (REORDER_FAILED otherwise). Children of instances cannot be reordered (INSTANCE_SUBLAYER_RESTRICTED): reorder on the master.

Set text font properties.

Create a paint style.

Create a text style.

Delete a local style (paint, text, effect or grid). Library styles return REMOTE_STYLE. Nodes keep their resolved values but lose the link.

Create a variable collection.

Create a variable in a collection.

Rename a variable; "/" makes groups.

Delete variables. Cannot be undone.

Delete a variable collection and all its variables. Cannot be undone.

Rename a variable collection.

Rename a mode in a variable collection.

Add a new mode to a variable collection.

Delete a mode from a variable collection. Cannot delete the last mode.

Pin an explicit variable mode on nodes or pages (e.g. a mobile frame pinned to the Spacing collection's mobile mode), or clear: true to unpin. Works on scene nodes and page ids. Echoes explicitVariableModes ({} = nothing pinned).

Remove a variable binding from a node property, verified by readback (UNBIND_FAILED otherwise). For minWidth/maxWidth/minHeight/maxHeight the leftover literal clamp is cleared too (previousLiteral, clearedLiteral).

Create a page. Figma Design only: FigJam returns FIGMA_DESIGN_ONLY (create FigJam pages in its UI).

Rename a page.

Delete a page. The last page cannot be deleted.

Move nodes to a different parent.

Move nodes from their current page to a different page.

Swap an instance to a different component, keeping position and size.

Clone a page and its contents, inserted after the original. Figma Design only (FIGMA_DESIGN_ONLY in FigJam).

Rotate nodes by degrees. pivot 'center' (default) keeps the visual centre in place; 'top-left' is Figma's raw rotation, which moves the centre. Children of auto-layout parents (unless ABSOLUTE) cannot use a centre pivot: they get top-left plus a warning. Echoes appliedPivot, rotation and absoluteBoundingBox.

Combine components into a variant set; names must use variant naming (e.g. "Size=Large").

FigJam only: create a sticky note (fixed 240×240). Author name/visibility are set by Figma and cannot be changed.

FigJam only: toggle a sticky between square and wide. Use figma_set_text for body text.

FigJam only: flowchart shape with embedded text (30 shape types; cornerRadius is fixed).

FigJam only: change the shape type of a shape-with-text node.

FigJam only: connector (arrow) between two nodes. Endpoints attach via magnets (AUTO recommended), fixed positions, or float free. Default end cap ARROW_EQUILATERAL. STRAIGHT only supports CENTER/NONE magnets.

FigJam only: modify an existing connector's endpoints, line type, end caps, or label.

Create a labeled section (works in both Figma Design and FigJam) to group content. Supports dev status (READY_FOR_DEV/COMPLETED).

Update a section's name, dev status, or content visibility. Pass devStatus: null to clear.

FigJam only: create a table (default 2×2), optionally seeded via cells.

FigJam only: set the text and/or fill color of a single table cell.

FigJam only: insert a row at the given index (existing rows at and after the index shift down).

FigJam only: insert a column at the given index (existing columns at and after the index shift right).

FigJam only: remove the row at the given index.

FigJam only: remove the column at the given index.

FigJam only: set the height of a table row.

FigJam only: set the width of a table column.

FigJam only: move a row from one index to another.

FigJam only: move a column from one index to another.

FigJam only: create a syntax-highlighted code block.

FigJam only: update an existing code block's code text or language.

FigJam only: link preview from a URL: EMBED for OEmbed providers (YouTube, Spotify), else LINK_UNFURL (OpenGraph/Twitter card). Response includes nodeType.

Prototype (Figma Design only): get a node's reactions (trigger and action details).

Prototype (Figma Design only): add an interaction to a node; existing reactions are kept.

Prototype (Figma Design only): remove a reaction by its zero-based index; find it with figma_get_reactions first.

Prototype (Figma Design only): set a top-level frame as a flow starting point on the page, or clear it. Stored page-level as { nodeId, name } entries.