/migrate-visual-composer-to-gutenberg

name: migrate-visual-composer-to-gutenberg
description: "Use when the user says 'migrate visual composer to gutenberg', 'convert vc to blocks', or 'move visual composer pages to the block editor'. Parses the Visual Composer data, maps elements to core blocks, and creates draft duplicates for review."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 2.2.0
  mcp-server: respira-wordpress
  category: migration

Migrate Visual Composer to Gutenberg

**Version:** 2.2.0 **Updated:** 2026-09-13 **Freshly updated:** v2.1.0 adds design-token awareness: conversion writes now register the colors and typography they carry as named design tokens in the block editor's own global styles, and converted pages reference those tokens instead of carrying value copies. Reuse registered tokens instead of re-inlining raw values, and report the registration in the migration summary.

Full-site migration from Visual Composer (WPBakery) to the WordPress block editor (Gutenberg). Audits every Visual Composer page, maps elements to their Gutenberg block equivalents, builds a migration plan for approval, and executes page-by-page conversion into native block markup — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Visual Composer to Gutenberg, switching from WPBakery to blocks, converting Visual Composer pages to the block editor, or moving away from Visual Composer to native WordPress.

What This Skill Does

Visual Composer (now WPBakery Page Builder in its classic form, and Visual Composer Website Builder in its newer form) stores content in post_meta using VCV's custom JSON format. It has been one of the most widely-used WordPress page builders, bundled with thousands of themes. Gutenberg uses a flat block structure in `post_content` with HTML comment delimiters. The migration is moderate: Visual Composer's row/column grid and standard elements translate to Gutenberg, but the ecosystem of third-party VC add-ons and theme-bundled custom elements is vast and varied.

This skill reads every Visual Composer page, extracts the builder content, translates each element to its Gutenberg block equivalent, and writes the result to duplicate pages in native block markup — giving you a complete parallel version of your site to review before going live.

**Handles:**

• vc_row → Group block mapping
• vc_column → Columns/Column block mapping
• vc_column_text → Paragraph/Heading blocks
• vc_single_image → Image block
• vc_btn / vc_button → Buttons/Button block
• vc_video → Video/Embed block
• vc_separator / vc_text_separator → Separator block
• vc_raw_html → Custom HTML block
• vc_empty_space → Spacer block
• vc_custom_heading → Heading block
• vc_row_inner / vc_column_inner → nested Columns blocks
• vc_toggle (FAQ-style) → basic heading + paragraph (flagged for Details block)
• vc_tabs / vc_accordion → basic content fallback (flagged for manual enhancement)

What This Skill Does NOT Do

• Migrate Visual Composer's Design Options (box shadows, borders, gradients) 1:1 — Gutenberg has different styling capabilities
• Convert third-party VC add-on elements (Ultimate Addons, Starter Sites, theme-specific elements) — flagged for manual handling
• Migrate Visual Composer's template library — must be rebuilt in Gutenberg
• Convert WPBakery's frontend editor custom CSS — must be moved to theme/Additional CSS
• Handle the newer Visual Composer Website Builder (vcwb) — this skill targets the classic VCV/WPBakery format
• Replicate VC's parallax backgrounds or scroll effects — Gutenberg has limited support
• Guarantee pixel-perfect visual parity — different rendering approaches

Requirements

• Respira for WordPress plugin installed and connected
• MCP connection active (desktop or WebMCP)
• Visual Composer / WPBakery active on the source site
• Read access to scan Visual Composer content
• Write access to create duplicates with Gutenberg content

Trigger Phrase

• "migrate visual composer to gutenberg"

Alternative Triggers

• "convert visual composer to blocks"
• "switch from wpbakery to gutenberg"
• "move visual composer to block editor"
• "replace wpbakery with gutenberg"
• "visual composer to wordpress blocks"
• "migrate wpbakery to native wordpress"
• "convert vc to gutenberg"

Builder Technical Context

**Source: Visual Composer**

• Content stored in post_meta using VCV's custom JSON format
• Shortcode-based structure in classic mode: `[vc_row][vc_column][vc_column_text]...[/vc_column_text][/vc_column][/vc_row]`
• Read via `respira_extract_builder_content` with `builder=visual-composer`
• Elements: `vc_row`, `vc_column`, `vc_column_text`, `vc_single_image`, `vc_btn`, `vc_video`, `vc_separator`, `vc_raw_html`, `vc_empty_space`, `vc_custom_heading`, `vc_toggle`, `vc_tabs`, `vc_accordion`, `vc_row_inner`, `vc_column_inner`, etc.

**Target: Gutenberg (Block Editor)**

• Content stored in `post_content` as HTML with block comment delimiters
• Format: `<!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->`
• Write via standard WordPress content tools (`respira_update_page` / `respira_update_post`)
• Core blocks: `paragraph`, `heading`, `image`, `buttons`, `columns`, `group`, `html`, `video`, `separator`, `spacer`, `embed`, etc.

Execution Workflow

Phase 1: Pre-Migration Audit

1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance. 2. Detect Visual Composer presence via `respira_get_builder_info` or `respira_list_plugins`. 3. Inventory all Visual Composer content:

• `respira_list_pages` and `respira_list_posts` — identify all content
• `respira_find_builder_targets` with `builder=visual-composer` — find VC-managed pages

4. For each VC page, extract content:

• `respira_extract_builder_content` with `builder=visual-composer`
• Catalog: element types used, nesting depth, third-party elements, Design Options usage, custom