---
name: html-to-bricks
description: "Convert raw HTML/CSS into native Bricks Builder elements. Maps colors, typography, and spacing to your design system tokens so the result is drift-resistant. ACSS class mapping when ACSS is installed."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.0.0
  mcp-server: respira-wordpress
  category: migration
---

# HTML to Bricks Builder

**Version:** 1.0.0
**Updated:** 2026-05-24
**Category:** migration
**Status:** stable
**Requires:** Respira for WordPress plugin 7.1+ + Bricks Builder active + MCP server

---

## Description

Convert raw HTML/CSS — pasted from a design export, a Figma extraction, an existing landing page on another platform, or a competitor's source code — into native Bricks Builder elements. Not a screenshot-to-builder pass; this is a structural conversion that respects Bricks' element schemas, ACSS classes (if installed), and the site's design system.

Resolves [open feature request: HTML to Bricks Builder]. Uses the existing `respira_convert_html_to_builder` MCP tool, with a Bricks-specific workflow layered on top.

---

## When to Use

- A designer hands you HTML/CSS from a Webflow export, a Framer export, or a CodePen
- You're rebuilding a competitor's landing page (legally — don't copy proprietary work) and want to start from their structure
- You have an old static HTML page you want to bring into your live Bricks-powered site
- You're prototyping a section in HTML and want to land it in Bricks for further editing

---

## Trigger Phrases

- "convert this html to bricks"
- "import this design into bricks"
- "paste html into bricks"
- "html to bricks"
- "turn this html into a bricks page"
- "bring this codepen into bricks"

---

## Execution Workflow

### Step 1 — Verify Bricks is active

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

If Bricks is active, capture its version.

### 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 remind the user that a SafeEdit duplicate will be created.

### Step 3 — Pull design system if present

Call `respira_get_option('respira_design_system')`. If present, capture colors, typography, spacing tokens. The conversion will map raw CSS values (e.g. `#2563EB`) to design system tokens (e.g. `primary`) so the converted page is drift-resistant.

### Step 4 — Accept the HTML input

Three input modes:

- **Mode A — pasted in the conversation.** The user pastes raw HTML directly.
- **Mode B — URL.** The user gives a public URL; fetch the HTML via WebFetch or `/browse`. **Do NOT silently re-host external assets**; flag external images so the user can decide to mirror them.
- **Mode C — file.** The user uploads or references a local HTML file path.

In all modes, also accept inline `<style>` blocks and external `<link rel=stylesheet>` references. For external stylesheets, fetch their text content.

### Step 5 — Run the conversion

Call `respira_convert_html_to_builder` with `builder=bricks`, the HTML, the CSS, and the design-system context.

The MCP tool returns a Bricks element tree. Each element has a `name` (Bricks element type — `section`, `block`, `container`, `heading`, `text-basic`, `button`, `image`, etc.) and `settings` matching the Bricks schema.

### Step 6 — Map raw values to design system tokens

For each element in the tree:

- If `settings.color` is a hex value matching one of the design system colors, replace with a token reference
- If `settings.typography.font-family` matches the design system heading or body family, replace with a token reference
- If `settings.padding`, `settings.margin`, `settings.gap` are pixel values matching the design system spacing scale, replace with token references

This step is the difference between a one-off conversion and a maintainable page. After the conversion, if the user updates the design system, the converted page reflects it.

### Step 7 — ACSS class mapping (if ACSS detected)

Call `respira_get_option('automatic_css_settings')` or check the active theme for ACSS. If ACSS is installed:

- Map common CSS patterns to ACSS classes
- `padding: 96px 24px` → ACSS section padding utility
- `max-width: 1280px; margin: 0 auto` → ACSS container class
- Heading font sizes → ACSS heading scale classes

This is optional and gated on ACSS being present. If ACSS isn't installed, fall through to inline settings.

### Step 8 — Inject into the page

For a new page: call `respira_build_page` with the Bricks element tree as the page body.

For an existing page: call `respira_create_page_duplicate` first (SafeEdit), then `respira_inject_builder_content` against the duplicate.

Output the new (or duplicate) page URL.

### Step 9 — Verify

Open the new page in the Bricks editor (the URL pattern is `/?bricks=run&page_id={id}`). Visually verify:

- All sections render
- Typography looks correct
- Colors map to design system tokens
- Spacing is consistent
- Images load (warn if any external image URLs were preserved unmirrored)

If anything is off, the user can refine in the Bricks editor directly. Common issues to flag:

- HTML elements Bricks doesn't have a 1:1 mapping for (e.g. `<details>` collapsible → mapped to Bricks accordion)
- Forms — HTML `<form>` doesn't convert into Bricks Form element 1:1. Flag and ask the user to wire the form fields manually.
- Custom animations — CSS keyframes don't convert. Flag.

---

## Hard rules

- **Bricks-only.** This skill is locked to Bricks. For other builders, use the generic `convert_html_to_builder` workflow.
- **Never inject HTML directly into the page body.** If the conversion can't map an HTML element to a Bricks element, the skill must report the failure and let the user decide. Do not fall back to a "code block" element that pastes raw HTML — that recreates the do-not-write-raw-HTML failure mode.
- **External assets are flagged, not mirrored.** Don't silently download external images and side-load them. Flag them so the user explicitly decides to mirror.
- **Always SafeEdit on existing pages.** Never convert HTML into a live page directly. Duplicate first.
- **Design system tokens take precedence over raw values.** When a CSS hex matches a design system color, use the token. Always.

---

## Telemetry

Records: site URL hash, Bricks version, HTML input size (bytes), elements converted count, design system bound, ACSS detected, success/failure, total duration. No HTML content, no element names, no page IDs sent.

Endpoint: `POST https://www.respira.press/api/skills/track-usage`