figma-to-weaverse

Figma 转 Weaverse

将 Figma 设计转化为易于维护的 Weaverse 页面。这是 Figma 输入适配器，与 cloning-websites-to-weaverse 配套，但来源是 Figma 文件，而不是在线 URL。两个适配器最终都会汇入同一个下游技能 generating-weaverse-project-json。

Figma file / frame ─→ figma-to-weaverse ─→ generating-weaverse-project-json ─→ import / content API
   (Figma MCP)        (tokens + manifest + preview)        (project JSON)

两个适配器共享相同的下游规则。区块匹配、深度架构验证、内容清单、克隆预览路由和品牌指南冲突规则都与 cloning-websites-to-weaverse 完全相同；完整的匹配逻辑请参阅该技能。本技能仅替换提取层（使用 Figma MCP，而非 Firecrawl），并补充 Figma 特有的注意事项。

使用场景

• 页面或店面的来源是 figma.com URL（文件、画框或选区）
• “在 Weaverse 中实现此设计”“根据 Figma 构建首页”
• 映射到多个 Weaverse 页面的多画框流程

不要将其用于在线网站克隆（请使用 cloning-websites-to-weaverse）或微小的文案修改。

必需输入

• 带有 node-id 的 Figma URL（页面/画框），或当前选区。只有文件的 URL 不够；请索取节点链接。
• .guides/brand-guideline.md
• sections.md
• app/weaverse/components.ts
• 目标页面类型和路由（见“预检”）
• 交付所需：Weaverse 项目 ID 和 WEAVERSE_API_KEY（见 weaverse-content-api）

预检（提取任何内容之前）

跳过以下任一项，都会导致整个返工流程：

