# Plugin source authoring Use this reference when producing complete `code.ts` and `ui.html` replacements for `update_generative_plugin`. ## Contents - [Deployment boundary](#deployment-boundary) - [Plan the product contract](#plan-the-product-contract) - [Entrypoint and UI lifecycle](#entrypoint-and-ui-lifecycle) - [PropsKit UI](#propskit-ui) - [Dynamic-page-compatible Plugin API](#dynamic-page-compatible-plugin-api) - [Authoring rules](#authoring-rules) - [Pre-build checklist](#pre-build-checklist) ## Deployment boundary The MCP update accepts a `files` array containing complete replacements for existing authored files: ```json [ { "path": "code.ts", "content": "" }, { "path": "ui.html", "content": "" } ] ``` It can replace `code.ts` and `ui.html`. It cannot replace `manifest.json`, create a missing file, or accept a diff. Unspecified files are preserved, so include only files that changed. A metadata-only update can use an empty `files` array with `metadata.name` and/or `metadata.description`. After create/get: 1. Read the manifest, UI, and current entrypoint URIs. 2. Verify the manifest targets `editorType: ["figma"]`, includes functional UI, and uses dynamic-page access. 3. Preserve the existing UI message contract when it fits the requested workflow. 4. When different controls are required, replace `ui.html` and update `code.ts` so their message contracts agree. 5. If the existing manifest itself is incompatible and the requested behavior requires changing it, surface that limitation; `update_generative_plugin` cannot repair it. Do not add imports, extra source files, build configuration, or dependencies that the tool cannot deploy. ## Plan the product contract Before coding, define: - The primary action and whether it creates, transforms, or inspects layers. - Required selection and input states. - UI controls, defaults, validation, and status copy. - Messages sent UI → sandbox and sandbox → UI. - Which operations are repeatable and which close the plugin. - The exact created/modified layers, placement, selection, and viewport behavior. - Maximum expected work and how it is bounded. - Whether relaunch data or lightweight persisted preferences are useful. Every plugin needs functional UI. Even a zero-parameter operation needs a clear primary button plus useful disabled/error/success feedback. ## Entrypoint and UI lifecycle The sandbox is the only side that can call `figma.*`. The UI iframe is the only side that can use DOM/browser APIs. Communicate exclusively through messages. `code.ts` owns Plugin API calls and loads the separate UI with `__html__`: ```ts const PANEL_WIDTH = 280 type UiMessage = | { type: 'resize'; height: number } | { type: 'run'; count: number } figma.showUI(__html__, { width: PANEL_WIDTH, height: 240 }) figma.ui.onmessage = async (message: UiMessage) => { if (message.type === 'resize') { figma.ui.resize(PANEL_WIDTH, Math.max(120, Math.min(900, Math.round(message.height)))) return } if (message.type === 'run') { // Validate, mutate, report status. Close only for a genuinely one-shot flow. } } ``` `ui.html` owns the DOM and sends messages to the sandbox: ```html
Create layers
``` Do not close the plugin before asynchronous operations and messages finish. Keep it open for repeatable panels; close only after a one-shot action has completed or a terminal error is shown. ## PropsKit UI Use PropsKit `fig-*` controls rather than raw HTML equivalents where available. Structure the panel as `` followed by ``. - Wrap controls in `` with a child `