frontend-to-xd-fast

把前端页面渲染成场景数据，再生成 Adobe XD 可打开、可编辑的 .xd 文件。默认面向移动端 H5（375px 宽），也支持改 viewport。

这个 skill 产出什么

输出目录（默认 ./XD设计稿）：

• 项目名-UI设计稿-可滚动原型版.xd —— 主交付文件（每次必须生成），带原生视口线、固定底栏和点击跳转
• 项目名-UI设计稿.xd —— 静态整页参考版，只用于看整页设计，不作为手机预览交付
• _build/scenes/*.json —— 页面场景数据，修复 skill 用它定位到具体图层
• _build/screens/*.png —— 浏览器逐页截图，用于对照和像素校验
• _build/build-report.json —— 画板数、图层数、警告
• _build/prototype-report.json —— 原型版画板数、视口高度、固定节点、交互数、警告
• _build/qa-report.json —— 结构校验 + 逐页像素差异
• _build/pages.resolved.json —— 本次运行的完整配置（绝对路径）

不要把 _build/ 当成交付物发给用户；它是修复 skill 的原料。

前置条件与环境准备

浏览器（Edge 优先）

• Windows，默认自动探测系统 Microsoft Edge：pages.json 的 chromePath（浏览器可执行文件路径）留空时，依次查找
  C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe（Edge 32 位安装路径）和
  C:\Program Files\Microsoft\Edge\Application\msedge.exe（Edge 64 位安装路径）。
• chromePath 也可以显式指向 msedge.exe 或 Chrome for Testing（CFT，免安装的 Chrome 测试版）的 chrome.exe，优先级最高。
• Edge 不存在或启动失败时，用 CFT 兜底：运行 python <skill目录>/scripts/fetch_chrome_for_testing.py 下载到
  %LOCALAPPDATA%\chrome-for-testing\chrome-win64\（Windows 当前用户本地应用数据目录）；先加 --check
  只查看 Stable（稳定版）版本号和 win64 下载地址，不下载。
• 浏览器本体不预装、不随技能分发；启动时使用 headless（无头模式）和 Playwright 临时 profile（临时用户配置目录），不读取用户日常 Edge 配置。

Python

• 建议 Python 3.10+；低于该版本只提示，不硬拦。
• 依赖：Pillow、fonttools。不随技能分发；首次运行 run_fast.py 时由 scripts/ensure_deps.py
  自动检测并联网安装（缺失才装，已装则跳过），镜像回退顺序与下面一致。也可手动装：
  python -m pip install -r <skill目录>/scripts/requirements.txt -i <镜像地址>。
• PyPI 镜像：清华主用 https://pypi.tuna.tsinghua.edu.cn/simple，阿里云备用
  https://mirrors.aliyun.com/pypi/simple/，都失败再用官方 https://pypi.org/simple；只在安装命令里加 -i，不执行 pip config set 改全局配置。
• 离线说明：依赖安装后缓存在本机，之后离线可正常用。纯离线机器需先在有网环境跑一次
  run_fast.py（或手动 pip install Pillow fonttools）把依赖装好。

Node

• Node.js 18+：playwright-core 自身 engines 的硬要求；技能文档只提示、不额外硬拦，但低于 18 时依赖会退出。
• 依赖（playwright-core、xd2svg）不随技能分发；首次运行 run_fast.py 时由 scripts/ensure_deps.py
  自动检测 <skill目录>/scripts/node_modules，缺失则联网 npm install（走国内镜像），已装则跳过。
  也可手动在 scripts/ 目录执行 npm install。
• 离线说明：npm install 把依赖装到本地 scripts/node_modules，之后离线可正常用。纯离线机器需先在有网环境跑一次。

Adobe XD

• Adobe XD 45 使用 modern 清单，已实测
• XD 40 / 2021–2022 使用 legacy 最小清单，未实测；默认 manifestProfile: "both" 同时产出两份，报告里必须标注“legacy 未验证”

工作流

1. 先摸清前端

在生成之前确认这些事实，不要猜：

• 页面清单：每个 HTML 文件、详情页需要的 ?id=、居民端/工作人员端角色
• 登录态：是 localStorage、cookie，还是项目自带的 _session.html?role=...&target=...
• 前端 API 地址：如果前端硬编码了 http://127.0.0.1:5000，而本次服务跑在别的端口，用 apiRewrite 重写，不要改前端源码
• 图标：iconCss（如 css/mui.min.css）、iconFont（如 fonts/mui.ttf）、iconPrefix（如 mui-icon-）
• 固定底栏/操作条/悬浮按钮：选择器写进 fixedElements
• 页面根节点：通常是 .app，写进 rootSelector

2. 写 pages.json

复制 assets/pages.example.json，按项目实际情况修改。字段说明见 references/pages-schema.md。

关键点：

• pages[].name 是画板名，必须是中文、唯一
• pages[].path 可以是相对路径，也可以是完整 URL
• 详情页必须显式写 ?id=，不要依赖自动爬链接
• viewportLine 默认开启，y 默认 812；只有高度超过 y 的页面才画线
• run_fast.py 会强制把 prototype.enabled 设为 true，可滚动原型版始终生成；在 pages.json 里配置 prototype 用于设置视口高度、固定元素和点击跳转，字段见 references/pages-schema.md
• prototype.fixedElements 默认固定 header.app-bar（顶部）、nav.tabbar / div.action-bar / a.fab（底部）
• prototype.tabBars 配底部导航热区；prototype.listLinks / buttonLinks 配列表项和按钮跳转
• sessionTemplate 只在项目使用 _session.html 模式时填写；否则用 session.localStorage / cookie / initScript

3. 运行

python <skill目录>/scripts/run_fast.py pages.json

只想生成、不做像素校验：

python <skill目录>/scripts/run_fast.py pages.json --skip-qa

流水线会自动：

1. 从 iconCss 提取图标码点，写入 _build/icon_map.json
2. 按需启动 server.startCommand
3. 用 Playwright 逐页渲染、抓场景、截整页图
4. 生成静态 .xd
5. 始终生成 -可滚动原型版.xd（run_fast.py 会强制把 prototype.enabled 设为 true，带视口线、固定元素、点击交互）
6. 校验静态版结构 + 逐页像素差异

4. 读报告

• build-report.json.warnings 非空：先处理警告（图标缺失、场景缺失、预览失败）
• qa-report.json.status == "warn"：看 pixel 数组里 pct30 最高的页面，优先人工检查
• pct30 是“色阶差 >30 的像素占比”，不是文字差异率；字体抗锯齿、阴影边缘会产生 1–3% 的正常差异

5. 可滚动原型版（每次必须生成，最终交付以此为准）

快速 skill 的默认和最终交付都是可滚动原型版；不要用手绘视图线冒充。静态版只作为整页设计参考。

配置 pages.json：

"prototype": {
  "enabled": true,
  "viewportHeight": 812,
  "homePage": "首页",
  "fixedElements": [
    { "selector": "header.app-bar", "anchor": "top" },
    { "selector": "nav.tabbar", "anchor": "bottom" },
    { "selector": "div.action-bar", "anchor": "bottom" },
    { "selector": "a.fab", "anchor": "bottom" }
  ],
  "tabBars": [
    {
      "pages": ["首页", "公告列表", "社区活动", "我的诉求", "我的"],
      "selector": "nav.tabbar",
      "columns": 4,
      "items": [
        { "label": "首页", "target": "首页" },
        { "label": "活动", "target": "社区活动" },
        { "label": "诉求", "target": "我的诉求" },
        { "label": "我的", "target": "我的" }
      ]
    }
  ],
  "listLinks": [
    { "pages": ["公告列表"], "selector": "a.list-item", "target": "公告详情" }
  ],
  "buttonLinks": [
    { "pages": ["登录"], "selector": "button.btn.btn-primary", "target": "首页" }
  ]
}

生成后检查：

• XD 里选中长画板，右侧应显示 滚动 = 垂直、视口高度 = 配置值（示例 812）；
• 视口线在配置的视口高度处（示例 812px），线上不应有“首屏 812px”手绘文字；
• 预览窗口应是 375×视口高度 的手机视口，不是整张长画板缩放；
• 滚动时顶栏/底栏固定，点击底部导航和列表项能跳转。

灵活性要求（不同项目必须按实际配置，不要写死）：

• viewportHeight 不是固定 812：iPhone X 是 812，iPhone 14 是 844，Plus 是 896，
  安卓常见 800 / 915 等；以项目 viewport.height 或 prototype.viewportHeight 为准。
• 视口线位置 = 屏幕高度，不是导航栏高度。导航栏更高时，固定底栏的顶边会自动上移，
  底边仍贴屏幕底部；构建脚本用场景里元素的真实高度计算，不写死导航栏高度。
• 同一项目里有不同尺寸画板时，在 pages[].viewportHeight 单独覆盖。
• tabBars[].columns / items 按实际导航项数量和顺序配置；不同项目导航项不一样就改这里。
• fixedElements 选择器按项目实际类名配置；顶部栏、底部栏、操作条、悬浮按钮都可以加。
• listLinks / buttonLinks 的 target 必须和 pages[].name 完全一致。

如果预览窗口显示整张画板，先确认打开的是 -可滚动原型版.xd，不是静态版；再看预览窗口是否被拉成“适合窗口”大小。

6. 让用户复查（必须做）

生成完成后，按下面清单主动问用户，不要只说“已完成”：

请打开 XD 检查，重点看：
1. 视图线（默认 812px）是不是太高/太低？
2. 页面高度对不对？有没有页面明显偏矮/偏高、底部内容被截断？
3. 长标题、列表、textarea 有没有文字溢出或错位？
4. 字体、图标、卡片阴影、渐变是否正常？
5. 有没有缺页、缺按钮、缺图标？
6. 画板位置和命名是否方便查找？
7. 如果用了可滚动原型版：选中长画板时是否显示“滚动 = 垂直、视口高度 = 配置值”？
8. 预览时内容是否滚动，顶部标题栏/底部导航是否固定，点击导航和列表是否跳转？
有问题请按“页面名 + 现象 + 期望效果”告诉我。

用户报告问题后，调用 xd-artifact-repair skill，不要自己直接改 .xd 二进制。

硬性规则

• 每次输出到新目录；不要覆盖已有 .xd。
• 不要为了让 QA 通过而修改浏览器截图；以真实前端渲染为准。
• 文字按“视觉行”拆成文本层，保证位置准确；不要合并成无法控制换行的整段。
• 图标从字体转成矢量路径；如果图标字体缺失，报告警告，不要静默丢弃。
• 固定底栏、底部操作条、悬浮按钮在静态版里要贴整页画板底部，不能停在首屏 812px 处。
• 静态版的视图线是可见图层，命名 视图线 812px，放在画板最上层；短页面不画。
• 用户的“视图线太高/太低”对应 viewportLine.y；不要改页面内容来迁就视图线。
• 可滚动原型版不要画手绘视图线：设置 viewportHeight 让 XD 自己画原生视口线。
  原生线有拖拽手柄、没有“首屏 812px”文字；如果看到“首屏 812px”，说明打开的是静态版。
• 可滚动原型版的固定元素要上移到视口底部（底部元素）或视口顶部（顶部元素），并打
  meta.ux.fixed: true；不要把它们留在整页画板底部，否则预览时会在屏幕外。
• 可滚动原型版只生成 modern 格式；legacy 兼容版仍是静态版。
• 始终生成可滚动原型版（run_fast.py 强制开启）；即使用户没有特别说明，也要把 -可滚动原型版.xd 作为最终交付文件，并在总结里先列它。

参考文件

• references/pages-schema.md —— pages.json 全字段（含 prototype 可滚动原型配置）
• references/review-checklist.md —— 交付前复查清单
• references/troubleshooting.md —— 常见失败和处理
• references/triggers.md —— 触发词和同义说法
• assets/pages.example.json —— 完整示例
• assets/prototype.example.json —— 可滚动原型版 prototype 配置示例

兼容性口径

• Adobe XD 45.0.62.17：已实测
• XD 40 / 2021–2022：使用 AGC 1.5 + 最小 manifest 的 legacy 基线，未实测；报告里写“未验证”，不要写“已兼容”
• 如果用户提供了旧版安装包或测试机，再用 xd-artifact-repair 的兼容检查补测
• 默认输出两个文件：项目名-UI设计稿.xd（modern，XD45 实测）和 项目名-UI设计稿-legacy兼容版.xd（旧版兼容基线，未实测）
• 可滚动原型版额外输出 项目名-UI设计稿-可滚动原型版.xd（仅 modern）。XD 45.0.62.17 已实测：
  画板属性显示“滚动 = 垂直、视口高度 = 配置值”，视口线在配置高度处，预览窗口为手机视口；
  滚动/点击手感按 references/review-checklist.md 人工确认