How the Figma Plugin Manifest Is Structured in OpenAI Plugins

The Figma plugin in the OpenAI Plugins repository uses a two-file manifest system that separates core plugin metadata in .codex-plugin/plugin.json from runtime app configuration in .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 – Contains the complete plugin identity, user interface definitions, skill mappings, and public metadata
• .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, 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 establishes the plugin's identity using standard package metadata fields:

{
  "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:

{
  "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 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 contains the connector ID required for the Codex platform to communicate with Figma's API:

{
  "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:

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:

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 – A lock file generated by the plugin framework that tracks exact dependency versions and ensures reproducible builds
• 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 defines identity, UI branding, capabilities, and skill locations in the .codex-plugin/ directory
• .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 and 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 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 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, 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 under apps.figma.id that identifies the plugin instance to Figma's API infrastructure. It is separated from plugin.json to maintain a security boundary between publicly shareable metadata and credentials that should remain private or environment-specific.

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