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

> Learn how to create Code Connect templates for Figma components. Map Figma properties to code props using the MCP runtime and figma.selectedInstance methods. Get the complete guide.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-10

---

**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`](https://github.com/openai/plugins/blob/main/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 `ResultSection`s 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.figma.ts) Template File

Place the template alongside existing files as defined by [`figma.config.json`](https://github.com/openai/plugins/blob/main/figma.config.json) `include` patterns. The file must contain specific structural elements documented in lines 106-126 of [`SKILL.md`](https://github.com/openai/plugins/blob/main/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:

```typescript
// 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:

```typescript
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:

```typescript
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-code-connect/references/api.md), while advanced patterns are documented in [`references/advanced-patterns.md`](https://github.com/openai/plugins/blob/main/references/advanced-patterns.md).