figma-bridge

Figma Bridge

Read and edit live Figma files through the figma-bridge MCP (plugin + local server, no Figma REST API, no rate limits). This skill exists because in real sessions 20% of bridge calls failed, and almost every failure was one of six avoidable mistakes listed under Troubleshooting.

Not the same as Framelink (figma-context-mcp skill, REST API, 6 req/month on free plans). Use the bridge whenever the plugin can be opened in the file. Fall back to Framelink only for files you cannot open in Figma.

Instructions

Step 1: Handshake — list_files first, then pass fileKey everywhere

1. Call list_files before anything else. It never fails and returns [{fileKey, fileName}] for every file where the plugin is open.
2. If it returns nothing, stop and ask the user to run the plugin in the target file (Figma → Plugins → Development → Figma MCP Bridge). Do not retry other tools in a loop.
3. If more than one file is connected, pick the one whose fileName matches the task and pass fileKey on every subsequent call. Omitting it is the error "Multiple files connected. Specify a fileKey".
4. fileKey for cloud files is the id in the URL: figma.com/design/<fileKey>/<name>. Locally unsaved files get keys like unsaved-ms7tl1kp-… that change when the file is reopened. When you see "No plugin connected for fileKey", rerun list_files and use the key it prints.

Step 2: Read with the ladder, never with the firehose

Responses over the context limit are not returned; Claude Code dumps them to a file and you get an error. Server builds from 2026-09-07 on default get_document and get_selection to depth 2 and genuinely honor depth on get_node (it was accepted and ignored before, which is why these calls used to overflow). Truncated levels come back as {id,name,type} stubs with childCount and truncated: true. On an older build, assume every read is unbounded and lean harder on find_nodes.

Use this order:

1. Orient: get_design_context({depth: 2, fileKey}). Returns the current selection if there is one, else the current page, depth-limited. This is how you learn what the user selected and get the node ids. Keep depth ≤ 3.
2. Locate: find_nodes({root, name | regex, type, limit, fileKey}) returns lightweight {id, name, type} rows without serializing subtrees. Scope with root whenever you have a parent id. Or get_node_by_path({path: "Hero/Card/Title"}) for a readable address that survives file revisions.
3. Drill: get_node({nodeId, depth, fields, fileKey}). Default depth: 0 returns the node with children as {id,name,type} stubs; raise depth one level at a time. Combine depth: 1 or 2 with fields to get exactly what you need. Projections that worked well in practice:
   • text specs: ["characters","styles.fontSize","styles.fontFamily","styles.fontStyle","styles.fontWeight","styles.lineHeight"]
   • layout: ["bounds","children.bounds","children.name"]
   • colors: ["styles.fills","styles.strokes","children.styles.fills"]
   • visibility: ["styles.visible","styles.opacity"] Omitted style fields are Figma defaults (opacity 1, visible true, cornerRadius 0, empty fills = none).
4. Bulk: for a big frame you need to study in full, save_children_json({parentId, outputDir, filenamePattern: "{name}.json"}) writes one JSON file per direct child, then grep or jq the files instead of pulling them through context.
5. get_selection and get_document are fine at their depth-2 default. Raising their depth on a large page is still the fastest way to blow the context budget.