Figma Plugin API: English for Design Tool Development

Figma plugins are JavaScript programs that run inside the Figma desktop and browser apps and can read and modify the current design document. Plugin development requires understanding a specific two-thread architecture and a large API surface for manipulating design nodes. If you are an ESL developer building internal Figma tooling or publishing plugins to the community, the vocabulary in this post will help you read the Figma Plugin API documentation and discuss design automation in English.

Architecture: Two Threads

main thread — the sandboxed JavaScript environment where your plugin code runs and where all Figma API calls are made; it has direct access to the document but no access to browser APIs like fetch or localStorage.

“All node manipulation must happen in the main thread because the Figma Plugin API is only available there, not in the UI iframe.”

UI thread — a separate sandboxed iframe that your plugin can optionally open to display a custom HTML interface; it has access to browser APIs but cannot call the Figma Plugin API directly.

“We built the settings form in the UI thread using a React component, and used postMessage to send the user’s choices back to the main thread for processing.”

postMessage — the browser standard API used to pass messages between the main thread and the UI thread in both directions; it is the only communication channel between the two sandboxes.

“When the user clicks Save in the UI thread, we call postMessage to send the configuration object to the main thread, which then applies the changes to the selected nodes.”

Plugin Manifest

manifest — the manifest.json file at the root of every Figma plugin that declares the plugin’s name, ID, entry point scripts, permissions, and menu items; Figma reads this file to install and launch the plugin.

“We added the network permission to the manifest after Figma rejected the plugin because it tried to make fetch calls without declaring the permission upfront.”

plugin ID — a unique string assigned to your plugin when you create it in Figma; it must match the id field in the manifest and is used to identify your plugin in the Figma community and in API calls.

“After transferring the plugin to the company’s Figma organisation, we updated the plugin ID in the manifest to match the new owner’s plugin entry.”

PluginAPI and Node Access

PluginAPI — the global figma object available in the main thread that exposes all plugin functionality, including the current file, current page, selection, UI control, and node creation methods.

“We access everything through the PluginAPI object: figma.currentPage to find where to insert nodes, and figma.ui to open and communicate with the UI thread.”

figma.currentPage — the PluginAPI property that returns the page the user is currently viewing, allowing you to traverse its node tree or add new nodes to it.

“We iterate over figma.currentPage.children to find all top-level frames and generate a report of their names and dimensions.”

createRectangle — a PluginAPI method that creates a new rectangle node and inserts it into the document; after calling it you must append the node to a parent to make it visible.

“We call figma.createRectangle(), set its width, height, and fill, and then append it to the selected frame to place a background shape behind the content.”

Node Types and Properties

node types — the categories of design objects in a Figma document, including FRAME, TEXT, RECTANGLE, ELLIPSE, COMPONENT, INSTANCE, and GROUP; each type has its own set of readable and writable properties.

“We filter figma.currentPage.findAll() to only INSTANCE nodes so the plugin only processes component instances and ignores raw shapes.”

setSharedPluginData — a PluginAPI method that stores arbitrary key-value data on any node in a namespace scoped to your plugin, persisting even after the plugin closes.

“We call setSharedPluginData on each annotated node to store the linked Jira ticket ID so the plugin can look it up the next time it runs without prompting the user again.”

getSharedPluginData — the complementary method that reads data previously stored with setSharedPluginData, allowing your plugin to maintain persistent state tied to specific design nodes.

“On startup, we call getSharedPluginData on all nodes to rebuild a map of existing annotations so the plugin does not create duplicate entries.”

Closing the Plugin

figma.closePlugin — the PluginAPI method that shuts down the plugin and optionally displays a toast notification to the user; calling it is required to properly end the plugin’s execution.

“After applying all the style changes, we call figma.closePlugin(‘Styles updated successfully’) so Figma shows the user a confirmation message and cleans up the plugin’s resources.”

Practice

Write a minimal Figma plugin that finds all TEXT nodes on the current page and logs their character content to the console. Add a UI panel with a button that sends a postMessage to the main thread to trigger the scan. In English, explain to a colleague why you cannot call figma.currentPage from inside the UI thread and what architectural decision forces this separation.