Migrate a Figma design into Penpot with high fidelity: Figma Auto Layout → Penpot flex/grid, Figma Variables → Penpot tokens, Figma component sets → Penpot variants, preserving hierarchy. Reads via the Figma MCP, writes via the Penpot MCP, through an intermediate representation (IR). Degrades to manually-pasted Figma data if the Figma MCP is absent. Triggers: 'migrate from Figma', 'import this Figma file into Penpot', 'move our Figma library to Penpot', 'recreate this Figma design in Penpot', 'Figma to Penpot'.
Migrate a Figma design into Penpot with high fidelity: Figma Auto Layout → Penpot flex/grid, Figma Variables → Penpot tokens, Figma component sets → Penpot variants, preserving hierarchy. Reads via the Figma MCP, writes via the Penpot MCP, through an intermediate representation (IR). Degrades to manually-pasted Figma data if the Figma MCP is absent. Triggers: 'migrate from Figma', 'import this Figma file into Penpot', 'move our Figma library to Penpot', 'recreate this Figma design in Penpot', 'Figma to Penpot'.
penpot-migrate bridges two MCP servers: it reads a Figma design via the Figma MCP and writes it
into Penpot via the Penpot MCP — every mutation goes through execute_code; validate visually with
export_shape; read structure with penpotUtils.shapeStructure (full tool surface:
shared/penpot-mcp-tool-reference.md). It never writes Penpot directly from Figma data — it first builds a normalized
intermediate representation (IR), then translates the IR into Penpot constructs (boards, flex,
tokens, components). If the Figma MCP isn't available, it accepts manually-pasted Figma export/JSON and
works from that.
2. The One Rule That Matters Most
IR before any Penpot write, and migrate in layers. Tokens first, then components, then screens —
each validated. Never one-shot a whole file. The IR is the contract that decouples Figma's model from
Penpot's API.
3. Penpot MCP Tool Reference
Full surface: shared/penpot-mcp-tool-reference.md. Penpot-write side: createBoard/addFlexLayout/
addGridLayout, penpot.library.local.tokens.addToken, createComponent/createVariantFromComponents,
export_shape for fidelity checks. Figma-read side: the Figma MCP's design-context tools (names vary;
treat them as producing raw data the IR normalizes).
4. Plugin API Essentials
Gotcha numbers refer to shared/plugin-api-gotchas.md.
Penpot uses Boards (not Frames); Auto Layout maps to Board flex (dir, gaps, padding, sizing fill/auto/fix) or grid.
Figma Variables → Penpot tokens via addToken({type,name,value}) with the real type strings (shared/tokens-schema.json). Map Figma modes → Penpot themes.
#9 Figma component sets/variants → Penpot variant containers via penpot.createVariantFromComponents(mainInstances) (no combineAsVariants method). Beware #12 — variant mutation corrupts the file; prefer create-then-group, never edit a variant container in place.
#2 token application is async — apply in one call, verify resolvedValue/ in a LATER call; flex overrides child x/y; detach before mutating instance internals.
shape.tokens
#4
#6
Verify unfamiliar signatures with penpot_api_info first.
Constraints — preserve hierarchy/layout/variants; map Variables to tokens; on-grid spacing.
Acceptance Criteria — IR built; tokens migrated & resolving; components/variants reconstructed; screens visually match (export compare); fidelity report.
Act as a migration engineer who prizes structural fidelity.
6. Mandatory Workflow
Visual self-review (mandatory): before every ✋ checkpoint that shows visual work,
run the export → look → fix loop from shared/visual-self-review.md — export the unit you
just built, inspect the image yourself against the checklist, fix visible defects (max 2
iterations), and present that same export with any remaining defects named.
Phase 1 — Build IR. Normalize into the IR (scripts/buildIR.js, references/02-ir-building.md). The IR is plain data; no Penpot writes yet. ✋ Checkpoint: review IR coverage.
Each IR node carries enough to build the Penpot equivalent (layout = flex/grid spec; children reference
components or primitives). Translation reads IR, writes Penpot.
9. Modes & Policies
Default review. Component/variant restructuring and detach never auto (shared/modes-and-policies.md).
10. State Management
Ledger under RUN_ID: phase, ir (or a pointer), migrated:{tokens,components,screens}, gaps:[...]. The IR is the resumable artifact — re-read it after truncation.
