> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokencraft.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Figma Integration

> Sync design tokens from Tokencraft directly into Figma using the official plugin

# Figma Integration

Tokencraft integrates with Figma through plugins that allow you to sync design tokens between Tokencraft and Figma variables.

## Community Plugin (Recommended)

A community plugin is available on the Figma Community that provides **bidirectional sync** between Figma variables and Tokencraft:

* **Import**: Sync Figma variables → Tokencraft tokens
* **Export**: Sync Tokencraft tokens → Figma variables
* Full support for all variable types and modes

<Note>
  **Get the plugin**: [Install from Figma Community](https://www.figma.com/community/plugin/1571169428295128880)
</Note>

## Official Plugin

Tokencraft also ships with an official Figma plugin that lets you:

* **Connect via OAuth** — sign in through your browser (recommended)
* Discover all workspaces tied to your account
* Pick one or multiple tokensets to sync in a single run
* Create/update Figma variable collections with full mode support (Light, Dark, etc.)
* Map Tokencraft token types (`color`, `dimension`, `fontSize`, …) to the corresponding Figma variable types

> The official plugin currently syncs **Tokencraft → Figma**. For bidirectional sync, use the [community plugin](https://www.figma.com/community/plugin/1571169428295128880).

## Requirements

* Figma **desktop** app
* Tokencraft account (any plan with Figma plugin access)
* Tokencraft API reachable at `https://app.tokencraft.dev`

## Installation

1. Download the latest Tokencraft Figma plugin bundle (zip) from the dashboard or the internal release page
2. Unzip the archive to a convenient location
3. In Figma Desktop, go to **Plugins → Development → Import plugin from manifest…**
4. Select the `manifest.json` contained in the extracted folder
5. The plugin appears under **Plugins → Development → Tokencraft → Figma Variables**

## Syncing tokens into Figma

### 1. Launch and connect (OAuth)

1. Open your Figma file and run **Tokencraft → Figma Variables**
2. Click **Connect to Tokencraft**
3. Your browser opens the Tokencraft login and consent screen
4. Approve the requested scopes
5. Return to Figma — the plugin receives the token automatically

The OAuth flow uses PKCE and a polling bridge because Figma's sandbox cannot receive redirect callbacks directly. See [MCP OAuth](/mcp/oauth#figma-plugin-oauth) for technical details.

<Note>
  OAuth tokens appear in [API Settings](https://app.tokencraft.dev/api-settings) as `MCP OAuth — Figma Plugin`. Revoke them there to disconnect the plugin.
</Note>

### Alternative: API key (development)

For local development, you can paste a manual API key (`tkc_…`) from [API Settings](https://app.tokencraft.dev/api-settings). The key is stored in Figma client storage per file.

### 2. Load workspaces

1. Click **Load workspaces**
2. Choose the workspace you want to sync (all workspaces linked to the key are listed)

### 3. Select tokensets and modes

1. Tick one or more tokensets you’d like to export
2. Modes defined in Tokencraft (light, dark, …) are mapped to Figma variable modes automatically

### 4. Sync

4. Click **Sync to Figma**
5. The plugin creates or updates one variable collection per tokenset (`Workspace / Tokenset`) and populates variables + modes

### Result

* Variables appear in **Assets → Variables** grouped by `Workspace / Tokenset`
* Modes mirror your Tokencraft mode names (Light, Dark, …)
* Aliases are resolved automatically when possible; missing dependencies are logged in the UI

## Token mapping reference

| Tokencraft type                                                                            | Figma variable type | Notes                                                      |
| ------------------------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------- |
| `color`                                                                                    | `COLOR`             | Supports `#RGB`, `#RRGGBB`, `#RRGGBBAA`, `rgb()`, `rgba()` |
| `dimension`, `number`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `duration` | `FLOAT`             | Numeric strings are parsed (`16px`, `1.5rem`, `200ms`, …)  |
| `fontFamily`, `typography`, `shadow`, `gradient`, `border`, `transition`, `cubicBezier`    | `STRING`            | Stored as stringified values                               |
| `boolean` (future)                                                                         | `BOOLEAN`           | Coerced to `true` / `false`                                |

Tokens that alias other tokens are resolved before being pushed to Figma so variables receive the computed value.

## Network access

`manifest.json` allows the plugin to call:

* `https://app.tokencraft.dev` (production API)

Adjust the list if you host the API elsewhere.

## Troubleshooting

| Issue                               | Fix                                                                                                                                     |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **OAuth connection failed**         | Ensure you're logged into Tokencraft in the browser; try revoking the `MCP OAuth — Figma Plugin` token in API Settings and reconnecting |
| **401 Unauthorized**                | Reconnect via OAuth, or check your API key (dev fallback)                                                                               |
| **Failed to load workspaces (404)** | Ensure the API is reachable at `https://app.tokencraft.dev`                                                                             |
| **No tokensets selected**           | At least one tokenset checkbox must be ticked before syncing                                                                            |
| **Composite tokens stored as JSON** | Extend `setVariableValueForMode` in `code.ts` if you want to break complex types down further                                           |

Logs are printed in the plugin UI to help you diagnose issues quickly.

## Roadmap

* Persist "last synced" metadata in Tokencraft
* Enhanced bidirectional sync features

<Note>
  **Bidirectional sync is now available** through the [community plugin](https://www.figma.com/community/plugin/1571169428295128880) on Figma Community.
</Note>

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Learn the API
  </Card>

  <Card title="JavaScript Integration" icon="js" href="/integrations/javascript">
    Build custom workflows around the plugin
  </Card>
</CardGroup>