1. 页面类型和路由。 询问设计将用作首页（INDEX）、落地页（CUSTOM，例如 /disney），还是单个句柄的资源模板（COLLECTION/PRODUCT）。这决定允许使用哪些区块（enabledOn）以及数据如何加载。不要根据导航链接推断。
2. 正确的店面。 .env 中的 PUBLIC_STOREFRONT_ID 必须与 .shopify/project.json 中的店面一致。.env 不匹配会导致本地渲染其他品牌的销售渠道，并且已发布的集合看起来像是缺失了。使用 npx shopify hydrogen env pull 修复。
3. 正确的品牌指南。 确认 .guides/brand-guideline.md 描述的是此品牌（仓库通常是从关联品牌克隆而来）。如果不是，请遵循 Figma 设计令牌，在规格说明中注明，并请用户替换品牌指南。
4. Weaverse 项目状态。 读取项目页面（pages <projectId>）：空的 COLLECTION/PRODUCT 模板在这些路由上只会渲染页眉和页脚——请指出这一点，这并非由你的页面导致。
5. 现有说明。 阅读仓库中已有的 .figma/*.md 规格说明；页眉/页脚/菜单的工作以及令牌决策可能已经完成。

必需交付物

与网站克隆技能相同的三项交付物，另加上线页面：

1. 内容清单 — 按区块列出真实资源 URL（来自 Figma 资源导出，之后替换为 Shopify CDN URL）、文本、链接、Shopify 引用和媒体类型。
2. 克隆预览路由 — 在 app/routes/clone-preview.$page.tsx 中添加 $page 分支，以 React + Tailwind 渲染完整设计，并标注区块、调整品牌样式。必须先获得用户批准，才能拆分区块。
3. 设计规格 — 区块映射、注释表、架构边界、交互模型、令牌映射。
4. 上线的 Weaverse 页面 — 通过 Content API 推送，并在已部署的店面上验证；页面 JSON 保存在 .clone/<page>/ 中。
5. 视觉检查通过 — .figma/<page>.visual.json 和 .figma/ref/<page>/ 中的 Figma 参考截图，以及最终的 scripts/visual_check.mjs 报告，其中显示 Result: PASS（列出例外情况）。未完成此项，页面就不算完成。

使用 Figma MCP 提取（MCP 优先）

使用 Figma MCP 工具。它们会返回结构化设计数据——提取设计令牌和布局时比抓取 HTML 更精确，但在真实交互方面较弱（静态设计没有运行时行为）。

在使用 get_design_context 前加载 figma-design-to-code，在进行任何 use_figma 写入调用前加载 figma-use。

1. 对页面框架调用 get_design_context 是首要操作。 一次调用会返回参考代码、截图、资源 URL、所用的文本/颜色样式以及组件描述。如果响应被截断，在编写任何内容前，先从已保存的输出中读取被省略的中间部分。如果它询问 Code Connect，请原样询问用户并遵循其回答。
2. 收集注释。 设计师备注会以 data-development-annotations（语义：H1/H2/H3、“这不是标题，而是链接”）和 data-interaction-annotations（菜单、链接目标、悬停行为）的形式返回。将每条注释都提取到规格说明中的注释表，并将其映射到一项需求——在长响应中很容易遗漏。Figma 评论无法通过 MCP 读取；如果相关，请向用户索取。
3. 设计令牌。 文件使用变量时调用 get_variable_defs；否则使用 get_design_context 响应末尾的样式列表。仅将全站级值映射到 project.config.theme；页面专属颜色保留为区块设置。
4. 结构。 仅使用 get_metadata 作为参考（选择节点、查找框架）。设计上下文中的顶层框架就是区块边界。
5. 交互提示。 图层名称会表达意图（例如 Grows Upward — Demo (hover to test)、Carousel Demo、Sort Dropdown (Grows Downwards)）。记录这些提示；不要据此臆造额外动画。
6. 资源。 设计上下文会列出资源 URL（figma.com/api/mcp/asset/...）。它们会在约 7 天后过期。尽早下载文件内容并检查（其中一些是纯色 SVG、装饰性蒙版，或需要翻转/裁剪后显示的图片）。
7. 全局部分。 页眉、导航、下拉菜单和页脚通常包含在每个框架中。将它们视为布局/主题工作（主题设置、Shopify 菜单、布局组件），而不是页面区块。
8. 占位内容。 设计师会留下灰色方框、标价为 $00.00 的示例商品卡片、画布外的零散标签。在清单中将其标记为 MISSING/占位内容，并将该区块映射到真实数据（商品集合、Instagram 信息流），而不是复刻占位内容。

插件备用方案

如果 MCP 无法访问文件或无法导出特定资源（例如扁平化图层组、特殊导出设置），则改用 Figma Agent 插件导出，并读取其输出文件。MCP 是首选路径；仅在弥补具体缺失时使用插件，并在清单中注明哪些资源来自备用方案。

工作流

1. 预检（见上文）。阅读 .guides/brand-guideline.md；确保 sections.md 是最新的。
2. 提取设计（见上文步骤）。将规范和清单保存为 .figma/<brand>-<page>.md（令牌表、标注表、内容清单、缺漏项）。趁节点 ID 还在手边，将每个区块框架的 Figma 截图保存到 .figma/ref/<page>/<block>.png（get_screenshot → curl；这些 URL 有效期很短）。这些截图将用作视觉检查参考。
3. 构建内容清单——列和规则与克隆技能相同。
4. 生成克隆预览路由：app/routes/clone-preview.$page.tsx——每个页面对应一个 $page 分支，使用 React + Tailwind、真实 Figma 资源和 {/* === BLOCK NAME === */} 标记。页眉和页脚不属于预览内容。
5. 用户审批检查点——停止并等待。 提供预览 URL（使用 npm run dev 打印的开发服务器端口，不要猜测端口）和区块数量、品牌覆盖项、缺漏项。反复调整，直到用户批准。
6. 批准后立即将资源移至 Shopify。 裁剪出响应式变体（桌面端／移动端），并按照设计翻转／旋转，然后通过 weaverse-content-api → upload 上传。将返回的媒体对象保存在 .clone/<page>/shopify-assets.json。绝不要发布 Figma 资源 URL。
7. 拆分并匹配。 对每个区块进行分类（媒体类型、构成、布局机制、交互），并按照克隆技能的优先级进行匹配和深入的结构验证。还要根据预检得出的页面类型检查每个候选项的 enabledOn。
   • 并行审计：每个候选区块安排一名只读侦察员，按要求逐项报告 SUPPORTED/GAP，并注明文件和行号。
   • 然后每个区块安排一名实施者，所有人遵循同一约定：每个新增设置的默认值必须保持当前渲染效果；不得编辑注册表、sections.md 或任务范围外的共享文件；不得运行构建或格式化命令；集成者负责注册、文档、lint 和构建。
   • 优先使用小型共享区块（例如标题 + 链接页眉），而不是手动将相同页眉添加到多个区块中。
8. 集成。 注册新区块，更新 sections.md，仅对更改的文件运行格式化程序，进行类型检查并与更改前的错误基线进行比较，按照 CI 的方式构建。
9. 使用 generating-weaverse-project-json 生成页面 JSON（使用 Shopify 媒体对象，不写入默认值，明确写入预设），并验证 JSON。
10. 通过 Content API 交付（weaverse-content-api）：对 CUSTOM／模板页面调用 create-page（INDEX 页面已存在），然后通过一次 PATCH 重新关联根 main 并创建所有项目。全站值通过 theme-update 更新（先备份旧值）；菜单通过管理代理（menuUpdate）更新（先备份旧菜单）。如果页面需要尚未部署的代码，请立即部署（或告知用户，在此之前线上页面无法正常使用）。
11. 使用 Playwright 在真实路由上验证——循环直到 PASS。 编写 .figma/<page>.visual.json（每个区块对应一个区段：[data-wv-id] 选择器 + 参考图像；对数据驱动或占位区块使用 mode: "structure"，并且仅在这些区块中添加 note），然后从店面仓库运行 node <this skill>/scripts/visual_check.mjs .figma/<page>.visual.json。规范格式、设置方法和修复指南见 references/visual-check.md。
    • 阅读 report.md；对每个 ❌，打开区块截图、参考图像和 .diff.png，修复一个原因（通过 Content API 调整区块设置，或修改区块代码），然后使用 --only <block> 重新运行。重复此过程，直到完整运行在桌面端和移动端均显示 Result: PASS。
    • 绝不要通过提高阈值或将区块切换为 structure 来掩盖真实的设计差异。
    • 如果某区块连续三次迭代毫无进展，或需要你没有的决策／资源，则将差异图提交给用户，并升级处理。
    • 脚本会检查 JS 错误、损坏的图片、溢出、H1 数量、区块顺序和被裁切的圆角元素。仍需手动测试交互：悬停效果、筛选器会更改 URL 和结果数量、排序、加载更多、菜单链接可正常跳转；应从渲染后的 DOM 中统计商品数量，而非从 loader JSON 中统计。
    • 部署后，使用相同规范对已部署的 URL 重新运行检查（--url https://<storefront>/<path>）。
