Using Figma Code Connect for Design-to-Code Workflows with OpenAI Plugins

The Figma Code Connect skill in the OpenAI plugins repository automatically generates .figma.ts template files that map Figma components to code snippets by parsing URLs, discovering unmapped components, and matching property interfaces.

This guide explains how to use the Figma Code Connect skill within the openai/plugins repository to bridge the gap between design and engineering. The skill automates the creation of type-safe mapping templates that keep your React components synchronized with Figma designs as they evolve.

How the Figma Code Connect Pipeline Works

The skill follows a deterministic six-step workflow defined in plugins/figma/skills/figma-code-connect/SKILL.md. When you provide a Figma URL, the system executes a pipeline that extracts metadata, analyzes component properties, and generates executable TypeScript templates.

Step 1: Parse the Figma URL

The skill first extracts the fileKey and nodeId from the provided Figma URL. The nodeId format converts from X-Y to X:Y notation to match the Figma API specification. This parsing identifies the specific component or frame within the design file that requires code mapping.

Step 2: Discover Unmapped Components

Using the MCP tool get_code_connect_suggestions, the skill identifies which components in the current selection lack existing Code Connect mappings. This prevents duplicate work and ensures the pipeline only generates templates for new components that need coverage.

Step 3: Fetch Component Properties

The skill invokes get_context_for_code_connect to retrieve a typed description of each component's properties. According to the source code, Figma properties map to specific types: TEXT, BOOLEAN, VARIANT, INSTANCE_SWAP, and SLOT. Each type requires different handling in the generated template.

Step 4: Identify the Code Component

The system reads figma.config.json to resolve import-path aliases, then scans your codebase directories (typically src/components/ or components/) for a component whose prop interface aligns with the Figma property list. This matching ensures that the generated template uses the correct props and types from your actual implementation.

Step 5: Create the .figma.ts Template File

The skill generates a new file alongside existing Code Connect templates, populating it with a figma.code tagged template. The template maps each Figma property to code props using specific API methods:

• instance.getString() for TEXT properties
• instance.getEnum() for VARIANT properties
• instance.getBoolean() for BOOLEAN properties
• instance.getInstanceSwap() for INSTANCE_SWAP properties
• instance.getSlot() for SLOT properties

Step 6: Validate the Output

The final step verifies that every Figma property is represented in the template, confirms imports are correct, and ensures no hard-coded children appear. The validation script post_write_figma_parity_check.sh runs after template creation to verify that rendered code matches the Figma component visually and functionally.

Writing .figma.ts Templates

Generated templates live next to your components and export a default object containing the example code, imports, and metadata.

Basic Template Structure

Here is a minimal template for a Button component, referencing the implementation in SKILL.md lines 78-118:

// url=https://www.figma.com/file/abc123/MyDesign?node-id=42-100
// source=src/components/Button.tsx
// component=Button
import figma from 'figma'

const instance = figma.selectedInstance

const label = instance.getString('Label')
const variant = instance.getEnum('Variant', {
  Primary: 'primary',
  Secondary: 'secondary',
})
const size = instance.getEnum('Size', {
  Small: 'sm',
  Medium: 'md',
  Large: 'lg',
})
const disabled = instance.getBoolean('Disabled')

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

Handling Nested Instances

For components that contain other components (such as an icon inside a button), use getInstanceSwap and check the instance type before executing the nested template:

const icon = instance.getInstanceSwap('Icon')
let iconSnippet = null

if (icon && icon.type === 'INSTANCE') {
  iconSnippet = icon.executeTemplate().example
}

export default {
  example: figma.code`
    <Button ${iconSnippet ? figma.code`icon={${iconSnippet}}` : ''}>
      ${label}
    </Button>
  `,
  id: 'button-with-icon',
}

Always verify type === 'INSTANCE' before calling executeTemplate() to avoid runtime errors.

Working with SLOT Properties

SLOT properties represent nested content areas that accept multiple children. Use getSlot to retrieve a ResultSection[] array:

const content = instance.getSlot('Content')

export default {
  example: figma.code`<Card>${content}</Card>`,
  id: 'card',
}

Never concatenate ResultSection[] objects outside the figma.code tag; always interpolate them inside the template literal.

Critical Rules and Pitfalls

The SKILL.md documentation enforces specific constraints to ensure deterministic and safe template generation:

• Never concatenate ResultSection[] objects. Always interpolate them inside a figma.code tag to maintain proper template structure.
• Skip hasCodeConnect() guards. The runtime automatically handles instances without mappings, so explicit guard checks are unnecessary and should be omitted.
• Use the correct property methods. Call getInstanceSwap for INSTANCE_SWAP properties and getSlot exclusively for SLOT properties—swapping these will cause template failures.
• Validate imports. Ensure figma.config.json correctly resolves import paths before scanning for matching components.

Key Files in the Repository

The Figma Code Connect functionality spans several locations in the openai/plugins repository:

• plugins/figma/skills/figma-code-connect/SKILL.md – Complete specification of the six-step pipeline, API reference, and validation rules.
• plugins/figma/ui/figma-workbench.html – Visual workbench for checking design-code parity after generation.
• plugins/figma/commands/implement-from-figma.md – Command documentation that triggers the Code Connect workflow.
• plugins/figma/scripts/post_write_figma_parity_check.sh – Post-generation validation script to ensure visual consistency.

Summary

• The Figma Code Connect skill in openai/plugins automates the creation of .figma.ts templates through a six-step deterministic pipeline.
• The system parses Figma URLs, discovers unmapped components using get_code_connect_suggestions, and fetches properties via get_context_for_code_connect.
• Templates use specific API methods (getString, getEnum, getBoolean, getInstanceSwap, getSlot) to map Figma properties to code props.
• Always validate that nested instances have type === 'INSTANCE' before calling executeTemplate(), and never concatenate ResultSection[] arrays outside figma.code tags.
• Generated templates are validated by post_write_figma_parity_check.sh to ensure synchronization between design and code.

Frequently Asked Questions

What is the purpose of a .figma.ts file?

A .figma.ts file is a TypeScript template that defines how a Figma component translates into code. It exports a configuration object containing the templated code example, required imports, and metadata that allows the Figma Code Connect runtime to render the correct code snippet when a designer selects a component in Figma.

How does the skill handle nested components?

The skill uses instance.getInstanceSwap() to retrieve references to nested instances. Before executing the nested template, the code must verify that the returned handle has type === 'INSTANCE'. If true, calling executeTemplate() on the nested instance returns its code snippet, which can then be interpolated into the parent template using figma.code tagged literals.

What types of Figma properties are supported?

The skill supports five Figma property types: TEXT (mapped with getString), BOOLEAN (mapped with getBoolean), VARIANT (mapped with getEnum), INSTANCE_SWAP (mapped with getInstanceSwap), and SLOT (mapped with getSlot). Each type requires its specific API method to ensure type-safe code generation.

How do I validate that generated templates match the design?

After template generation, the post_write_figma_parity_check.sh script runs automatically to verify that the rendered code output matches the Figma component's visual appearance and structure. Additionally, you can use figma-workbench.html to perform manual visual parity checks and ensure that mapped properties correctly reflect the design intent.

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