penpot-migrate — Figma → Penpot, fidelity-first

1. Title + How it works

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.