# How to Set Up Code Connect Mappings Between Figma and Your Codebase

> Effortlessly set up Code Connect mappings between Figma and your codebase. Link design components to source code for bidirectional sync using MCP Server Tools. Get started now.

- Repository: [Figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)
- Tags: how-to-guide
- Published: 2026-03-30

---

**To set up Code Connect mappings between Figma and your codebase, use the MCP Server Tools (`get_code_connect_suggestions`, `add_code_connect_map`, `send_code_connect_mappings`) to link published Figma components to their concrete source code implementations, enabling bidirectional synchronization between design files and repository files.**

Code Connect is Figma’s bidirectional linking system that synchronizes published components with their code counterparts. According to the `figma/mcp-server-guide` repository, this workflow is orchestrated through a dedicated Model Context Protocol (MCP) skill and low-level API tools that automate the mapping process. This guide covers the complete architecture, implementation strategies, and exact API calls needed to establish these connections.

## Core Architecture of the Code Connect System

The mapping infrastructure in `figma/mcp-server-guide` consists of four integrated layers that handle different aspects of the synchronization workflow.

### MCP Server Tools

The repository exposes four primary tools for Code Connect operations in [`README.md`](https://github.com/figma/mcp-server-guide/blob/main/README.md) under the "Code Connect" section:

- **`get_code_connect_suggestions`** – Scans selected nodes and returns unmapped, published components with their metadata
- **`add_code_connect_map`** – Creates a single mapping between a Figma node and a code file
- **`send_code_connect_mappings`** – Bulk-applies multiple mappings in one atomic operation
- **`get_code_connect_map`** – Retrieves existing mappings for verification

These tools live in the core MCP server implementation and are referenced in [`figma-power/POWER.md`](https://github.com/figma/mcp-server-guide/blob/main/figma-power/POWER.md) as part of the overall capabilities matrix.

### The `figma-code-connect-components` Skill

Located at [`skills/figma-code-connect-components/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-code-connect-components/SKILL.md), this high-level orchestration layer provides the step-by-step logic that agents follow when users request component connections. The skill handles the decision flow from suggestion generation through final mapping persistence, including prerequisite validation and error handling.

### Reference Documentation

The file [`skills/figma-generate-library/references/code-connect-setup.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/code-connect-setup.md) contains detailed parameter tables, error codes, and documentation for mapping tiers (simple vs. template-based). This reference distinguishes between **per-component** and **final-pass** strategies for different workflow phases.

## The Complete Code Connect Mapping Workflow

The [`SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/SKILL.md) file defines a six-phase workflow that agents execute when establishing links between Figma designs and repository files.

### Phase 1: Validate Prerequisites

Before initiating any mapping calls, the system verifies that:
- The target component is **published** to a team library (draft components will trigger `CODE_CONNECT_NO_LIBRARY_FOUND`)
- The user’s Figma plan includes Code Connect access
- The node ID format uses colons (`nodeId=1:2`) rather than hyphens (`node-id=1-2`)

### Phase 2: Generate Suggestions

Call `get_code_connect_suggestions` with the file key and node ID to retrieve candidate components:

```text
get_code_connect_suggestions(
  fileKey="kL9xQn2VwM8pYrTb4ZcHjF",
  nodeId="42:15"
)

```

This returns an array of objects containing `componentName`, `nodeId`, `props`, and `thumbnail` data for unmapped components.

### Phase 3: Match Components to Source Code

The agent searches the repository structure (typically `src/components/` or `components/` directories) for implementation files whose names and prop signatures align with the Figma component definitions. Use repository search tools to locate candidates:

```bash

# Example: Finding Button implementations with ripgrep

rg -i "Button" src/components/**/*.tsx

```

### Phase 4: Present and Confirm Matches

The agent surfaces candidate code files to the user for acceptance, rejection, or refinement. This human-in-the-loop step prevents incorrect mappings before persistence.

### Phase 5: Persist the Mappings

For single mappings, use `add_code_connect_map`:

```text
add_code_connect_map(
  nodeId="42:15",
  fileKey="kL9xQn2VwM8pYrTb4ZcHjF",
  source="src/components/Button.tsx",
  componentName="Button",
  label="React"
)

```

For batch operations during retrofits or library generation, use `send_code_connect_mappings`:

```text
send_code_connect_mappings(
  fileKey="kL9xQn2VwM8pYrTb4ZcHjF",
  mappings=[
    { nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" },
    { nodeId: "43:20", componentName: "Card",   source: "src/components/Card.tsx",   label: "React" },
    { nodeId: "44:5",  componentName: "Input",  source: "src/components/Input.tsx",  label: "React" }
  ]
)

```

### Phase 6: Verify in Dev Mode

Run `get_code_connect_map` to confirm the mapping exists in Figma’s system:

```text
get_code_connect_map(
  fileKey="kL9xQn2VwM8pYrTb4ZcHjF",
  nodeId="42:15"
)

```

Developers can then open the component in Figma’s **Dev Mode** to view the actual code snippet from [`src/components/Button.tsx`](https://github.com/figma/mcp-server-guide/blob/main/src/components/Button.tsx) rather than auto-generated placeholders.

## Implementation Strategies: Per-Component vs. Final-Pass

The [`code-connect-setup.md`](https://github.com/figma/mcp-server-guide/blob/main/code-connect-setup.md) reference document defines two distinct strategies for applying mappings, depending on where you are in the design system lifecycle.

### Per-Component Mapping

Map each component immediately after creation during Phase 3, step 3h of the generation workflow. This approach provides immediate feedback, catches prop signature mismatches early, and ensures continuous synchronization as the design system evolves. The `figma-code-connect-components` skill defaults to this lightweight approach for ongoing development.

### Final-Pass Mapping

Collect all unmapped components after design completion and apply them in a single bulk call via `send_code_connect_mappings`. This strategy is more efficient for retrofitting existing Figma files or performing initial library setup on mature codebases where batch processing reduces API overhead.

## Handling Common Mapping Errors

The [`SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/SKILL.md) and reference documentation catalog specific error codes and their resolutions:

- **`CODE_CONNECT_NO_LIBRARY_FOUND`** – The component exists only as a draft. Publish the file as a team library before mapping.
- **`CODE_CONNECT_MAPPING_ALREADY_EXISTS`** – A mapping already links this node to code. Remove the existing mapping in the Figma UI or skip this component.
- **"No published components found"** – The selection contains unpublished components. Publish them to a library first.
- **URL parsing errors** – Figma URLs use `node-id=1-2` syntax, but the API requires `nodeId=1:2`. Convert hyphens to colons before calling tools.

## Summary

- **Code Connect** creates bidirectional links between Figma components and source code files using four MCP tools: `get_code_connect_suggestions`, `add_code_connect_map`, `send_code_connect_mappings`, and `get_code_connect_map`.
- The workflow is orchestrated by the `figma-code-connect-components` skill in [`skills/figma-code-connect-components/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-code-connect-components/SKILL.md), which enforces a six-phase process from suggestion to verification.
- Components must be published to a team library before mapping; draft components trigger `CODE_CONNECT_NO_LIBRARY_FOUND` errors.
- Use **per-component mapping** for continuous synchronization during active development, or **final-pass mapping** via `send_code_connect_mappings` for efficient bulk retrofits.
- Verify successful mappings by calling `get_code_connect_map` and inspecting the component in Figma Dev Mode.

## Frequently Asked Questions

### What are the prerequisites for creating a Code Connect mapping?

The component must be published to a Figma team library, and the user must have a Figma plan that includes Code Connect features. Unpublished draft components will return `CODE_CONNECT_NO_LIBRARY_FOUND` errors when you attempt to map them. Additionally, ensure your node IDs use colon formatting (`1:2`) rather than hyphen formatting (`1-2`) when passing parameters to the MCP tools.

### How do I map multiple components at once?

Use the `send_code_connect_mappings` tool with an array of mapping objects in the `mappings` parameter. Each object requires `nodeId`, `componentName`, `source` (the file path), and `label` (the framework identifier). This bulk operation is ideal for final-pass strategies when retrofitting existing design systems, as it reduces API calls compared to individual `add_code_connect_map` invocations.

### Why does my mapping return "CODE_CONNECT_MAPPING_ALREADY_EXISTS"?

This error indicates the Figma node already has an existing Code Connect link to a code file. You must either remove the previous mapping through the Figma UI before creating a new one, or skip this component if the existing mapping is correct. The system prevents duplicate mappings to maintain a strict one-to-one relationship between design components and their canonical code implementations.

### Where can I find the complete parameter documentation for these tools?

Detailed parameter tables, error code definitions, and mapping tier specifications (simple vs. template) are documented in [`skills/figma-generate-library/references/code-connect-setup.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-generate-library/references/code-connect-setup.md) within the `figma/mcp-server-guide` repository. The high-level user workflow is defined in [`skills/figma-code-connect-components/SKILL.md`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-code-connect-components/SKILL.md), while the tools are listed in the capabilities matrix at [`figma-power/POWER.md`](https://github.com/figma/mcp-server-guide/blob/main/figma-power/POWER.md).