Repository navigation
Releases
v2.5.30
Fixed
Dashed borders were read back as solid (src/plugin/handlers-node-detail.js, handlers-css.js, handlers-design-context.js, extract-design-tree.js)
get_node_detailreturned every stroke property except the one that says a border is dashed, andget_csshardcodedsolidfor all of them — stating as fact something the reader never looked at. An agent reading faithfully rendered a dashed affordance as a solid one, with colour, weight, radius and size all agreeing with the wrong answer.- The write side has forwarded
dashPatternsince BUG-17, so a border drawn through this bridge could not be read back as it was drawn. get_node_detailandget_design_contextnow reportdashPatternwhen non-empty;get_cssemitsdashedplus a comment carrying the numbers, since CSS has no single property for Figma's dash/gap array. An empty array means solid and is omitted rather than reported as[].- Thanks to @wamynobe (PR #17) for finding this and fixing the first three read paths.
extract-design-tree.js— behindget_designandscan_design— had the same omission and is fixed here too, so all four read paths now agree. scripts/test-dash-pattern.mjscovers the round trip: dashed reported, solid omitted rather than sent as[], a missing property not throwing, the CSS output for both cases, and the array being copied rather than aliased to Figma's live object.
v2.5.29
Fixed
Plugin UI counted advisory messages as errors (plugin/ui.html)
handlers-create.jsposts a{ type: "log" }warning when a child is created with explicit x/y inside an auto-layout parent.window.onmessageonly special-casedsession-info, so that warning fell through to the operation-result path:msg.successwasundefined, the error counter incremented, and the Activity log printed✗ ? undefined— no op id, no message. Onecreatetherefore produced a visible error alongside its own success line.- It then called
sendResponse(undefined, ...), and the bridge loggedsettle ORPHAN response id=undefinedfor each one. type: "log"is now handled, and any message without an op id is ignored rather than treated as a failed operation.
Release workflow failed at the MCP Registry step (.github/workflows/release.yml)
- The registry verifies the npm version exists before registering it, and npm's read path needs a moment to serve a just-published version. v2.5.28 published to npm successfully and then failed the registry step with a 404 for a version npm already had. The step now waits for npm to serve the version and retries the registry publish.
modifyVariable could not rename a variable or edit its description (src/plugin/handlers-styles.js)
- It threw
value is requiredunless a per-mode value was supplied, butnameanddescriptionare variable-level, not per-mode. Renaming a token therefore needed a dummy value. It now acceptsvalue,nameordescriptionin any combination, and still rejects a call that changes nothing.
layoutAlign: "STRETCH" silently ignored on empty auto-layout children (src/plugin/layout-helpers.js)
- A child that is itself an auto-layout frame starts at
counterAxisSizingMode: "AUTO"(hug) before it has children, and hug wins overSTRETCH. The child collapsed to the 100px default instead of filling the parent — so a screen built from nested auto-layout sections came out with a 196px header and 25px cards inside a 390px frame. A plain frame does not hit this, which is why it only showed up when composing real screens. applyChildLayoutnow promotes the cross-axis sizing toFILLwhenlayoutAlign: "STRETCH"is set on an auto-layout child, unless the caller gave an explicit sizing or width/height for that axis.- Verified on a live Figma file: the same section goes from 100px to 350px.
v2.5.28
Added
scripts/test-read-parity.mjs— runs the pre-refactorextractDesignTreeand the current one over the same mock nodes and fails if a field present in the baseline is gone. Confirms the v2.5.27 refactor dropped nothing: FRAME, RECTANGLE with a gradient and INSTANCE outputs are field-for-field identical, and the mixed-text node gainsfontFamily,fontWeightandmixedStyleswhere the old code sent{}.
Notes
No behaviour change over 2.5.27; this release carries the parity test and the version bump.
v2.5.26
Fixed — 10 bugs from field report (Clean Master Plus project)
BUG-NUM-01 (HIGH): FLOAT scalar variables only applied to default mode (src/plugin/handlers-tokens.js)
numbers: { "radius-md": 12 }on a multi-mode collection (["light", "dark"]) set 12 only in light; dark mode kept its initial value (0).- Same root cause affected
fontSizes. Result: dark-mode UI had zero corner radius, zero spacing. - Fix: scalar values in
applyVariableValuenow write to every mode in the collection, not just the default. Per-mode object syntax ({ light: 4, dark: 8 }) still routes per-mode unchanged.
BUG-FONT-02 (CRITICAL): STRING font variables resolved as "String value" placeholder (src/plugin/handlers-tokens.js)
- Same root cause as BUG-NUM-01 but with disastrous consequences: text styles bound to a STRING font variable rendered as font literally named
"String value"→ invisible text + broken layout. - Fix: same
applyVariableValuechange — scalar STRING values propagate to all modes.
BUG-MODE-01 (HIGH): setFrameVariableMode crashed with unloaded font "String value Medium"
- Direct consequence of BUG-FONT-02 — auto-resolved by the fix.
BUG-TS-01 (HIGH): re-running setupDesignTokens didn't clear stale STRING font bindings (src/plugin/handlers-tokens.js)
- Calling
setupDesignTokensa second time with literalfontFamily: "Inter"(nofonts:key) left the existing text style still bound to the previous STRING variable. - Fix: when caller passes a literal font name, plugin now explicitly unbinds
fontFamily/fontStylebefore assigning the new literal.
BUG-FONT-01 (HIGH): system fonts produced cryptic error (src/plugin/handlers-tokens.js)
setupDesignTokenswithfontFamily: "SF Mono"(orSF Pro,system-ui) failed with genericfont could not be loaded— Figma cloud doesn't carry macOS system fonts.- Fix: error now suggests the correct cloud-available replacement:
SF Mono→ JetBrains Mono, Roboto Mono, Fira CodeSF Pro→ Inter, Manrope, DM Sanssystem-ui/-apple-system→ Inter
BUG-TEXT-01 (HIGH): TEXT nodes stuck at 100×100 when only width or no dimensions passed (src/plugin/handlers-write.js)
- Default values
width: 100, height: 100inhandlers.createdestructuring made every TEXT node default to a 100×100 fixed box. Vertical overflow + parent frame bloat. - Fix: distinguish missing vs. zero. When neither width/height passed →
textAutoResize: "WIDTH_AND_HEIGHT"(natural shrink-wrap). When only width →"HEIGHT"+ resize to actual node height. Post-appendChildre-apply useshasExplicitWidth/hasExplicitHeightinstead of falsy check on default 100.
BUG-DEL-01 (CRITICAL): deleting frames containing components silently lost variables (src/plugin/handlers-write.js)
figma.delete({ id: <frame containing COMPONENT masters> })ran without warning; user reports variable collections + text styles also vanished afterwards (Figma edge case under dynamic-page document access).- Fix:
deletenow blocks frames containingCOMPONENT/COMPONENT_SETdescendants by default. Response includesblocked: "contains-components",componentCount,componentNames. Caller passesforce: trueto override after confirming.
BUG-CONN-01 (MEDIUM): plugin disconnect after idle, no auto-reconnect (plugin/ui.html)
- v2.5.25 added visibility listener but only force-reconnected when
consecutiveErrors > 0or poll in-flight. Idle case (poll succeeded recently but server expired session before user returned) slipped through. - Fix: track
lastSuccessfulPollAt; if user returns to tab > 20s after last successful poll, force-reconnect regardless of error state.
Documentation-only:
- BUG-TS-02 (MEDIUM):
fontWeight: "Medium"ontext/labelfalling back to"Regular"— this was already handled by the legacy fallback loop on line 691-695. The actual root cause was font load failure mid-chain; with BUG-FONT-01 improvements the error is now explicit instead of silent fallback. - BUG-TIMEOUT-01 (MEDIUM): retrying
setupDesignTokenson an existing collection with full payload (15 colors × 2 modes + 16 numbers + 7 textStyles) takes ~60s. Not a bug — Figma's variable + style API doesn't batch. Recommendation: only callsetupDesignTokensonce per session; usemodifyVariablefor individual updates.
Tests
scripts/test-v2526-feedback.mjs— 23 tests covering every fixable bug above:- BUG-NUM-01 scalar all-modes + per-mode object preserved (×5)
- BUG-FONT-02 STRING var all-modes (×3)
- BUG-TS-01 unbind on literal (×1)
- BUG-FONT-01 SF Mono / SF Pro hints (×4)
- BUG-TEXT-01 hug / width-only / both (×7)
- BUG-DEL-01 component-block + force override (×3)
- Full suite: 398 tests, 0 failures
v2.5.25
Fixed — Connection stability + INSTANCE_SWAP defaultValue
Connection stability (bridge-server.js + plugin/ui.html)
Field report: "Cứ lâu lâu nó bị disconnect xong phải đợi connect lại, có khi không connect, chạy npx lại cũng không connect được luôn." Four root causes fixed:
HEALTH_TTL_MSraised 60s → 120s: previously sessions were marked disconnected when browsers throttled background tabs to ~1Hz polling. The plugin's long-poll cycle (8–12s) plus throttling could push the gap past 60s when the tab wasn't focused. 120s covers all reasonable throttle modes.SESSION_EXPIRE_MSraised 5min → 30min: ops queued while user stepped away (lunch, meeting) no longer vanish when they return. Sessions still expire eventually so memory doesn't grow unbounded.reconnect()now aborts the in-flight long poll viaAbortControllerinstead of just flipping a flag and waiting up to 12s for the existingawait fetch()to settle. Previously could create overlapping poll loops.#killStaleBridges()now kills ALL PIDs holding the port, not just the first one returned bylsof. Multiple zombie processes (from repeatednpx figma-ui-mcpruns) are reclaimed together. Excludes our own PID.- Plugin now listens for
visibilitychange— when the Figma tab becomes visible after a long pause and a poll is in flight or recently errored, it force-reconnects immediately instead of waiting for the next throttled poll cycle.
INSTANCE_SWAP defaultValue clarification (handlers-tokens.js)
Field report: "Plugin wants the nodeId (not the published key) as INSTANCE_SWAP default. Docs are misleading." Confirmed — the Figma plugin API expects a local node ID (e.g. "123:456"), not a published component key. Previous code accepted either as a string and silently broke instance swap when a key was passed.
- Comments + error messages now clearly say "node ID, not published key"
- When a key-like string (no
":") is passed, the plugin now auto-resolves viafigma.importComponentByKeyAsync()before falling back to a clear error message pointing atcreateComponent(...).id/listComponents() api-docs.jsexample updated — usesiconMaster.idfromcreateComponent()instead of a fake published key string
Tests
test-component-properties.mjs— 7 new tests covering node ID accepted-as-is, published key auto-resolution, unknown key error path- Full suite: 375 tests, 0 failures
v2.5.24
Added — Complete component property workflow (merged PRs #8, #9, #10, #11 by @muhammadmahad-debug)
This release closes a major gap: instance text overrides now actually re-measure auto-layout. Buttons grow to fit longer labels, cards reflow when content changes — exactly the workflow needed for proper component libraries.
The chain that makes it work:
- Master-side property definitions (PR #8 —
addComponentProperty,bindComponentPropertyToText,removeComponentProperty) — create TEXT / BOOLEAN / INSTANCE_SWAP properties on aCOMPONENTorCOMPONENT_SET, bind a child TEXT's.charactersso override values flow through the property pipeline. - Generic property binding (v2.5.22 follow-up —
bindComponentProperty,unbindComponentProperty) — single API covering all three reference fields (.characters,.visible,.mainComponent) with type validation and preservation of co-existing refs. - Cross-page component lookup under dynamic-page access (PR #9 —
loadAllPagesAsync) —instantiatenow callsawait figma.loadAllPagesAsync()beforefindOne, mirroring whatlistComponentsalready did. Also exposesfigma.loadAllPagesAsync()to user code so arbitrary cross-page queries work. - Missing variant/property handlers shipped (PR #10 —
setComponentProperties,getComponentProperties,swapComponent) — these had been on the executor allowlist since v2.4.0 but no plugin-side handler ever existed (silently failed for 2 years). Now driving instance property overrides actually works end-to-end. - Modern per-child layout sizing + auto-promote (PR #11 —
layoutSizingHorizontal/layoutSizingVerticalparams on create/modify, auto-promote TEXT to HUG on content change) — Figma's modernlayoutSizingHorizontal: "FIXED" | "HUG" | "FILL"beats legacytextAutoResizefor children of auto-layout. Whenmodify({content: "..."})targets a TEXT inside a hug-axis parent, the text axis is auto-promoted to HUG so the parent reflows. Explicit user params override the magic.
Fix in this release: unbindComponentProperty setting componentPropertyReferences = null was rejected by Figma's validator (Expected object, received null) — caught during live smoke test of v2.5.22. Now assigns empty object {} which Figma accepts.
Live smoke test verified
End-to-end on a real Figma multi-page file:
- Button master → addComponentProperty TEXT → bindComponentPropertyToText → instantiate → setComponentProperties with longer label → button width grew 140px → 244px (+104px reflow).
- Card master with BOOLEAN
showIcon→ bindComponentProperty.visible→ unbind + rebind → setComponentPropertiesfalse→ icon hidden in instance.
Tests
test-component-properties.mjs— 47 tests (PR #8)test-bind-component-property.mjs— 22 tests (v2.5.22 follow-up + v2.5.23 empty-object fix)test-dynamic-page.mjs— 15 tests (PR #9)test-variant-handlers.mjs— 46 tests (PR #10)test-layout-sizing-axes.mjs— 15 tests (PR #11)- Full suite: 368 tests, 0 failures
Credits
Massive thanks to @muhammadmahad-debug — 4 high-quality PRs, all backed by mock tests + plugin-side vm tests + rebuild + docs updates.
v2.5.23
Fixed — unbindComponentProperty rejected by Figma when clearing last field
Setting node.componentPropertyReferences = null threw at runtime:
Property "node.componentPropertyReferences.value" failed validation: Expected object, received null
Caught during live Figma smoke test of v2.5.22 — mock tests didn't exercise the Figma validator.
Fix: assign empty object {} instead of null when unbinding the last field. Effectively clears all references and Figma accepts it.
Tests
scripts/test-bind-component-property.mjsupdated to assert empty-object behavior- Full suite: 292 tests, 0 failures
v2.5.22
Added — Component property definitions on master components (merged from PR #8 by muhammadmahad-debug)
New handlers — master-side property API:
addComponentProperty— create TEXT / BOOLEAN / INSTANCE_SWAP property on aCOMPONENTorCOMPONENT_SET. ValidatesdefaultValueper type, rejectsVARIANTwith a clear message (variants live on component sets viacombineAsVariants()).bindComponentPropertyToText— bind a child TEXT node's.charactersto a TEXT property. This is the step that makes auto-layout actually re-measure on instance override — Figma only reflows when text arrives via a bound property, not from a rawcharacterswrite.removeComponentProperty— delete a property definition. Bare-name →name#idresolution works here too.
New handlers — generic binding (this release):
bindComponentProperty— generic version supporting all three reference fields:.characters(TEXT property, TEXT node),.visible(BOOLEAN property, any node),.mainComponent(INSTANCE_SWAP property, INSTANCE node). Preserves existing references on the same node, validates field/type match, walks up to find owning component automatically.unbindComponentProperty— remove a single field binding; other refs on the node preserved. Sets refs tonullwhen last field cleared (Figma quirk: empty object doesn't clear).
Resolves the long-standing limitation where instance text overrides changed content but never reflowed auto-layout. Now buttons grow to fit longer labels when setComponentProperties is used on the instance — exactly the workflow needed for proper component libraries.
Tests
scripts/test-component-properties.mjs— 47 tests (TEXT/BOOLEAN/INSTANCE_SWAP creation, bare-name resolution, binding edge cases, validation)scripts/test-bind-component-property.mjs— 22 tests (proxy forwarding ×4, BOOLEAN binding ×3, INSTANCE_SWAP binding ×2, TEXT binding ×2, preservation ×2, validation ×4, unbind ×3, no-op ×1, last-field-clear ×1)- Full suite: 292 tests, 0 failures (39+13+29+27+23+11+41+24+16+47+22)
v2.5.21
Fixed — BUG-01/02/03/04 from field reports
BUG-01: setupDesignTokens with textStyles throws under documentAccess: dynamic-page (src/plugin/handlers-tokens.js)
- Removed sync
figma.getLocalTextStyles()fallback — Figma rejects sync call underdocumentAccess: dynamic-page - Both
setupDesignTokensandapplyTextStylenow usegetLocalTextStylesAsyncexclusively - Fixes:
Cannot call with documentAccess: dynamic-page. Use figma.getLocalTextStylesAsync instead.
BUG-02: VECTOR fill rejects gradient objects (src/plugin/handlers-write.js)
buildVectornow usesbuildFillArray(same as FRAME/RECTANGLE) instead ofsolidFill- Gradient fills (
{ type: "LINEAR_GRADIENT", stops: [...] }) now work on VECTOR nodes - Hex fills, alpha hex (
#RRGGBBAA), and CSS color strings still work — no regression
BUG-03: query() 100-node hard cap + no parentId filter (src/plugin/handlers-write.js)
- Default cap raised 100 → 500 (configurable via
limitparam) - New
parentIdparam scopes search to a subtree —findAllruns on the parent instead of the whole page - Throws clear error if
parentIdis invalid; gracefully returns[]if parent has nofindAllmethod
BUG-04: Material Icons names produce no helpful error (server/code-executor.js)
- Added
MATERIAL_TO_IONICONSmapping table (60+ common icons:local_cafe→cafe,notifications→notifications, etc.) - When user passes a Material name, error now suggests the Ionicons equivalent
- For unknown
snake_casenames, error suggests kebab-case alternative - Full library scan still runs first — only the error message is improved
Tests
scripts/test-v2521.mjs— 16 new tests (BUG-02 ×5, BUG-03 ×4, BUG-04 ×4, regression ×3)- Full suite: 223 tests, 0 failures (39+13+29+27+23+11+41+24+16)
v2.5.20
docs(v2.5.20): add multi-tab sessionId workflow to api-docs quick-start