Tokens Studio for Figma Plugin Documentation

The figma-bridge tool allows you to control Figma Desktop from the command line using the Chrome DevTools Protocol (CDP). It enables you to execute Plugin-API JavaScript (figma.*) directly in the Figma renderer to read documents, mutate nodes, manage variables, and export assets without using the Figma UI or a manual plugin installation.

Requirements:

• Platform: macOS only.
• Runtime: Node.js 22+ (required for built-in WebSocket and fetch support).

Core Workflow:

1. Use node cli.mjs start to clone, patch, and launch a debug version of Figma.
2. Use node cli.mjs eval to run Plugin-API commands.
3. Use node cli.mjs export or node cli.mjs shot to capture visual output.

Note: start will gracefully quit any currently running instance of Figma to avoid profile conflicts.

# From tools/figma-bridge/
node cli.mjs start
node cli.mjs eval "return figma.currentPage.name"

The Tokens Studio Figma plugin operates using two distinct entry points that communicate via an asynchronous messaging channel. Understanding this separation is key to knowing where logic resides.

Backend (controller.ts)

The backend runs in the Figma environment and is responsible for interacting with the Figma API and managing the plugin lifecycle. Its core responsibilities include:

• Figma API Communication: Instantiating the asynchronous messaging channel to communicate with the PluginInstance.
• Event Registration: Registering handlers for Figma events such as close, selectionchange, and documentchange.
• Dev Mode Compatibility: Registering support for Figma Dev Mode.
• UI Rendering: Triggering the UI display (figma.showUI) and passing necessary local data (e.g., license keys, active themes) to the frontend.

Frontend (index.tsx)

The frontend is the React-based user interface. Once the backend has gathered initial information, the frontend takes over to:

• Tool Initialization: Initializing tracking tools like Mixpanel and Sentry.
• Messaging Setup: Instantiating the messaging channel to communicate with the ReactInstance (the backend).
• Event Handling: Registering specific internal events:
  • GET_THEME_INFO: Retrieves the user's last active theme.
  • STARTUP: Locates the document container to render the React application root, wrapped in providers for Sentry, Redux, and tooltips.

Once the AppContainer component is mounted, it has access to the gathered information and handlers required for user interaction.

Tokens Studio for Figma splits storage configuration into two distinct parts to balance team synchronization with individual security:

1. Storage Type (Shared): The current storage provider type for a document is saved on the figma.root node as shared plugin data. Because this is stored on the Figma document itself, it is externally accessible, ensuring that all team members working on the same file are prompted to use the same provider.
2. API Credentials (Private): Sensitive API credentials for the chosen storage provider are stored locally on the client. This ensures that credentials remain private to the individual user and are not shared via the Figma document.

Startup Lifecycle: When the plugin starts, it reads the shared storage provider from the document and then checks the local client storage for matching API credentials. If credentials are missing, the user will need to provide them.

When building Auto-layout frames, pay close attention to primaryAxisSizingMode and counterAxisSizingMode to avoid collapsed or invisible content.

Vertical Stacks (Hug Contents)

To make a vertical stack grow with its children, set primaryAxisSizingMode to "AUTO". If left as "FIXED", the frame will maintain its initial height and clip the children.

Horizontal Wrap (Grid Pattern)

To create a wrapping row (like a grid of cards), you must configure three specific properties:

1. layoutWrap = "WRAP"
2. primaryAxisSizingMode = "FIXED" (A fixed width is required to trigger the wrap).
3. counterAxisSizingMode = "AUTO" (Allows the height to expand based on the number of rows).

Use itemSpacing for column gaps and counterAxisSpacing for row gaps.

node cli.mjs eval '
  const wrap = figma.createFrame();
  wrap.layoutMode = "HORIZONTAL";
  wrap.layoutWrap = "WRAP";
  wrap.primaryAxisSizingMode = "FIXED";     // fixed width → wrapping kicks in
  wrap.counterAxisSizingMode = "AUTO";      // height hugs the rows
  wrap.itemSpacing = 16;                    // column gap
  wrap.counterAxisSpacing = 16;              // row gap
  wrap.resize(768, 10);                     // width matters; height will hug
  figma.currentPage.appendChild(wrap);
  return { id: wrap.id };
'

AsyncMessageChannel is a communication abstraction used to facilitate asynchronous messaging between different environments in the Tokens Studio Figma plugin. It manages the flow of data between the Figma Plugin Controller (Sandbox), the Figma Plugin UI, and an optional Web Browser Preview.

Data Flow Architecture

• Controller (Sandbox) $\leftrightarrow$ UI: Uses PluginInstance and ReactInstance to bridge the gap between the Figma sandbox and the UI iframe.
• UI $\leftrightarrow$ Browser Preview: When in PREVIEW_MODE, the UI forwards messages via WebSockets to a browser environment to allow for external development/testing.

Environments

• Environment.PLUGIN: The controller entrypoint (Figma Sandbox).
• Environment.UI: The ui entrypoint (Iframe). Has access to parent.postMessage to communicate with the controller.
• Environment.BROWSER: The web preview environment. Communicates with the UI via WebSockets.