12. 清理并交接。 移除该页面的预览分支，提交（包含视觉规范和参考图像；生成的 .figma/visual/ 输出可以保持未跟踪状态），推送，然后监控此店面自身的部署工作流（同一仓库中的其他品牌工作流可能因无关原因失败）。报告最终视觉检查结果、已接受的例外，以及 Studio 仍需处理的事项（页面 SEO、缺失的集合／链接、尚未发布的资源）。

Figma 与网站克隆的具体差异

方面	网站（Firecrawl）	Figma（MCP）
设计令牌	从 CSS／计算样式推断	通过 get_variable_defs 显式提供 — 直接映射到主题
区块边界	HTML 区块标记、滑块／网格类	来自 get_metadata 的顶层画板／自动布局容器
组合方式	从 HTML 定位信息读取	从自动布局方向／换行／间距读取
资源	HTML 中的图片／视频 URL	通过 download_assets 导出；没有真实的视频 src
交互	HTML 中的实际运行时行为	运行时没有交互 — 根据画板名称、原型链接、设计师备注推断；不要臆造设计中没有暗示的交互
响应式变体	<picture>／断点类	如果设计师创建了桌面／移动端画板，则分别使用；否则使用一个画板

注意事项

• 跳过审批检查点 — 与网站克隆规则相同：用户必须先批准克隆预览，然后才能拆分区块。
• 臆造交互 — 除非原型或备注有说明，否则静态 Figma 画板没有轮播自动播放或滚动行为。不要仅因画板显示多张卡片就将其归类为滑块。请通过原型链接或画板名称确认。
• 忽略 Figma 变量 — get_variable_defs 是你能获得的最直接的令牌来源。如果有变量却仍将颜色／尺寸硬编码，就浪费了 Figma 的主要优势。
• 猜测资源 URL — 使用 download_assets 导出真实资源；如果导出失败，请在清单中标记 MISSING — [describe]，不要用占位符替代。
• 每个画板都做成一个庞大的专属区块 — 应拆分为可复用区块；优先复用注册表中的区块。
• 重新推导匹配规则 — 区块匹配优先级和深层架构验证已在 cloning-websites-to-weaverse 中说明。请遵循这些规则，不要自行重新制定宽松版本。
• 将移动端／桌面端画板视为两个页面 — 它们是同一区块的响应式变体；应映射到 imageMobile／imageDesktop 或断点逻辑，而不是拆成两个页面。
• 将预览路由留在代码库中 — Weaverse 页面验证通过后应将其删除。
• 未询问页面类型就开始构建 — 曾有页面最初按 COLLECTION 模板构建，后来必须改为 CUSTOM 页面；产品网格区块也必须更换，因为仅适用于集合的区块无法在其他页面运行。
• 使用错误的店面调试数据 .env — “找不到集合”可能只是因为本地令牌属于另一个品牌的渠道。请先检查预检第 2 项，再判断是否为发布问题。
• 将 Figma 资源 URL 传给 Weaverse — 这些 URL 会在几天内过期，部分图片转换也会阻止其访问。请先上传到 Shopify。
• 遗漏注释 — 设计师关于标题级别、链接目标、菜单和悬停行为的备注都是要求；请保留注释表，并在最后逐项勾选。
• 复现设计师的占位内容 — 灰色方框和示例卡片只是实际数据的替代物，并非内容。
• 根据过期的开发服务器判断成功 — 执行 PATCH 后，请重启 npm run dev；旧进程可能会在相同 ID 下继续提供之前的数据。
• 未通过 PASS 视觉检查就宣布页面完成 — 仅凭截图目测会漏掉卡片角被裁切的问题，而检查结果会报告 no clipped rounded elements ❌。请运行检查循环，直到桌面端和移动端都通过。
• 放宽检查而不是修复页面 — 提高 threshold、删除区块或将其标记为 structure，都不能让实际差异消失。

相关技能

• cloning-websites-to-weaverse — 网站输入适配器；负责管理此技能复用的共享版块匹配、清单和预览规则。
• generating-weaverse-project-json — 下游技能；将此技能的规范、清单和令牌表转换为可直接导入的 JSON。
• weaverse-content-api — 导入后，将内容推送到实时项目或更新其中的内容。
• figma-use / figma-generate-design — Figma MCP 插件技能；在进行任何 use_figma 写入调用之前，先加载 figma-use。