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

> ## Agent Instructions
> These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code.
> The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference).
> Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs.
> Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only.
> Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install.

# Connect Figma files

> Link your Figma file to a Ditto project from your editor: your agent matches text layers to the strings from your codebase, links them, and organizes them.

Use your AI agent to link your Figma file to your Ditto project in minutes. Instead of connecting every text layer by hand, your agent matches, links, and organizes your product copy for you.

You can also link layers one at a time in the Ditto plugin or the web app ([Linking](https://help.dittowords.com/en/articles/11502480-linking) in the help center). From your editor, an agent links a whole file in one pass, in the tools developers already use.

<Info>
  If you ran a scan, your product strings are already in your Ditto component library. The agent matches Figma text layers against them and links the matches, so the layer, the component, and the key in your string files share one developer ID.
</Info>

## Step 1: Connect the Ditto MCP and the Figma MCP

Your agent talks to both Ditto and Figma to accomplish tasks. Ditto is used to search, create, and link text, and Figma is used to read the text layers in your file.

* Ditto MCP server: [Setup](/guides/connect-the-mcp).
* Figma MCP server: [Figma's MCP catalog](https://www.figma.com/mcp-catalog/).

## Step 2: Create the Ditto project from your Figma file

A Ditto project is where your team works on the copy for a feature, product area, or Figma file. Creating it from the file connects the two. This step happens in Figma, once, in the Ditto plugin:

1. In Figma, open the Ditto plugin (**Actions › Plugins & widgets › Ditto**) and log in.
2. Paste your Figma file's URL into the plugin.
3. Select **Start a new project**, click **Continue**, and add the frames you want in Ditto.

For more detail on this step, see [How to create a Ditto project from Figma](https://help.dittowords.com/en/articles/11557887-how-to-create-a-ditto-project-from-figma) in the help center. This step must be done via the Ditto Figma plugin as the API and MCP cannot connect a file.

## Step 3: Instruct your agent

Paste this prompt into your agent with your Ditto project URL and your Figma file URL. The agent tells you what it is about to do at each step and waits for your confirmation before it changes anything.

```text theme={null}
You're helping me link Figma text nodes to Ditto text items, then link matched Ditto text items to library components. Follow these steps in order. At each step, tell me what you're about to do and wait for my explicit confirmation before taking the action — never proceed automatically.

1. Identify the project and file, then confirm
Look up the Ditto project from the URL below and tell me its name. Wait for my confirmation before doing anything else. Then pull all text nodes from the Figma file.

2. Link Figma text nodes → Ditto project text items
For every text node in the Figma file:

- Search only within this Ditto project for a text item whose text is an exact match (case-sensitive, trimmed) to the node's text. Search with matchType "anyWord", not "containsPhrase" — containsPhrase has produced false negatives on real matches (especially contractions like "Don't" or "We'll"). Treat anyWord results as candidates only, then verify each one with a strict trimmed, case-sensitive comparison before calling it a match — never conclude "no match" from an empty containsPhrase result.
- If a match exists, link the node to that existing item.
- If no match exists, create a new text item in the project with the node's text, then link the node to it.
- If multiple Figma nodes have identical text, link each node to the same Ditto text item — don't create duplicate items for repeated text.

3. Link Ditto project text items → library components
Once step 2 is fully done, go through every text item in the project (existing and newly created) and check it against text items in my Ditto component library:
- Search the same way as step 2 — matchType "anyWord", never "containsPhrase" — then verify each candidate with a strict trimmed, case-sensitive comparison.
- If a project text item's text is an exact match to a library component's text, link them.
- If there's no exact match, leave it alone — don't create new components and don't link on partial/fuzzy matches.

4. Report back
Summarize: how many nodes linked to pre-existing items, how many new items were created, and how many items got linked to a library component. Flag anything ambiguous (e.g. near-duplicate text, empty text nodes) instead of guessing.

Ditto project: [Insert Ditto Project URL from the Ditto web app]
Figma file: [Insert Figma File URL]
```

### Save the prompt as a skill

Store the prompt as a skill so anyone on the team runs it by name instead of pasting it. Create a `SKILL.md` with this frontmatter and the prompt above as the body, at the path for your agent, and commit it. Leave the two placeholder lines in place; the agent fills them from the URLs you pass when you run it.

```markdown theme={null}
---
name: ditto-figma-link
description: Link the text layers of a Figma file to a Ditto project and attach exact matches to library components. Use when asked to link, connect, or sync a Figma file with Ditto.
---

<the prompt above>
```

<Tabs>
  <Tab title="Claude Code">
    Path: `.claude/skills/ditto-figma-link/SKILL.md`. Run it with `/ditto-figma-link`, followed by the project URL and the file URL.
  </Tab>

  <Tab title="Cursor">
    Path: `.cursor/skills/ditto-figma-link/SKILL.md`. Run it with `/ditto-figma-link`, followed by the project URL and the file URL.
  </Tab>

  <Tab title="Codex">
    Path: `.agents/skills/ditto-figma-link/SKILL.md`. Run it with `$ditto-figma-link`, followed by the project URL and the file URL.
  </Tab>
</Tabs>

### What the agent does

At each step of the prompt, and the tools it calls:

1. **Identify the project and file.** `list_projects` resolves the project from its URL, and the Figma MCP returns the file's text nodes. The agent works from each node's rendered text, not its layer name.
2. **Link Figma text nodes to project text items.** For each node, `search_ditto_text` with `projectIds` set to the project and `matchType: "anyWord"`, then a strict trimmed, case-sensitive comparison of the candidates. A match is linked with `link_figma_nodes_to_text_item`, up to 50 node IDs per call (`figma.branchId` for a Figma branch). No match: `create_text_items`, then link. Identical text on several nodes links to one text item.
3. **Link project text items to library components.** `search_ditto_text` with `entityTypes: ["libraryComponent"]`, exact matches only. `link_text_items_to_component` attaches each match, and the text item takes on the component's text, properties, variants, and developer ID. No new components, no fuzzy links.
4. **Report back.** Counts of nodes linked to existing items, items created, and items attached to components, plus anything ambiguous (near-duplicate text, empty nodes) for you to decide.

`link_figma_nodes_to_text_item` returns one result per node:

| Outcome                    | Meaning                                                                                 | What to do                                            |
| -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `linked`                   | The node now points at the text item                                                    | Nothing                                               |
| `already_linked`           | The node was already linked to this item                                                | Nothing                                               |
| `not_found`                | Ditto has not synced this node                                                          | Open the plugin in the file, sync the page, and retry |
| `not_text_node`            | The node is not a text layer                                                            | Check the node ID                                     |
| `wrong_file_or_branch`     | The node belongs to a different file or branch than the project                         | Check `projectId` and `branchId`                      |
| `main_component_text_node` | The node is text inside a Figma main component, which Ditto links through its instances | Link the instances instead                            |

## Step 4: What you have now

* **Your Figma text layers are linked to text items.** A text item holds the copy and its status, tags, notes, and comments. Linking does not change the Figma file; from now on, edits to the text item in Ditto and edits to the layer in Figma sync to each other, and frame previews in the web app refresh on sync.
* **Repeated copy points at one text item.** A string that appears on several screens is one text item, so an edit to any instance applies to all of them.
* **Reused text is attached to your components.** Each matched text item carries the component's text, properties, variants, and developer ID, so the Figma layer, the component, and the key in your string files resolve to one ID. Edit the component and every instance updates.

## Link a single layer

For one layer, give the agent the layer's link instead of the file's. In Figma, select the text layer, choose **Copy link**, and tell the agent which string it should show:

```text theme={null}
The "Create account" button at <layer link> should show our production
string. Find that string in Ditto and link the layer to it.
```

The agent reads the node through the Figma MCP, finds the project connected to the file with `list_projects`, searches for "Create account" with `search_ditto_text`, and links the node with `link_figma_nodes_to_text_item`.

## After linking

* **Namespaced developer IDs.** Project-only text items keep auto-generated IDs such as `welcome-to-dittopay-7`. Ask the agent to rename them into a scheme (`onboarding.welcome.title`) with `update_text_items` and `newDeveloperId`. Leave component-linked items alone; that ID is the component's, shared across every project that uses it.
* **Undo a wrong link.** `unlink_text_items_from_component` detaches a text item (every instance carrying that developer ID, or only those in one `projectId`) and gives it a fresh developer ID.
* **Keep in sync.** `npx -y @dittowords/cli@latest pull` brings design-side edits into code; re-running `scan` on the same repository lets Ditto match code-side changes against the earlier scan; the `TextItem_Base_Text_Changed` [webhook](/additional-tools/webhooks#event-reference) fires when linked text changes. Filter `pull` by status or the integrated flag so in-progress design copy never reaches production ([CLI configuration](/cli-reference/configuration#statuses)).