Using Code Connect Templates for Design Tool Integration: A Complete Guide for OpenAI Plugins

Code Connect templates are parserless .figma.js or .figma.ts files that establish a bidirectional link between Figma components and code components by mapping design properties to code props using the Figma plugin runtime API.

The Code Connect system in the openai/plugins repository enables seamless design-to-code synchronization by storing template files alongside your source components. This approach creates a reliable two-way connection that automatically generates framework-specific code snippets from selected Figma instances, eliminating the manual translation between design and development.

What Are Code Connect Templates?

Code Connect templates are special files that live next to your code components and describe how to render code snippets from a selected Figma instance. Unlike the heavy figma.connect() parser, these parserless templates use a lightweight runtime API to extract properties and generate code on-the-fly. Each template contains three mandatory comment headers (url=, source=, component=) and exports an object with example, imports, id, and optional metadata fields.

Architecture and Key Files

The Code Connect system spans multiple layers within the Figma plugin:

• Plugin manifest: plugins/figma/.codex-plugin/plugin.json tells Codex that the Figma plugin exists and provides metadata.
• Skill definition: plugins/figma/skills/figma-code-connect/SKILL.md drives the agent's behavior through step-by-step workflow instructions.
• API reference: plugins/figma/skills/figma-code-connect/references/api.md documents the runtime API (figma.selectedInstance, instance.getString, etc.) that template authors use.
• Configuration: figma.config.json (project-root) tells the Code Connect CLI where to find template files and which language/framework they belong to.
• Template files: Files with the .figma.js or .figma.ts suffix live next to the code components they describe.
• MCP tools: The plugin calls endpoints such as get_code_connect_suggestions and get_context_for_code_connect to discover unmapped components and retrieve property definitions.

The Code Connect Workflow

The system follows a six-step process to establish mappings between design and code:

1. Parse the Figma URL to extract fileKey and nodeId (converting hyphens to colons).
2. Discover unmapped components via get_code_connect_suggestions, which returns published components needing templates.
3. Fetch property definitions using get_context_for_code_connect to obtain Figma property types (TEXT, BOOLEAN, VARIANT, INSTANCE_SWAP, SLOT).
4. Locate the matching code component by reading the project's source tree (typically src/components/…).
5. Write the .figma.* template by mapping each Figma property to the appropriate code prop using API methods like instance.getString and instance.getEnum.
6. Publish the template, allowing the MCP server to validate it and establish the connection for future design-to-code calls.

Why Use Parserless Templates?

Parserless templates avoid the overhead of the figma.connect() parser and let the plugin generate snippets on-the-fly from the selected instance. This approach is ideal for quick, project-specific mappings and works for any framework supported by the label field in figma.config.json, including React, SwiftUI, and Kotlin. The lightweight nature of these templates means they can be updated rapidly without complex build processes.

Code Connect Template Examples

Minimal React Button Template

Create a file named src/components/Button.figma.js next to your component source:

// url=https://www.figma.com/file/abc123/MyFile?node-id=123-456
// source=src/components/Button.tsx
// component=Button
const figma = require('figma')
const instance = figma.selectedInstance

// Extract Figma properties
const label = instance.getString('Label')
const variant = instance.getEnum('Variant', { Primary: 'primary', Secondary: 'secondary' })
const disabled = instance.getBoolean('Disabled')

export default {
  example: figma.code`<Button label="${label}" variant="${variant}" ${disabled ? 'disabled' : ''} />`,
  imports: ['import { Button } from "./Button"'],
  id: 'button',
  metadata: { nestable: true }
}

This example demonstrates the basic structure required in plugins/figma/skills/figma-code-connect/references/api.md, using instance.getString for text properties and instance.getEnum for variant mapping.

Mapping Variants and Booleans

For components with multiple states, use src/components/Card.figma.ts:

// url=https://www.figma.com/file/def456/UI-Kit?node-id=78-90
// source=src/components/Card.tsx
// component=Card
import figma from 'figma'

const instance = figma.selectedInstance

