Code Connect Expert

Multiple components at once:

• "Create code connect files for all the components on this page: [Figma URL to a frame/page]"
• "I need code connect files for Button, Card, and Modal — here's the Figma file: [URL]"
• "Batch connect these components: [list of Figma URLs or a single page URL]"

Reviewing/fixing existing files:

• "Review the code connect file for Button and fix any issues"
• "This code connect file isn't mapping correctly, can you fix it?"
• "Update the code connect for Card — new props were added in Figma"

When given a page or frame URL containing multiple components, the skill will use get_metadata to discover all components, then process each one.

Prerequisites

• The user must identify the target React (or Web) component(s) in their codebase, OR the skill will scan the codebase to find matching components
• The user must provide a Figma URL: https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • This can be a URL to a single component, a frame containing components, or a page
  • OR when using figma-desktop MCP, the user can select node(s) directly in the Figma desktop app
• The Figma MCP server is available and will be used to fetch component properties, variants, and layer structure
• The Figma component(s) must be published to a team library

Required Workflow

Follow these steps in order. Do not skip steps.

Step 1: Parse the Figma URL and Discover Components

IMPORTANT: Convert node IDs from URL format (1-2) to colon format (1:2) for all MCP tool calls.

Parse the provided Figma URL to extract the file key and node ID:

• URL format: https://figma.com/design/:fileKey/:fileName?node-id=1-2
• Extract fileKey (segment after /design/)
• Extract node ID from node-id parameter, convert hyphens to colons

For single component requests: Proceed directly to Step 1b.

For batch/multi-component requests: Use get_metadata to discover all components in the frame or page:

get_metadata(fileKey=":fileKey", nodeId="1:2")

This returns the node tree. Identify all <symbol> nodes — these are Figma components. Build a list of components to process, tracking:

• Component name
• Node ID
• Processing status (pending/done/skipped)

Then run Steps 1b through 6 for each component before moving to the next. After all components are processed, present a summary (see Step 7).

Step 1b: Gather Component Information

Before writing any Code Connect file, you must understand both the code component and the Figma component.

For the Figma component — use the Figma MCP:

Always use the MCP tools to get accurate property information. Do not guess property names.

1. Run get_design_context to fetch full component details:

get_design_context(fileKey=":fileKey", nodeId="1:2")

2. From the response, extract:

   • Variant properties (enums): property name and all option values
   • Boolean properties: property name and what they control
   • String properties: property name
   • Instance-swap properties: property name and what components can be swapped in
   • Layer hierarchy: child instances, text layers, and their names

3. If the response is too large or truncated, use get_metadata first to get the node tree, then fetch specific child nodes individually.

4. If any property information is ambiguous or unclear from the MCP response, ask the user rather than guessing. You are the domain expert — it's better to clarify than to produce incorrect property mappings.

Supplementary information: The user may also provide screenshots, documentation, or manually describe properties. Use these to supplement (not replace) what the MCP provides.

For the code component:

1. Read the component file to understand its props interface
2. Identify all props, their types, and default values
3. Note the component's import path
4. Check for sub-components that may need separate connections
5. If the user hasn't specified a component file, scan the codebase for matching components:
   • Search for files with names matching the Figma component name
   • Check common paths: src/components/, components/, lib/ui/, app/components/
   • Present candidates to the user if multiple matches are found

Step 2: Create the Property Mapping Plan

Before writing code, plan how each Figma property maps to a code prop. Cross-reference the Figma properties (from MCP) with the code component's props interface to find the best mappings. Present this plan to the user.

Mapping decisions to make for each Figma property:

Also determine:

• Whether variant restrictions are needed (one Figma component = multiple code components)
• Whether multiple figma.connect calls are needed for the same URL
• Which child components need their own separate figma.connect calls

Step 3: Write the Code Connect File

Create the .figma.tsx (React) or .figma.ts (Web Components) file.

File naming and placement:

• React: ComponentName.react.figma.tsx
• Web Components: ComponentName.web.figma.tsx
• Always place the Code Connect file alongside the code component it connects to (same directory as the component file).
• Check if a Code Connect file already exists before creating a new one. If one exists, update it rather than creating a duplicate. This skill is frequently used to improve existing Code Connect files.

IMPORTANT rules:

• Import figma from '@figma/code-connect/react' for React or from '@figma/code-connect/html' for Web Components
• Import the actual component from the codebase
• Figma property names must match EXACTLY (case-sensitive, including spaces)
• Enum keys must match Figma variant option names EXACTLY
• The example function should return realistic, copy-paste-ready code
• Code Connect files are NOT executed — they are parsed as templates

React template:

import figma from '@figma/code-connect/react'
import { ComponentName } from './ComponentName'

figma.connect(ComponentName, 'https://figma.com/design/:fileKey/:fileName?node-id=X-Y', {
  props: {
    // Property mappings here
  },
  example: (props) => {
    return (
      <ComponentName {...relevantProps}>
        {children}
      </ComponentName>
    )
  },
})

Web Components template:

import figma, { html } from '@figma/code-connect/html'

figma.connect('https://figma.com/design/:fileKey/:fileName?node-id=X-Y', {
  props: {
    // Property mappings here
  },
  example: (props) => html`\
<component-name attr="${props.attr}">
  ${props.content}
</component-name>`,
})

Step 4: Handle Complex Patterns

Apply these patterns based on the component's needs:

Boolean with conditional visibility

When a boolean toggle like "Has Label" controls whether a text property appears: