Back to Details

html-to-bricks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HTML to Bricks Builder

HTML to Bricks Builder

Version: 1.1.0 Updated: 2026-08-04 Category: migration Status: stable Requires: Respira for WordPress plugin 7.1+ + Bricks Builder active + MCP server
Version: 1.1.0 Updated: 2026-08-04 分类： 迁移 状态： 稳定 依赖： 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.
将从设计导出文件、Figma提取内容、其他平台现有落地页或竞品源代码中复制的原始HTML/CSS转换为原生Bricks Builder元素。这并非截图转构建器的简单转换，而是遵循Bricks元素架构、ACSS类（若已安装）及站点设计系统的结构化转换。
解决了[开放功能请求：HTML转Bricks Builder]。基于现有
respira_convert_html_to_builder
MCP工具，叠加了Bricks专属工作流。

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
  • 设计师向你提供Webflow导出、Framer导出或CodePen的HTML/CSS文件
  • 你需要重建竞品的落地页（合法操作——请勿复制专有内容），并希望从其结构开始
  • 你有一个旧静态HTML页面，想要导入到正在运行的Bricks驱动站点中
  • 你正在用HTML制作某个区块的原型，希望导入到Bricks中进行进一步编辑

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"
  • "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

步骤1 — 验证Bricks是否激活

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.
调用
respira_get_builder_info
。若当前激活的构建器不是Bricks，则停止操作并告知用户："此技能针对Bricks Builder。你当前激活的构建器是{X}。请改用通用的
convert html to builder
工作流，或切换激活的构建器。"
若Bricks已激活，记录其版本。

Step 2 — Confirm site + target page

步骤2 — 确认站点及目标页面

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.
调用
respira_get_active_site
。询问用户：
  • "将HTML转换为新页面（我会创建它），还是导入到现有页面（请告知具体页面）？"
  • 若选择现有页面：确认页面ID，并提醒用户将创建一个SafeEdit副本。

Step 3 — Pull design system if present

步骤3 — 提取设计系统（若存在）

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.
调用
respira_get_option('respira_design_system')
。若存在，提取颜色、排版、间距令牌。转换过程会将原始CSS值（如
#2563EB
）映射到设计系统令牌（如
primary
），确保转换后的页面能跟随设计系统更新。

Step 4 — Accept the HTML input

步骤4 — 接收HTML输入

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.
三种输入模式：
  • 模式A — 对话中粘贴：用户直接粘贴原始HTML内容。
  • 模式B — URL链接：用户提供公开URL；通过WebFetch或
    /browse
    获取HTML内容。请勿静默托管外部资源；标记外部图片，由用户决定是否镜像。
  • 模式C — 文件：用户上传或引用本地HTML文件路径。
所有模式均支持内联
<style>
块和外部
<link rel=stylesheet>
引用。对于外部样式表，需获取其文本内容。

Step 5 — Run the conversion

步骤5 — 执行转换

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.
The conversion also registers the colors and typography it carries as named design tokens in Bricks' own global styles, and the converted elements reference those tokens instead of carrying value copies. When refining afterwards, reuse the registered tokens (
respira_list_design_tokens
shows them) rather than re-inlining raw hex values or font stacks — and mention the registration, token names and counts, when you report the conversion done.
调用
respira_convert_html_to_builder
，传入参数
builder=bricks
、HTML内容、CSS内容及设计系统上下文。
MCP工具会返回Bricks元素树。每个元素包含
name
（Bricks元素类型——
section
、
block
、
container
、
heading
、
text-basic
、
button
、
image
等）和符合Bricks架构的
settings
。
转换过程还会将识别到的颜色和排版注册为Bricks全局样式中的命名设计令牌，转换后的元素会引用这些令牌而非直接使用原始值。转换完成后，告知用户令牌已注册、令牌名称及数量，后续优化时请使用已注册的令牌（可通过
respira_list_design_tokens
查看），而非重新内嵌原始十六进制值或字体栈。

Step 6 — Map raw values to design system tokens

步骤6 — 将原始值映射到设计系统令牌

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.
针对元素树中的每个元素：
  • 若
    settings.color
    是与设计系统颜色匹配的十六进制值，替换为令牌引用
  • 若
    settings.typography.font-family
    与设计系统的标题或正文字体匹配，替换为令牌引用
  • 若
    settings.padding
    、
    settings.margin
    、
    settings.gap
    是与设计系统间距刻度匹配的像素值，替换为令牌引用
此步骤是一次性转换与可维护页面的核心区别。转换完成后，若用户更新设计系统，转换后的页面会自动同步更新。

Step 7 — ACSS class mapping (if ACSS detected)

步骤7 — ACSS类映射（若检测到ACSS）

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.
调用
respira_get_option('automatic_css_settings')
或检查当前主题是否安装ACSS。若已安装ACSS：
  • 将常见CSS模式映射为ACSS类
  • padding: 96px 24px
    → ACSS区块间距工具类
  • max-width: 1280px; margin: 0 auto
    → ACSS容器类
  • 标题字号 → ACSS标题刻度类
此步骤为可选操作，仅在ACSS已安装时执行。若未安装ACSS，则使用内嵌设置。

Step 8 — Inject into the page

步骤8 — 导入到页面

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.
若为新页面：调用
respira_build_page
，将Bricks元素树作为页面主体。
若为现有页面：先调用
respira_create_page_duplicate
（SafeEdit），再针对副本调用
respira_inject_builder_content
。
输出新页面（或副本页面）的URL。

Step 9 — Verify

步骤9 — 验证

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.
在Bricks编辑器中打开新页面（URL格式为
/?bricks=run&page_id={id}
），进行视觉验证：
  • 所有区块正常渲染
  • 排版显示正确
  • 颜色映射到设计系统令牌
  • 间距保持一致
  • 图片正常加载（若保留了未镜像的外部图片URL，需向用户发出警告）
若存在问题，用户可直接在Bricks编辑器中优化。需标记的常见问题：
  • Bricks无法一对一映射的HTML元素（如
    <details>
    折叠组件→映射为Bricks手风琴组件）
  • 表单——HTML 
    <form>
    无法一对一转换为Bricks Form元素。需标记并请用户手动配置表单字段。
  • 自定义动画——CSS关键帧无法转换。需标记。

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.
  • 仅支持Bricks：此技能仅针对Bricks。若使用其他构建器，请改用通用的
    convert_html_to_builder
    工作流。
  • 禁止直接注入HTML到页面主体：若无法将HTML元素映射为Bricks元素，技能必须报告失败并由用户决定后续操作。请勿退化为使用“代码块”元素粘贴原始HTML——这会回到“请勿编写原始HTML”的错误模式。
  • 外部资源仅标记，不镜像：请勿静默下载外部图片并加载。需标记外部资源，由用户明确决定是否镜像。
  • 现有页面必须使用SafeEdit：禁止直接将HTML转换到已上线页面。必须先创建副本。
  • 设计系统令牌优先于原始值：当CSS十六进制值与设计系统颜色匹配时，必须使用令牌。

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
记录内容：站点URL哈希、Bricks版本、HTML输入大小（字节）、转换元素数量、是否绑定设计系统、是否检测到ACSS、转换成功/失败、总耗时。不会发送HTML内容、元素名称或页面ID。
端点：
POST https://www.respira.press/api/skills/track-usage