How the Figma Plugin Integrates with OpenAI Codex: Architecture and Execution Flow

The Figma plugin connects to OpenAI Codex through a metadata-driven three-layer architecture consisting of a plugin manifest, connector app binding, and OpenAI surface configuration, enabling design-to-code workflows via the Codex runtime.

The openai/plugins repository hosts the official Figma integration for OpenAI Codex, allowing developers to convert Figma designs into production code through automated skills. This integration leverages a declarative architecture that bridges the Codex runtime with the Figma API via connector-based routing and skill-based execution.

Three-Layer Integration Architecture

The integration is implemented through three declarative configuration layers that define how Codex discovers, routes, and presents the Figma plugin to users.

Plugin Manifest Declaration

The foundation of the integration is defined in .codex-plugin/plugin.json, which declares the plugin's identity, capabilities, and runtime assets. According to the source code at lines 1-38, this manifest specifies that the plugin provides read, write, and interactive capabilities for the figma category. This metadata tells the Codex runtime that the plugin can access design data, push updates, and handle interactive user sessions.

Connector App Binding

The logical name figma is mapped to a concrete connector ID in .app.json. As implemented in lines 1-6, this file binds the logical app name to connector_68df038e0ba48191908c8434991bbac2, which the Codex runtime uses to route API calls to the Figma service. This app-backed wiring ensures that when a skill requests design data or needs to push updates, Codex forwards the request to the Figma API via the registered connector rather than making direct calls.

OpenAI Surface Configuration

The user-facing presentation layer is configured in agents/openai.yaml. This file supplies UI metadata including the display name, icons, and default prompt used by the Codex UI when the plugin is presented to users, as defined in lines 1-7. This configuration ensures consistent branding and behavior across CLI, API, and web interfaces.

Skill Execution and Design-to-Code Workflows

Below the configuration layers, the plugin's skills implement the actual design-to-code workflows. Each skill resides under plugins/figma/skills/ and follows the standard Codex skill structure, containing a SKILL.md file and optional implementation scripts.

The figma-implement-design skill translates selected Figma nodes into production-ready UI code. Before execution, the skill enforces pre-conditions defined in agents/figma-implementation-agent.md. According to lines 7-13 of this file, the implementation agent requires calling internal helpers get_design_context and get_screenshot to capture the design state before code generation begins.

When a user invokes a Figma-related command, the execution flow follows this path:

1. The Codex runtime reads .codex-plugin/plugin.json to discover plugin metadata and capabilities
2. It loads .app.json to resolve the connector ID for routing Figma API calls
3. It dispatches the skill request (e.g., figma-implement-design) to the appropriate handler
4. Skill scripts call the Figma API through the registered connector using helpers like get_design_context
5. Generated UI code and Code Connect templates return to the user

Invoking Figma Skills via Codex

You can trigger design-to-code workflows through the Codex CLI or HTTP API.

Command Line Execution

Run the design implementation skill directly from your terminal:

codex run figma-implement-design \
  --prompt "Implement the design at https://www.figma.com/file/abcd1234/MyScreen?node-id=12:34" \
  --output ./generated-ui

Programmatic API Invocation

For automated pipelines, use the Codex HTTP API:

POST https://api.codex.openai.com/v1/plugins/figma/run
{
  "skill": "figma-implement-design",
  "input": {
    "figma_url": "https://www.figma.com/file/abcd1234/MyScreen?node-id=12:34"
  },
  "options": {
    "output_dir": "./generated-ui"
  }
}

Response Structure

The API returns a structured response containing generated files and parity analysis:

{
  "status": "success",
  "files_created": [
    "components/Button.jsx",
    "styles/tailwind.css"
  ],
  "parity_report": {
    "matches": ["layout", "colors"],
    "differences": ["rounded corners (fallback to 4px)"]
  }
}

Summary

• Metadata-driven architecture: The Figma plugin integrates with OpenAI Codex through three configuration files—.codex-plugin/plugin.json for capabilities, .app.json for connector routing, and agents/openai.yaml for UI presentation.
• Connector-based routing: The logical figma app name maps to a specific connector ID that handles all Figma API communication, ensuring secure and routed access to design data.
• Skill-based execution: Actual design-to-code workflows are implemented as skills (such as figma-implement-design) that enforce pre-conditions through agents like figma-implementation-agent.md and utilize helpers including get_design_context and get_screenshot.
• Multiple invocation methods: Users can trigger workflows via CLI commands or HTTP API calls, receiving structured responses with generated code files and design parity reports.

Frequently Asked Questions

What files are required to configure the Figma plugin for OpenAI Codex?

The integration requires four key files: .codex-plugin/plugin.json to declare capabilities and category, .app.json to bind the logical app name to a connector ID, agents/openai.yaml to define UI metadata, and individual skill definitions (such as skills/figma-implement-design/SKILL.md) to implement specific workflows. These files work together to enable Codex to discover, route, and execute Figma-related commands.

How does OpenAI Codex route API calls to Figma?

Codex uses a connector-based routing system defined in .app.json. When a skill requests Figma data, the runtime looks up the logical app name figma in this file, resolves it to the connector ID connector_68df038e0ba48191908c8434991bbac2, and forwards the request through that connector. This abstraction allows the Codex runtime to communicate with Figma without hardcoding API endpoints in the skill logic.

What pre-conditions must be met before implementing a Figma design in code?

Before generating code, the figma-implement-design skill must satisfy requirements defined in agents/figma-implementation-agent.md. Specifically, the agent enforces that the skill calls get_design_context to retrieve node properties and get_screenshot to capture the visual state. These pre-conditions ensure the generated code accurately reflects the current design state.

Can the Figma plugin write data back to Figma, or is it read-only?

The plugin supports both read and write operations. The manifest in .codex-plugin/plugin.json explicitly declares read, write, and interactive capabilities for the Figma category. This means skills can retrieve design data, push updates back to Figma files, and handle interactive sessions where the user and AI collaborate on design modifications.

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