Skip to content

Releases

v2.5.30

Choose a tag to compare

@github-actions github-actions released this 26 Oct 07:27

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_detail returned every stroke property except the one that says a border is dashed, and get_css hardcoded solid for 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 dashPattern since BUG-17, so a border drawn through this bridge could not be read back as it was drawn.
  • get_node_detail and get_design_context now report dashPattern when non-empty; get_css emits dashed plus 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 — behind get_design and scan_design — had the same omission and is fixed here too, so all four read paths now agree.
  • scripts/test-dash-pattern.mjs covers 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

Choose a tag to compare

@github-actions github-actions released this 11 Oct 09:04

Fixed

Plugin UI counted advisory messages as errors (plugin/ui.html)

  • handlers-create.js posts a { type: "log" } warning when a child is created with explicit x/y inside an auto-layout parent. window.onmessage only special-cased session-info, so that warning fell through to the operation-result path: msg.success was undefined, the error counter incremented, and the Activity log printed ✗ ? undefined — no op id, no message. One create therefore produced a visible error alongside its own success line.
  • It then called sendResponse(undefined, ...), and the bridge logged settle ORPHAN response id=undefined for 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 required unless a per-mode value was supplied, but name and description are variable-level, not per-mode. Renaming a token therefore needed a dummy value. It now accepts value, name or description in 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 over STRETCH. 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.
  • applyChildLayout now promotes the cross-axis sizing to FILL when layoutAlign: "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

Choose a tag to compare

@github-actions github-actions released this 11 Oct 08:45

Added

  • scripts/test-read-parity.mjs — runs the pre-refactor extractDesignTree and 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 gains fontFamily, fontWeight and mixedStyles where 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

Choose a tag to compare

@github-actions github-actions released this 26 May 09:44

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 applyVariableValue now 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 applyVariableValue change — 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 setupDesignTokens a second time with literal fontFamily: "Inter" (no fonts: 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/fontStyle before assigning the new literal.

BUG-FONT-01 (HIGH): system fonts produced cryptic error (src/plugin/handlers-tokens.js)

  • setupDesignTokens with fontFamily: "SF Mono" (or SF Pro, system-ui) failed with generic font 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 Code
    • SF Pro → Inter, Manrope, DM Sans
    • system-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: 100 in handlers.create destructuring 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-appendChild re-apply uses hasExplicitWidth/hasExplicitHeight instead 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: delete now blocks frames containing COMPONENT / COMPONENT_SET descendants by default. Response includes blocked: "contains-components", componentCount, componentNames. Caller passes force: true to 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 > 0 or 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" on text/label falling 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 setupDesignTokens on 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 call setupDesignTokens once per session; use modifyVariable for 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

Choose a tag to compare

@github-actions github-actions released this 22 May 09:47

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_MS raised 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_MS raised 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 via AbortController instead of just flipping a flag and waiting up to 12s for the existing await fetch() to settle. Previously could create overlapping poll loops.
  • #killStaleBridges() now kills ALL PIDs holding the port, not just the first one returned by lsof. Multiple zombie processes (from repeated npx figma-ui-mcp runs) 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 via figma.importComponentByKeyAsync() before falling back to a clear error message pointing at createComponent(...).id / listComponents()
  • api-docs.js example updated — uses iconMaster.id from createComponent() 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

Choose a tag to compare

@TranHoaiHung TranHoaiHung released this 19 May 04:49

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:

  1. Master-side property definitions (PR #8 — addComponentProperty, bindComponentPropertyToText, removeComponentProperty) — create TEXT / BOOLEAN / INSTANCE_SWAP properties on a COMPONENT or COMPONENT_SET, bind a child TEXT's .characters so override values flow through the property pipeline.
  2. 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.
  3. Cross-page component lookup under dynamic-page access (PR #9 — loadAllPagesAsync) — instantiate now calls await figma.loadAllPagesAsync() before findOne, mirroring what listComponents already did. Also exposes figma.loadAllPagesAsync() to user code so arbitrary cross-page queries work.
  4. 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.
  5. Modern per-child layout sizing + auto-promote (PR #11 — layoutSizingHorizontal/layoutSizingVertical params on create/modify, auto-promote TEXT to HUG on content change) — Figma's modern layoutSizingHorizontal: "FIXED" | "HUG" | "FILL" beats legacy textAutoResize for children of auto-layout. When modify({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 → setComponentProperties false → 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

Choose a tag to compare

@github-actions github-actions released this 18 May 17: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.mjs updated to assert empty-object behavior
  • Full suite: 292 tests, 0 failures

v2.5.22

Choose a tag to compare

@github-actions github-actions released this 18 May 17:00

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 a COMPONENT or COMPONENT_SET. Validates defaultValue per type, rejects VARIANT with a clear message (variants live on component sets via combineAsVariants()).
  • bindComponentPropertyToText — bind a child TEXT node's .characters to 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 raw characters write.
  • removeComponentProperty — delete a property definition. Bare-name → name#id resolution 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 to null when 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

Choose a tag to compare

@github-actions github-actions released this 05 May 16:46

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 under documentAccess: dynamic-page
  • Both setupDesignTokens and applyTextStyle now use getLocalTextStylesAsync exclusively
  • Fixes: Cannot call with documentAccess: dynamic-page. Use figma.getLocalTextStylesAsync instead.

BUG-02: VECTOR fill rejects gradient objects (src/plugin/handlers-write.js)

  • buildVector now uses buildFillArray (same as FRAME/RECTANGLE) instead of solidFill
  • 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 limit param)
  • New parentId param scopes search to a subtree — findAll runs on the parent instead of the whole page
  • Throws clear error if parentId is invalid; gracefully returns [] if parent has no findAll method

BUG-04: Material Icons names produce no helpful error (server/code-executor.js)

  • Added MATERIAL_TO_IONICONS mapping 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_case names, 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

Choose a tag to compare

@github-actions github-actions released this 19 Apr 04:52
docs(v2.5.20): add multi-tab sessionId workflow to api-docs quick-start