How to Create Code Connect Templates for Figma Components: A Complete Guide

Create a *.figma.ts file next to your component source that uses the MCP runtime to map Figma properties to code props via figma.selectedInstance methods.

The figma-code-connect skill in the OpenAI Plugins repository provides a structured workflow for binding Figma components to their code implementations. This guide explains how to create Code Connect templates based on the official specification in plugins/figma/skills/figma-code-connect/SKILL.md.

Understanding the Code Connect Architecture

Code Connect operates through the MCP (Meta-Component Platform) runtime. When a user selects a Figma instance, the runtime loads the corresponding template file and executes it to generate a typed code snippet.

The MCP Runtime and Template Execution Model

The runtime supplies a singleton figma object where figma.selectedInstance represents the currently selected Figma node. All property extraction happens through methods on this instance, and instance.executeTemplate() returns a ResultSection[] that the MCP engine stitches into the final output.

Property-to-Prop Mapping Rules

The mapping between Figma properties and code props follows strict type conventions:

• TEXT properties use getString() to return simple strings
• BOOLEAN properties use getBoolean() with optional custom value mapping
• VARIANT properties use getEnum() requiring exhaustive mapping for every enum value
• INSTANCE_SWAP properties use getInstanceSwap() followed by executeTemplate() on the returned instance
• SLOT properties use getSlot() returning an array of ResultSections for free-form content

Step-by-Step Workflow for Creating Templates

The figma-code-connect skill defines a six-stage workflow documented in SKILL.md.

Step 1: Parse the Figma URL and Extract Identifiers

Extract the fileKey and nodeId from the Figma URL, converting hyphens to colons in the node ID. This parsing logic is described in lines 30-41 of the skill specification.

Step 2: Discover Unmapped Components

Call the MCP tool get_code_connect_suggestions with excludeMappingPrompt:true to list published components lacking Code Connect mappings. The tool handles three response types: no components available, already mapped components, or a list of candidates requiring templates.

Step 3: Fetch Component Properties

Use get_context_for_code_connect to retrieve the component's property definitions. This returns typed metadata including TEXT, BOOLEAN, VARIANT, INSTANCE_SWAP, and SLOT properties that drive your mapping logic.

Step 4: Identify the Matching Code Component

Search figma.config.json for import paths, then locate a source file whose props interface matches the Figma property list. The skill suggests candidate files and requires user confirmation before proceeding.

Step 5: Create the .figma.ts Template File

Place the template alongside existing files as defined by figma.config.json include patterns. The file must contain specific structural elements documented in lines 106-126 of SKILL.md.

Step 6: Validate the Template

Re-read the file to ensure every Figma property is mapped, types are correct, no hard-coded children exist, and all MCP rules are respected—including never string-concatenating results and always checking type === 'INSTANCE' before executing nested templates.

Template Structure and Syntax

Every Code Connect template follows a strict format with metadata headers and a default export object.

Required Header Comments and Metadata

The template begins with mandatory comment annotations:

// url=https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId}
// source=src/components/Component.tsx
// component=Component

These headers link the Figma instance to your source code and must appear at the top of every *.figma.ts file.

Exporting the Template Object

The file must export a default object containing:

import figma from 'figma'
const instance = figma.selectedInstance

export default {
  example: figma.code`<Component />`,
  imports: ['import { Component } from "primitives"'],
  id: 'component-name',
  metadata: { nestable: true },
}

The example field uses figma.code template literals to construct the output. The imports array declares dependencies, id provides a unique identifier, and optional metadata specifies nesting behavior.

Handling Nested Components and Advanced Patterns

When components contain configurable child instances not exposed as props, the parent template should discover the child's Code Connect template and render it via executeTemplate(). This maintains composability and prevents hard-coding implementation details.

For example, a Button with an icon prop would handle the nested instance swap:

const icon = instance.getInstanceSwap('Icon')
let iconCode
if (icon && icon.type === 'INSTANCE') {
  iconCode = icon.executeTemplate().example
}

export default {
  example: figma.code`
    <Button ${iconCode ? figma.code`icon={${iconCode}}` : ''}>
      ${instance.getString('Label')}
    </Button>
  `,
  id: 'button',
}

Common Pitfalls and Validation Rules

The figma-code-connect skill enforces strict guardrails to ensure template safety:

• Never concatenate template results—always use figma.code tagged templates
• Always guard executeTemplate() calls with type === 'INSTANCE' checks
• Prefer getInstanceSwap over findInstance when a component prop exists
• Ensure variant enum mappings are exhaustive for all possible values
• Avoid hard-coding children—use getSlot for free-form content areas

These rules appear in the "Rules and Pitfalls" section (lines 99-138) of SKILL.md.

Summary

• Code Connect templates use the *.figma.ts extension and live next to component source code
• The MCP runtime provides figma.selectedInstance with methods like getString, getEnum, and getInstanceSwap
• Templates require specific header comments linking to Figma URLs and source files
• Always validate that every Figma property is mapped and type-safe
• Handle nested components by calling executeTemplate() on child instances rather than hard-coding

Frequently Asked Questions

What file extension do Code Connect templates use?

Code Connect templates use the .figma.ts extension. According to the OpenAI Plugins source code, these files must be placed alongside your component source and included in figma.config.json patterns to be discovered by the MCP runtime.

How do I map Figma variant properties to code enums?

Use instance.getEnum() with an exhaustive mapping object that includes every possible variant value. For example, map 'Primary' and 'Secondary' variants to 'primary' and 'secondary' code values. The method requires you to define all enum cases to prevent runtime errors.

Can I include child components in my Code Connect template?

Yes. Use getInstanceSwap() to retrieve child instances, then call executeTemplate() on the returned instance after verifying type === 'INSTANCE'. This renders the child's own Code Connect template within your parent component's output, maintaining proper composition chains.

Where is the figma-code-connect skill defined?

The skill is defined in plugins/figma/skills/figma-code-connect/SKILL.md within the OpenAI Plugins repository. Additional API references are available in plugins/figma/skills/figma-code-connect/references/api.md, while advanced patterns are documented in references/advanced-patterns.md.

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