EP08. "elementor-design-to-page 设计稿转整页"

• 拿到一张设计稿或一张截图，要一路搭出能用的 Elementor 页面，中间要过几道关：这个区块该用哪个容器、这个模块是不是已经有现成 widget、有没有把好几个 widget 拼对位置——elementor-design-to-page 就是把这整条流程串起来的编排型 skill
• 这是 mekko-digital/elementor-skills 开源仓库里 8 个技能中的最后一个，也是压轴的那个：它不重新发明轮子，而是在对的步骤把活派给包里其他 7 个 skill（elementor-feature-lookup 判断免费/Pro、elementor-widget-create 补现成没有的 widget、elementor-deploy-verify 验证部署、elementor-debug-render 排查渲染问题）
• 官方原文说得很直接：「it places and arranges *existing* widgets into a layout, and only authors new code when a needed widget doesn't exist」——这个 skill 的默认动作是「组装」，不是「造轮子」，造轮子是不得已才做的最后一步
• 前置知识：知道 Elementor container/widget 的基本概念，最好已经看过同系列讲 widget 脚手架、免费/Pro 判断、部署验证的几篇笔记

重点内容

这个 Skill 是做什么的

elementor-design-to-page 接受任意形式的设计输入——截图/图片（直接读图）、Figma（链接或导出的 CSS/JSON）、HTML/CSS（最精确，因为已经是结构化数据）、或纯文字描述。它的任务是把这些输入变成一个真的能在 Elementor 后台跑起来的页面，整个过程分成四步，一步一步往下走。

适合用在：

• 客户丢一张设计稿或截图，要求「照这个做一个页面」
• 已有的设计系统/组件库要落地成新的一批 Elementor 页面
• 需要把散落的 widget 组装成一个完整版面（不是写单个 widget，是拼版面）

不适合用在：

• 只是要写/改单一个 widget 的逻辑——那是 elementor-widget-create
• 只是要判断某功能免费还是 Pro——那是 elementor-feature-lookup
• 页面已经建好但渲染出问题——那是 elementor-debug-render

Step 0：先选搭建的运行环境

跟 elementor-deploy-verify 一样要先确定跑在哪：

Step 1：把设计稿读成「版面结构树」

不管输入是截图、Figma 还是 HTML/CSS，第一步都是先在脑子里（或对话里）把设计拆解成一棵结构树，动手搭建之前先把这份计划讲给用户看：

• 最外层的大区块（section）→ 对应 Elementor 的 container（flex 布局）：要记录方向（横排 row / 直排 column）、内容宽度（是否有最大宽度限制 boxed / 满版 full）、间距（gap）、对齐方式、背景
• 区块里面的小模块 → 对应到具体 widget（heading、text-editor、image、button、icon-list……）或者再嵌一层 container 当作分栏
• 要留意响应式的意图（手机版是不是要变成堆叠）和有没有重复/循环出现的内容（比如卡片列表）

Step 2：把每个模块对应到具体 widget（免费/Pro/自建三选一）

每个模块要决定用什么 widget，判断顺序是：

1. 先看是不是标准现成 widget，用 elementor-feature-lookup 确认免费还是 Pro（也确认这个 widget 在目标站点真的存在——有些 Pro 功能或实验性功能没开就是没有）
2. 如果设计需要的东西现成 widget 完全覆盖不了，用 elementor-widget-create 先脚手架出来，再用 elementor-deploy-verify 装上去、确认注册成功——要先确认这一步，再把它摆进页面，不要边搭页面边写没验证过的 widget
3. 优先选免费 widget，除非设计真的非要 Pro 版功能不可；如果用到了 Pro 依赖，要跟用户说清楚

Step 3：动手搭页面

MCP 路径：create-page 建页 → 每个区块跑一次 add-container → 在容器里 add-widget → 设置每个 widget 的具体参数。不确定某个 widget 有哪些可设置项，用 get-widget-schema 查。

wp-cli 路径：自己组一棵 _elementor_data 的元素树（骨架 + 每个 widget 的 settings）写进去。抓精确的设置键名要直接查真实存在的 widget（get_widget_types('name')->get_controls()）——不要凭猜测，键名会随版本不同而变。完整方法、树状结构 schema、和一个完整的 hero 区块范例都在 resources/page-build-reference.md 里。

