# How the Figma Plugin Manifest Is Structured in OpenAI Plugins

> Understand the Figma plugin manifest structure used in OpenAI Plugins. Learn how `.codex-plugin/plugin.json` and `.app.json` files separate metadata and runtime configuration for efficient development.

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

---

**The Figma plugin in the OpenAI Plugins repository uses a two-file manifest system that separates core plugin metadata in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) from runtime app configuration in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json).**

The `openai/plugins` repository implements a modular architecture for plugin management, and the Figma integration demonstrates this through its split manifest approach. Understanding the Figma plugin manifest structure is essential for developers building similar integrations or extending the Codex platform's design-to-code capabilities. This architecture separates static metadata from sensitive runtime credentials while maintaining a clear contract between the plugin and the host platform.

## The Two-File Manifest Architecture

The Figma plugin manifest follows a **dual-file pattern** that distinguishes between public plugin metadata and private runtime configuration.

- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** – Contains the complete plugin identity, user interface definitions, skill mappings, and public metadata
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – Stores the connector ID and other runtime-specific credentials required for API communication

This separation allows the main manifest to be version-controlled and shared openly while keeping sensitive connector identifiers in a distinct configuration layer.

## Core Plugin Metadata in plugin.json

Located at [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json), the primary manifest file defines how the plugin appears to users and how it integrates with the Codex platform.

### Identity and Versioning Fields

The root level of [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) establishes the plugin's identity using standard package metadata fields:

```json
{
  "name": "figma",
  "version": "2.0.20",
  "description": "Figma workflows for design implementation, Code Connect templates, and design system rule generation.",
  "author": { "name": "Figma", "url": "https://www.figma.com" },
  "homepage": "https://www.figma.com",
  "repository": "https://github.com/openai/plugins",
  "license": "LicenseRef-Figma-Developer-Terms",
  "keywords": ["figma", "design", "ui", "components"]
}

```

These fields enable the Codex platform to display versioning information, attribute authorship, and categorize the plugin in search results.

### Interface Configuration and UI Branding

The `interface` object controls the visual presentation and capability declarations within the Codex UI:

```json
{
  "interface": {
    "displayName": "Figma",
    "shortDescription": "Figma design-to-code workflows",
    "longDescription": "Figma workflows for implementing designs in code, generating Code Connect templates, and managing design system rules.",
    "developerName": "Figma",
    "category": "Creativity",
    "capabilities": ["Interactive", "Read", "Write"],
    "websiteURL": "https://www.figma.com",
    "privacyPolicyURL": "https://www.figma.com/legal/privacy/",
    "termsOfServiceURL": "https://www.figma.com/legal/developer-terms/",
    "defaultPrompt": [
      "Inspect a Figma design and implement it in code",
      "Create Code Connect templates for my components",
      "Build or update a screen in Figma"
    ],
    "brandColor": "#1ABCFE",
    "composerIcon": "./assets/logo-padded.png",
    "logo": "./assets/logo-padded.png",
    "logoDark": "./assets/logo-padded.png",
    "screenshots": []
  }
}

```

The `capabilities` array declares permission levels (**Interactive**, **Read**, **Write**), while `defaultPrompt` provides suggested user interactions that appear in the interface.

### Skills and App References

The manifest references external resources through path declarations:

- **`skills`** – Points to the `./skills/` directory containing skill definition modules
- **`apps`** – References [`./.app.json`](https://github.com/openai/plugins/blob/main/./.app.json) for runtime configuration

These paths are resolved relative to the plugin root directory, allowing the Codex platform to locate executable code and additional configuration files.

## Runtime Configuration in .app.json

The secondary manifest at [`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json) contains the **connector ID** required for the Codex platform to communicate with Figma's API:

```json
{
  "apps": {
    "figma": {
      "id": "connector_68df038e0ba48191908c8434991bbac2"
    }
  }
}

```

Isolating the connector ID in a separate file prevents sensitive credentials from appearing in the main manifest while maintaining a clear mapping between the plugin and its external service endpoints.

## Loading and Parsing the Manifest Programmatically

When developing tooling around the Figma plugin, you can load the manifest structure using standard file system operations. Here is how to access the core metadata:

```javascript
import fs from 'fs';
import path from 'path';

const manifestPath = path.join(__dirname, 'plugins', 'figma', '.codex-plugin', 'plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log(`Plugin: ${manifest.name} v${manifest.version}`);
console.log(`Capabilities: ${manifest.interface.capabilities.join(', ')}`);

```

To retrieve the connector ID for API authentication:

```javascript
const appPath = path.join(__dirname, 'plugins', 'figma', '.app.json');
const appManifest = JSON.parse(fs.readFileSync(appPath, 'utf8'));

const connectorId = appManifest.apps.figma.id;
console.log(`Figma connector ID: ${connectorId}`);

```

## Supporting Files in the Manifest Ecosystem

Beyond the two primary manifest files, the Figma plugin includes additional configuration files that support the Codex platform's plugin framework:

- **[`plugins/figma/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/figma/plugin.lock.json)** – A lock file generated by the plugin framework that tracks exact dependency versions and ensures reproducible builds
- **[`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json)** – Defines hook points that trigger specific skills when users interact with the Figma plugin through the Codex interface

These files work in concert with the main manifest to provide version control, dependency management, and event routing capabilities.

## Summary

- The Figma plugin manifest uses a **two-file architecture** separating public metadata from runtime credentials
- **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** defines identity, UI branding, capabilities, and skill locations in the `.codex-plugin/` directory
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** stores the connector ID required for Figma API authentication
- The `interface` object controls visual presentation including icons, colors, default prompts, and capability declarations
- **Supporting files** like [`plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugin.lock.json) and [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) manage dependencies and event handling
- Both files use standard JSON syntax and are parsed by the Codex platform to register and display the plugin

## Frequently Asked Questions

### What is the purpose of the .app.json file in the Figma plugin?

The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file isolates runtime configuration from public metadata, specifically storing the connector ID (`apps.figma.id`) that authenticates the plugin with Figma's API. This separation keeps sensitive credentials out of version-controlled manifest files while allowing the Codex platform to locate authentication details at runtime.

### How does the interface object affect the Figma plugin's appearance?

The `interface` object in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) controls all visual aspects of the plugin within the Codex UI, including the `displayName`, `brandColor`, icon assets (`composerIcon`, `logo`), and `defaultPrompt` suggestions. It also declares functional capabilities through the `capabilities` array, which determines whether the plugin supports interactive, read, or write operations.

### Where are skill definitions referenced in the manifest?

Skill definitions are referenced through the `skills` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json), which points to the `./skills/` directory relative to the plugin root. This path tells the Codex platform where to locate executable modules that handle specific Figma-related tasks like design inspection or Code Connect template generation.

### What is the connector ID and why is it separated from the main manifest?

The connector ID is a unique string (`connector_68df038e0ba48191908c8434991bbac2`) stored in [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) under `apps.figma.id` that identifies the plugin instance to Figma's API infrastructure. It is separated from [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) to maintain a security boundary between publicly shareable metadata and credentials that should remain private or environment-specific.