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.

Navigating Nuance: Precision in Figma Plugin Communication

As an ESL developer diving into the Figma Plugin API, you’ll quickly realize that technical jargon isn’t just about what something does; it’s profoundly influenced by how you describe it. The language used in code reviews, Slack conversations, and PR descriptions is critical for collaboration and conveying your intent clearly. Often, direct translations from your native language can lead to misunderstandings or, worse, perceived carelessness regarding best practices. Let’s look at some specific areas where ESL developers might face challenges.

One common issue arises when discussing asynchronous operations. The concept of the “UI thread” is fundamental in Figma plugin development – any UI updates must happen on the main thread to avoid crashes and ensure a smooth user experience. However, simply stating “I’m using postMessage” doesn’t fully convey the responsibility involved. A better phrasing would be: “To ensure responsiveness and prevent blocking the UI thread, I’ve structured this data retrieval operation within a Promise that resolves on the main thread before triggering the update to the Figma layer.” Avoid vague terms like “handling it asynchronously.” Instead, focus on how you’re managing the asynchronous flow. Similarly, when describing changes to node types, being precise is key. Saying “I modified a rectangle” isn’t detailed enough; instead, use phrases like: “I updated the rectangle node type to include a new ‘fill color’ property.”

Another area needing careful attention is feedback within code reviews. Receiving comments like “This looks messy” or “Can you refactor this?” can be incredibly frustrating without understanding the underlying reasoning. The key here is to respond with specific, actionable language. Instead of simply accepting criticism, ask clarifying questions: “Could you elaborate on what aspects you find ‘messy’ and suggest a more structured approach?” Or, when discussing potential solutions, use phrases like “I’ll refactor this section to adhere to the PluginAPI best practices for data handling” demonstrating an understanding of the established guidelines. Remember that engineers often communicate through intent – they are not necessarily looking for you to simply fix something, but to understand why it needs fixing and how you intend to address it.

Finally, crafting effective PR descriptions is crucial for maintainability. Don’t just list changes; provide context: “This PR implements a new feature allowing users to dynamically adjust the size of shapes within Figma using the Plugin API’s node manipulation capabilities. The code includes comprehensive error handling and adheres to established naming conventions for improved readability.” It’s about demonstrating understanding, not just execution.

Here’s an example illustrating how you might use the figma.plugin.canvas.insertNode command:

// Example: Inserting a circle node onto the canvas using PluginAPI
const newNode = {
  type: 'circle',
  x: 100,
  y: 100,
  radius: 50,
};

figma.plugin.canvas.insertNode(newNode);

This simple example highlights the importance of accurately describing the operation – inserting a circle node at specific coordinates – rather than just stating “I added a circle.” The clarity here is vital for other developers to understand and potentially build upon your work.