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.

In development

The Figma, Framer and Penpot plugins are in development and are not available yet. The behaviour, fields and examples on this page describe the 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 dynamic Layer +1 slots.
    • [text]: Automatically flagged as localized translatable text.
    • [lottie]: Converted into Lottie micro-animation slot containers.
    • Locked layers (node.locked === true): Rendered directly into the baked image (Layer −1, the static PNG background).
• 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 baked image (Layer −1) from Figma and orchestrates compilation.

---

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 Slot 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 sends dimensions to /v1/oim/compile, packages the baked image (Layer −1) with signed metadata via /v1/oim/package, and delivers a .oim.png file to disk.

{
  "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/plugin-penpot) brings OIM authoring to the open-source vector community:

• Web-First Design Integration: Connects via Penpot's Extension API (plugin.js).
• Board Configuration Storage: Serializes custom slot 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. Layer Separation & Masking Rules in Plugins

Both plugins enforce strict Layer Separation guarantees:

• Baked Isolation (Layer −1): Any layer without an interactive prefix or marked static is flattened into the baked base raster 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 (Layer −1) or left live (Layer +1).

---

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/compile and /v1/oim/package.
• Pre-flight Conformance Check: Before compilation, plugins validate that total slots do not exceed 150 and that text payloads are free of dangerous script injections.