Step 4：验证

搭完不代表结束，要过两关：

• 渲染有没有跑通：用 elementor-deploy-verify 里的渲染检查（建/存页面、无头渲染、确认没有 fatal 错误、确认预期的内容真的出现了），然后跑 wp elementor flush-css
• 看起来对不对：用 playwright-cli 这个 skill 截图页面 URL，跟原始设计稿比对，边看边调设置
• 如果渲染失败，或者页面空白/内容是旧的——交给 elementor-debug-render 排查

实操细节：几个容易踩坑的技术点

• 响应式值要加后缀键：<key>_tablet、<key>_mobile（比如 align、align_tablet），桌面版用不带后缀的裸键名
• 通用/进阶设置项统一加底线前缀：_element_id、_css_classes、_element_width、_margin、_padding
• 媒体类控件是对象，不是纯网址：image => [ 'id' => <attachment_id>, 'url' => <url> ]——图片要先塞进媒体库拿到 attachment id（MCP 用 sideload-image，或者 wp media import），不能直接塞一条 URL 字符串
• 动态值绑定走 __dynamic__ 映射：设置在元素 settings 上的 __dynamic__ map 才能绑定动态标签（细节见 elementor-dynamic-tag），MCP 那边对应的是 set-dynamic-tag 工具
• 经典架构和 4.0 atomic 架构的设置形状不能混用：经典 widget 用 widgetType，atomic 元素用 e-* 开头的元素类型 + 类型化的 props schema，动手前先确认目标站点/设计要落在哪一套架构
• 每个 container 和 widget 都要有唯一的 7 位十六进制风格 id：id 重复会让整棵树静默坏掉（不报错，但结构乱掉），这个坑很隐蔽，出问题时要优先检查 id 有没有撞车

怎么安装

这个 skill 是 mekko-digital/elementor-skills 这个开源仓库打包的 8 个技能之一，用 Claude Code 的插件市场机制安装，装一次全部到位：

Claude Code（推荐：走插件市场）：

claude plugin marketplace add mekko-digital/elementor-skills
claude plugin install elementor-skills@elementor-skills-marketplace

Claude Code（手动方式）： 把 skills/elementor-design-to-page 这个文件夹复制到 ~/.claude/skills/（所有项目都能用）或专案底下的 ./.claude/skills/（只想在这个项目用）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传 skills/elementor-design-to-page 这个文件夹（打包成 zip，内含 SKILL.md）——插件市场机制是 Claude Code 专属的，Desktop 端目前只能手动上传单个 skill。

常见错误

• ❌ 没跟用户确认版面结构树就直接开搭——设计输入常常有歧义（这个区块是不是要满版、这两栏在手机版是不是该堆叠），动手前先把拆解出来的计划讲一遍给用户看，比搭完再改省事
• ❌ 自建的 widget 没经过 elementor-deploy-verify 验证就直接摆进页面——出问题时分不清是 widget 本身没写对，还是页面搭建的参数传错了
• ❌ 手写 _elementor_data 时凭猜测编设置键名——不同版本键名会变，一定要用 get_widget_types('name')->get_controls() 去问真实存在的 widget 实例，不要靠记忆
• ❌ 经典 widget 的设置形状和 4.0 atomic 元素的 props schema 混着写在同一棵树里——两套东西结构完全不同，混用会直接坏
• ❌ 媒体控件直接塞一条图片网址字符串——Elementor 要的是 [ 'id' => ..., 'url' => ... ] 这种对象，网址要先透过媒体库上传拿到 attachment id
• 💡 id 重复是最隐蔽的坑之一，出现「结构看起来对但页面就是不对」的情况，先检查有没有重复 id
• 💡 这个 skill 是编排者，不是重复造轮子——遇到该交给别的 skill 处理的步骤（判断免费/Pro、造 widget、验证部署、排查渲染），就老实交出去，不要自己越权全包

Sources

官方文档：

1. elementor-skills（GitHub 仓库）— https://github.com/Mekko-Digital/elementor-skills
2. elementor-design-to-page SKILL.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-design-to-page/SKILL.md