Connect Figma files

​

Step 1: Connect the Ditto MCP and the Figma MCP

• Ditto MCP server: Setup.
• Figma MCP server: Figma’s MCP catalog.

​

Step 2: Create the Ditto project from your Figma file

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.

​

Step 3: Instruct your agent

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

---
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>

​

What the agent does

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.

​

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

The "Create account" button at <layer link> should show our production
string. Find that string in Ditto and link the layer to it.

​

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 fires when linked text changes. Filter pull by status or the integrated flag so in-progress design copy never reaches production (CLI configuration).