/figma-to-gutenberg

name: figma-to-gutenberg
description: "Use when the user says 'figma to gutenberg', 'figma to blocks', or hands over a Figma frame to rebuild on a WordPress site that uses the block editor. Maps the Figma node tree to core Gutenberg blocks, registers the frame's palette in Global Styles, and writes to a draft, so nothing live is touched."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.1.0
  mcp-server: respira-wordpress
  category: migration

Figma to Gutenberg

Rebuilds a Figma frame as a real, editable block-editor page — no page builder required. Reads the Figma node tree (layers, auto-layout, text, colors, images), maps each node to core Gutenberg blocks, registers the frame's palette in the site's Global Styles so the design system carries over, and writes to a draft so nothing live is touched. Works on any WordPress 6.6+ site, including block themes.

What This Skill Does

**Handles:**

• Frames and auto-layout → `core/group` with flex/stack layout (preferred over `core/columns` for row layouts — groups survive later editing and re-reading more faithfully)
• Text nodes → `core/heading` (level inferred from font size) or `core/paragraph`
• Rectangles/ellipses with image fills → `core/image`; lines → `core/separator`; buttons → `core/buttons` + `core/button`
• Repeated patterns by layer name + structure: FAQ stacks → `core/details`, image rows → `core/gallery`, quote-shaped blocks → `core/quote`
• Typography (size, weight, line-height, letter-spacing, alignment) via block supports; families noted for the theme
• Colors: solid fills and gradients on blocks; **the frame's distinct palette registered as named design tokens in Global Styles** (`respira_create_design_token`) so the page references tokens the whole site can reuse
• Spacing from Figma padding/item spacing via block gap and padding supports; per-corner radius and shadows where block supports allow
• Image fills downloaded from Figma and sideloaded into the media library

**Preserves:** text content, links and media; layout structure and nesting; the page stays fully hand-editable in the block editor and Site Editor afterwards.

What This Skill Does NOT Do

• **Pixel-perfect recreation** — the block editor's styling surface is intentionally narrower than Figma's canvas; complex decorative treatments land as flagged custom-CSS notes or flattened images
• **Figma components with overrides / variants** — flattened to visible content and flagged
• **Prototyping and interactions** — skipped
• **Complex vector art, masks, blend modes** — flattened to images where possible, otherwise flagged
• **Auto-generated responsive breakpoints** — core blocks are intrinsically responsive, but design-specific mobile layouts need a manual pass
• **Theme templates** — headers/footers/archive templates are out of scope; this builds page content

Requirements

• Respira for WordPress plugin installed and connected; WordPress 6.6+ with the block editor
• MCP connection active
• **Figma read access from your agent** — a connected Figma MCP, or a Figma file/frame URL plus a personal access token
• Write access to create a draft with the new block content

Trigger Phrase

• "figma to gutenberg"

Alternative Triggers

• "figma to blocks"
• "build this figma design with core blocks"
• "convert figma to the block editor"

Source: Figma

Same read model as every figma-to-* skill: read the selected frame's node tree via the agent's Figma access (Figma MCP, or REST `GET /v1/files/:key/nodes?ids=:id` plus `GET /v1/files/:key/images` for image fills). Key properties: node `type`, `layoutMode`/`itemSpacing`/`padding*`/axis alignment, text `style`, `fills`/`strokes`/`cornerRadius`/`effects`/`opacity`, `characters`, IMAGE fills.

Target: Gutenberg

Call `respira_get_builder_info` first — it lists the registered blocks (theme and plugin blocks included). Author with core blocks by default so the page works on any theme:

**Mapping (Figma → blocks):** `TEXT` → `core/heading` (≥48px h1, ≥36 h2, ≥28 h3, ≥20 h4) or `core/paragraph`; frame with HORIZONTAL layout → `core/group` (flex row) — reach for `core/columns` only when true column semantics are wanted; VERTICAL → `core/group` (stack); IMAGE fill → `core/image`; `LINE` → `core/separator`; CTA pairs → `core/buttons`; FAQ → `core/details`; wide/full sections → group with `align: full` and a background.

Palette: register the frame's colors as design tokens with `respira_create_design_token` (they land in the site's Global Styles), then reference the token slugs in block attributes rather than inlining hex values.

Execution Workflow

**Phase 1 — Read and audit:** verify the site via `respira_get_site_context` + `respira_get_builder_info`; read the frame; inventory nodes, block candidates, images, flags.

**Phase 2 — Build plan:** frame → page title, mapping table, the palette to register, flagged items. Explicit confirmation before any write.

**Phase 3 — Build:** register tokens; sideload images; write the block tree as a draft with `respira_build_page`; read the page back to confirm the block structure survived (`respira_read_page`).

**Phase 4 — Verify with your eyes:** render the draft and compare against the Figma frame (screenshot pass — write success is not visual proof). Refine with `respira_find_element` + `respira_update_element`. Report what carried over, the tokens registered, and what is flagged for a human.

**Phase 5: hand off for review.** Once the draft checks out, share the draft with whoever signs off. `respira_create_review_link` with the draft in `post_ids` sends a Murmur review link they open with no WordPress login, tapping any spot to leave a note; the notes also show in the respira.press dashboard and in Respira AER. Murmur is on the Builder plan and up; on a lower plan the tool answers `respira_murmur_plan`, so send `respira_create_share_link` instead. Read the notes with `respira_list_review_comments`