Skip to content

Design Tool Plugins Manual ​

The OIM ecosystem provides native plugins for industry-standard design tools, allowing creative teams to design in their favorite vector UI software and export directly into production-ready .oim containers.

Availability

The Penpot plugin is available now via its hosted manifest URL (https://plugins.oim.media/penpot/manifest.json). The Figma and Framer plugins remain in development; their fields and examples below describe the target design and may change before release.


1. Official Figma Plugin Architecture ​

The Figma plugin (packages/plugin-figma) operates under Figma's dual-process architecture:

  • Sandbox Thread (code.ts):
    • Traverses the selected Figma Frame node tree.
    • Automatically identifies layer roles using naming conventions:
      • [slot] or [oim]: Converted into live layers (the tag name comes from 1.x).
      • [text]: Automatically flagged as localized translatable text.
      • [lottie]: Converted into Lottie micro-animation layers.
      • Locked layers (node.locked === true): Fixed into the base image (the PNG pixels).
  • UI Iframe (ui.html / ui.ts):
    • Displays the live interactive preview.
    • Exposes fields for multi-language translations (en, es) and semantic color binding.
    • Requests a clean PNG raster of the base image from Figma and orchestrates packaging.

2. Figma Design-to-OIM Workflow ​

Exporting from Figma takes three simple steps:

  1. Layer Hierarchy Preparation:
    • Organize your vector assets within a root Frame (e.g. 1080x1080 or 1920x1080).
    • Prefix interactive headline layers with [slot] Headline.
  2. Configure Layer Properties:
    • Open the OIM Plugin from the Figma Plugins menu.
    • Enter localized strings for each supported language.
    • Assign semantic tokens (primary, surface, accent) from the Dynamic Colors palette.
  3. Export & Package:
    • Click Package .oim.
    • The plugin builds the 2.0 document locally with @oim-media/core, packages the base image with signed metadata via /v1/oim/package, and delivers a .oim.png file to disk.
json
{
  "figma_node_id": "12:456",
  "detected_type": "text",
  "name": "[slot] Summer Sale",
  "bounds": { "x": 120, "y": 340, "width": 480, "height": 80 },
  "content": {
    "en": "Summer Collection 2026",
    "es": "Colección de Verano 2026"
  }
}

3. Official Penpot Plugin Integration ​

The Penpot plugin (packages/plugins/penpot) brings OIM authoring to the open-source vector community and is ready to install via Penpot's hosted plugin manifest:

Install in Penpot ​

  1. Open Penpot and open Plugins → Install with URL (Ctrl+Alt+P / plugin manager).
  2. Paste the hosted manifest URL:
    text
    https://plugins.oim.media/penpot/manifest.json
  3. Select a board and launch OIM to translate text layers, bind dynamic fonts, and export a signed .oim.png.

Technical Integration ​

  • Web-First Design Integration: Connects via Penpot's Extension API (plugin.js).
  • Board Configuration Storage: Serializes custom layer attributes directly into board metadata using board.setPluginData("oim-config", ...).
  • Automatic Font Synchronization: Maps web fonts loaded in Penpot to standard font identifiers expected by <oim-player>.

4. Fixed and Live Layers in Plugins ​

Both plugins split a design between the base image and live layers:

  • Fixed Layers: Any layer without an interactive prefix or marked static is flattened into the base image.
  • Vectors & Outlines: SVG paths marked as [slot] are retained as vector definitions and rendered within the player's Shadow DOM overlay.
  • Clip Paths & Bounds: Nested frame clipping boundaries in Figma/Penpot are mapped to SVG <clipPath> definitions; each mask is either baked into the base image or left live.

5. Security & Verification Guardrails ​

Plugins communicate strictly with authorized developer endpoints:

  • Zero Secret Exposure: Plugins require only the developer API key, operating exclusively with /v1/oim/package.
  • Pre-flight Check: Before sending the data, plugins validate that total layers do not exceed 150 and that text payloads are free of dangerous script injections.