const size = instance.getEnum('Size', { Small: 'sm', Medium: 'md', Large: 'lg' })
const highlighted = instance.getBoolean('Highlighted')

export default {
  example: figma.tsx`<Card size="${size}" ${highlighted ? 'highlighted' : ''}>${instance.getString('Title')}</Card>`,
  imports: ['import { Card } from "./Card"'],
  id: 'card',
  metadata: { nestable: true }
}

The exhaustive getEnum mapping follows the guidance in SKILL.md section 5.2 ("Exhaustive variant handling"), ensuring all Figma variants map to valid code values.

Handling Instance Swaps for Nested Components

When a Figma component contains nested instances (like icons), use instance.getInstanceSwap and executeTemplate():

// url=https://www.figma.com/file/ghi789/Icons?node-id=321-654
// source=src/components/Badge.tsx
// component=Badge
const figma = require('figma')
const instance = figma.selectedInstance

const label = instance.getString('Label')
const icon = instance.getInstanceSwap('Icon') // may be null

export default {
  example: figma.code`
    <Badge label="${label}" ${
      icon ? `icon={${icon.executeTemplate().example}}` : ''
    } />
  `,
  imports: ['import { Badge } from "./Badge"'],
  id: 'badge',
  metadata: { nestable: true }
}

The icon.executeTemplate().example call is the canonical method to embed child components that have their own Code Connect mappings, as documented in SKILL.md section 7.

MCP Integration and Property Discovery

The system relies on two critical MCP endpoints orchestrated by the steps in SKILL.md:

• get_code_connect_suggestions: Returns a list of published Figma components that lack template mappings.
• get_context_for_code_connect: Supplies the type definitions for each Figma property (TEXT, BOOLEAN, VARIANT, INSTANCE_SWAP, SLOT), enabling accurate template generation.

These calls occur in steps 2-4 of the workflow defined in plugins/figma/skills/figma-code-connect/SKILL.md.

Configuration Requirements

Before creating templates, ensure your project root contains a figma.config.json file. This configuration tells the Code Connect CLI where to locate template files and which framework they represent. Without this file, the system cannot properly validate or publish your mappings. For detailed setup instructions, reference plugins/figma/skills/figma-code-connect/references/code-connect-setup.md.

Summary

• Code Connect templates use the .figma.js or .figma.ts extension and live adjacent to their corresponding code components.
• The three comment headers (url=, source=, component=) are mandatory for linking templates to Figma nodes.
• Parserless templates avoid the heavy figma.connect() parser and support rapid iteration for any framework defined in figma.config.json.
• The MCP tools get_code_connect_suggestions and get_context_for_code_connect automate the discovery of unmapped components and their property types.
• Use instance.getInstanceSwap combined with executeTemplate() to handle nested components that have their own Code Connect mappings.

Frequently Asked Questions

What file extension should Code Connect templates use?

Code Connect templates must use either .figma.js or .figma.ts extensions, depending on whether you are writing JavaScript or TypeScript. These files should be placed in the same directory as the component they describe, such as src/components/Button.figma.js alongside src/components/Button.tsx.

How does the system handle nested components with their own mappings?

When a Figma instance contains another component that also has a Code Connect template, use instance.getInstanceSwap('PropertyName') to retrieve the instance, then call executeTemplate().example on the result. This recursively generates the child component's code snippet and embeds it within the parent's output.

What is the difference between parserless templates and figma.connect()?

Parserless templates (.figma.js/.ts) are lightweight files that use a runtime API to generate code on-the-fly from the selected Figma instance, avoiding the heavy parsing infrastructure of figma.connect(). They are ideal for project-specific mappings and work with any framework supported by the label field in figma.config.json, whereas figma.connect() requires more setup and build integration.

Where does the Code Connect skill logic reside in the repository?

The primary workflow logic is defined in plugins/figma/skills/figma-code-connect/SKILL.md, which orchestrates the six-step process from URL parsing to template publication. Supporting documentation for advanced patterns resides in plugins/figma/skills/figma-code-connect/references/advanced-patterns.md, while the API reference is located at plugins/figma/skills/figma-code-connect/references/api.md.

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