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

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 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 as part of the overall capabilities matrix.

The figma-code-connect-components Skill

Located at 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 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 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:

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:

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

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:

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:

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 rather than auto-generated placeholders.

Implementation Strategies: Per-Component vs. Final-Pass

The 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 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, 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 within the figma/mcp-server-guide repository. The high-level user workflow is defined in skills/figma-code-connect-components/SKILL.md, while the tools are listed in the capabilities matrix at figma-power/POWER.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}