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

> Discover how the Figma plugin integrates with OpenAI Codex. Explore its three-layer architecture and execution flow for seamless design-to-code workflows.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-09-10

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to discover plugin metadata and capabilities
2. It loads [`.app.json`](https://github.com/openai/plugins/blob/main/.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:

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

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

```json
{
  "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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for capabilities, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for connector routing, and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to declare capabilities and category, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) to bind the logical app name to a connector ID, [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) to define UI metadata, and individual skill definitions (such as [`skills/figma-implement-design/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.