io.github.duncanbottrill/deskhand

Add a new mode to a variable collection.

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

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.

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.

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

Duplicate nodes.

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

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.

Create a component.

Create ellipse. Use arcData for arcs/rings.

Create a frame.

Create a component instance.

Create a line.

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

Create a paint style.

Create a rectangle.

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

Create a text node.

Create a text style.

Create a variable in a collection.

Create a variable collection.

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

Delete nodes.

Delete a page. The last page cannot be deleted.

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

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

Delete variables. Cannot be undone.

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

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

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.

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.

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.

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.

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

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.

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

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

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.

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

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'.

Group nodes.

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.

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.

Activate a Deskhand licence key.

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

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

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

Move nodes. Use relative=true for offset.

Move nodes from their current page to a different page.

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.