/html-to-breakdance

name: html-to-breakdance
description: "Use when the user says 'convert this html to breakdance' or 'paste html into breakdance', or has a Webflow, Framer, CodePen, or old static export to bring into a Breakdance site. Converts raw HTML and CSS into native EssentialElements nodes in _breakdance_data, mapping colors, type, and spacing to Breakdance Variables, and refusing element types Breakdance would skip-render."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.2.0
  mcp-server: respira-wordpress
  category: migration

HTML to Breakdance

**Version:** 1.2.0 **Updated:** 2026-10-04 **Category:** migration **Status:** stable **Requires:** Respira for WordPress plugin 8.6.32+ + Breakdance active + MCP server

---

Description

Convert raw HTML/CSS, pasted from a design export, a Figma extraction, a landing page on another platform, or your own prototype, into native Breakdance elements. Not a screenshot-to-builder pass. This is a structural conversion into the `EssentialElements\*` tree Breakdance's own renderer reads, with the site's Breakdance Variables reused instead of inlined values.

Uses the existing `respira_convert_html_to_builder` MCP tool with a Breakdance-specific workflow layered on top. The Breakdance layer matters because Breakdance stores nothing in `post_content`: the page lives entirely in the `_breakdance_data` post meta, and three of the five ways this conversion can go wrong are invisible unless you check the meta and the public render separately.

---

What Breakdance actually stores

Read this before the workflow. Every step below depends on it.

| Fact | Detail | |---|---| | Storage key | `_breakdance_data` post meta, JSON. `post_content` stays empty | | Envelope | `tree_json_string` (the tree as a stringified JSON) plus a `tree` sibling carrying `root`, `_nextNodeId` and `status`. Both the PHP tree gate and the editor's io-ts decoder need that exact shape | | Node shape (native) | `{ id, data: { type, properties: { content, design } }, children: [...] }` | | Node shape (what you send) | `{ type, attributes: { content, design }, children: [] }`. The attributes bucket is `content` + `design`, never `settings` | | Element type naming | Fully qualified class names: `EssentialElements\Section`, `EssentialElements\Heading`, `EssentialElements\Text`, `EssentialElements\RichText`, `EssentialElements\Button`, `EssentialElements\Image`, `EssentialElements\Video`, `EssentialElements\Divider`, `EssentialElements\Columns`, `EssentialElements\Column`, `EssentialElements\Div`, `EssentialElements\Grid`, `EssentialElements\CodeBlock` | | Content path | Values live at `properties.content.content.<field>`. `content` is the tab, `content.content` is the section inside it. A heading is `content.content.text` plus `content.content.tags` (`h1`..`h6`); a text node is `content.content.text` | | Styling path | `design.*`, for example `design.typography.align`. Design values never go in the content bag | | Children | Genuinely nested. Each node carries its own `children` array. No flat map, no parent refs (that is Bricks) | | Node IDs | Numeric, auto-assigned by the adapter with a floor of 100 (root is id 1). `_nextNodeId` is kept in sync on write. Do not invent IDs | | Render gate | `_breakdance_dependency_cache`, written by Breakdance's own save pipeline. Respira regenerates it best-effort via `\Breakdance\Render\generateCacheForPost`. Without it a perfectly valid tree renders nothing on the front end while the editor looks fine | | Variables | Breakdance Variables (Color, Typography, Spacing) live in the `breakdance_global_settings` option, not in the page |

Lowercase generic types (`heading`, `text`, `section`) are not Breakdance types. A page written with them persists and reports success, and Breakdance skip-renders every node. That was a real report against v6.9.1. The converter maps generics to the `EssentialElements\*` classes for you, which is exactly why you should convert through the tool rather than hand-assembling a tree.

---

When to Use

• A designer hands you HTML/CSS from a Webflow export, a Framer export, or a CodePen
• You are rebuilding a landing page you have the rights to and want to start from its structure
• You have an old static HTML page you want to bring into a live Breakdance site
• You are prototyping a section in HTML and want to land it in Breakdance for further editing

---

Trigger Phrases

• "convert this html to breakdance"
• "import this design into breakdance"
• "paste html into breakdance"
• "html to breakdance"
• "turn this html into a breakdance page"
• "bring this codepen into breakdance"

---

Execution Workflow

Step 1: Verify Breakdance is active

Call `respira_get_builder_info`. If the active builder is NOT Breakdance, stop and tell the user: *"This skill targets Breakdance. Your active builder is {X}. Use the generic `convert html to builder` workflow instead, or switch the active builder."*

If Breakdance is active, capture its version, and note whether the site runs themeless mode (Breakdance replacing the theme). Themeless changes what page chrome the converted page inherits, so it belongs in the report.

Oxygen 6 is a separate skill target even though its adapter extends this one. If the site is Oxygen 6, its types are `OxygenElements\*` and this skill does not apply.

Step 2: Confirm site + target page

Call `respira_get_active_site`. Ask:

• *"Convert the HTML into a new page (I'll create it), or into an existing page (you tell me which)?"*
• If existing: confirm the page ID and say plainly that a SafeEdit duplicate gets created first.

Step 3: Pull the design direction if present

Call `respira_get_design_direction`. If a direction is ACTIVE, capture its color roles, typography, and spacing tokens from `document.tokens`: the conversion maps raw CSS values (`#2563EB`) onto those tokens (`accent`) so the converted page is drift-resistant. Treat th