screenshot-to-html

screenshot-to-html — 将截图转换为高保真 HTML

将 UI 图像转换为整洁、自包含的 HTML 页面，使其渲染结果与目标图像一致。使用用户的语言回复（他们通常会用中文）；聊天回复保持简短，让实际工作在文件中完成。

核心原则：复现渲染状态，而非计算状态

目标图像是最终渲染像素的真实依据。复现图像，而不是机械地转录每个元素的数值。

• 克隆计算状态（不要这样做）。 用吸管提取每个十六进制颜色值、“测量”像素坐标和尺寸，再把类似 getComputedStyle 的数值粘贴到绝对定位的 div 中。结果就是一堆魔法数字：缺乏语义、无法响应式适配、脆弱不堪，而且微小的提取误差会不断累积，让效果更差。
• 克隆渲染状态（要这样做）。 像开发者一样解读设计：推断语义结构、一小组设计令牌（调色板、字体阶梯、间距节奏、圆角、阴影）和布局意图（flex/grid）。构建页面，然后渲染代码、截图并与目标图像比较，再迭代优化。目标是“我的渲染效果是否与目标一致”，即：render(code) ≈ target。

因此，这套工作流是一个反馈循环，而不是一次性输出。

工作流

复制此检查清单并跟踪进度：

- [ ] Phase 0 — Setup (inputs, stack, target width, deps, assets)
- [ ] Phase 1 — Read the design (global -> components -> exact text)
- [ ] Phase 2 — Build the first draft (semantic + tokens, self-contained)
- [ ] Phase 3 — Rendered-state loop (render, compare, fix; repeat 2-4x)
- [ ] Phase 4 — Interactivity & states (affordances + behavior, then verify)
- [ ] Phase 5 — Final checks
- [ ] Phase 6 — Enhance with motion (optional)

阶段 0 — 设置

• 确认输入：目标图像路径和所需的输出文件路径。
• 素材会自动处理（默认不提问）。 为每个位置选择能带来最清晰、最忠实效果的素材——不要“一律裁剪”：优先使用用户提供的素材；真实 Logo 使用内嵌 SVG / 官方文件；当源图中相应区域足够清晰时，裁剪源图中的特定独有内容 （scripts/crop.mjs）；通用照片使用 Unsplash / picsum；最后才使用 https://placehold.co 色块。质量标准：绝不交付模糊的放大裁剪图——用清晰的图库照片替换模糊的裁剪图。只有当素材对品牌至关重要，且没有任何方案可以近似还原时，才询问一次（不阻塞进度）。参见 reference.md 中的 Images & assets。
• 选择技术栈（只有不明确时才询问）：vanilla（HTML + 纯 CSS，自包含，默认）或 tailwind（HTML + Tailwind CDN）。参见 Stacks。
• 先了解画布和缩放比例，再编写任何 CSS。 读取像素尺寸（sips -g pixelWidth -g pixelHeight <image>），然后确定 CSS 像素下的设计宽度，而不是直接采用原始像素数：
  • 截图通常采用 Retina 分辨率（@2x/@3x），因此文件宽度是 CSS 宽度的 2–3 倍。不要直接除以倍数并按所得尺寸构建页面——这样会生成缩小的页面，导航栏文字只有 ~10px，在 100% 缩放下会显得很小。应映射到实际断点：网页 -> 1280 或 1440；移动设备 -> 375/390/393。
  • 按此宽度构建，使用实际场景中的字体尺寸（主视觉区域约为 48–72px，正文约为 16–18px），并保持响应式/流式布局（clamp()、max-width、%），确保页面以正常尺寸打开并能自适应——绝不要固定为迷你尺寸。
  • 在此设计宽度下运行渲染/比较循环；--scale 2 只会让差异图更清晰，并不意味着“按一半尺寸编写页面”。
• 仅需确保一次渲染依赖（无需下载浏览器）：npm i -D playwright-core。

阶段 1 — 阅读设计（先整体，再局部）

仔细查看图片并编写简短的构建规范。先整体，再局部：

• 布局：页面最大宽度、分栏网格、区块顺序、对齐方式。
• 颜色令牌：列出 4-8 种颜色（背景、表面、文字、次要文字、品牌色、强调色、分隔线）。 考虑渐变、叠加层和不透明度——不要只看单个像素。
• 字体：字体族（衬线体还是无衬线体、几何风格还是人文风格 -> 最接近的 Google Font）， 标题到正文的字号比例、字重、字间距、行高。
• 间距节奏（以 4/8 px 为基准）、边框圆角、阴影深度、边框/分隔线。
• 组件：导航、主视觉、特性区/便当盒布局、统计数据、卡片、用户评价、行动号召、页脚 — 注意结构和重复方式（构建一个组件，再循环处理数据）。
• 内容：逐字转录可见文本（不要编造或翻译）。

不要记录像素坐标。记录关系和令牌。 完整评分标准请参阅 reference.md。

阶段 2 — 构建初稿

• 使用一个自包含文件（内嵌 <style>，仅在必要时使用少量内嵌 JS）。
• 使用语义化 HTML（header/nav/main/section/article/footer，标题按顺序排列）。
• 在 :root CSS 变量中定义令牌；使用 flex/grid 构建布局，并采用流式尺寸（clamp、min()），不要使用固定像素框架。
• 使用图片中的原文。
• 图片：为每个位置选择最合适的图层（参见阶段 0）——如果源图中的特定内容清晰，裁剪独特的具体内容（node scripts/crop.mjs --in <target> --rect x,y,w,h --out assets/<name>.png）；通用图片素材使用清晰的 Unsplash/picsum 照片（模糊的裁剪效果不如真实照片）；否则使用 https://placehold.co/<w>x<h>，并附上 `` 注释。图标：使用内嵌 SVG（避免用表情符号充当图标）。
• 先匹配图片所示的断点；再添加合理的响应式行为，不要臆造看不到的布局。

阶段 3 — 渲染状态循环（重要环节）

1. 将初稿渲染为截图：

   node scripts/shot.mjs \
     --in <output.html> --out tmp/screenshot-to-html/v1.png --width <DESIGN_WIDTH>
   

2. 同时查看目标图片和渲染结果。逐个区域进行比较，并按优先级列出具体差异：布局/结构 > 尺寸/间距 > 颜色/对比度 > 排版 > 润色（阴影、圆角、渐变）。
3. 通过语义化修改修复最重要的问题（调整令牌/布局，而非随意设置数值）。重新渲染为 v2.png、v3.png……
4. 重复上述步骤，直到差异仅剩外观细节（通常需要 2-4 轮）。每轮都必须缩小视觉差距；如果修改导致效果变差，就撤销。

比较技巧和常见错觉请参阅 reference.md。

阶段 4 — 交互与状态（让它成为网页，而不是图片）

截图只是一个静止画面，无法展示悬停、焦点或哪些内容可以点击。只匹配截图，交付的只会是“一张暗中伪装成网页的图片”。让复刻页面像真正的网页一样运行：

• 真实元素。 所有看起来可以点击的内容都使用 <button> 或 <a href>（或 role="button" + tabindex="0"），绝不能使用无交互功能的 <div>/<span>；输入控件必须是真正的 <input>。
• 默认提供交互提示（始终如此）。 每个控件都要设置 cursor: pointer、可见的 :hover 状态变化、:focus-visible 焦点环（键盘）和 :active 按压效果，并添加较短的 transition（约 120-180ms）。这些不会改变静止状态的外观，只会增加反馈。
• 按图片所暗示的实现功能行为（最少量的内联 JS）：标签页/分段控件切换可见面板；多屏移动应用在设备边框内导航（底部导航/卡片切换屏幕）；模态框/菜单/下拉列表/折叠面板可以打开和关闭（按 Esc 键或点击背景关闭）；页面内导航平滑滚动。不要凭空设计无法推断的流程。
• 无障碍与动效。 标题层级合理，提供 alt 文本，焦点清晰可见，对比度适宜；遵循 prefers-reduced-motion。
• 验证，而非假设： node scripts/shot.mjs --in <file> --verify 会标记看起来可点击但没有交互功能或缺少悬停/焦点状态的元素；--states 会捕获悬停/焦点/打开状态的画面。修复所有无效控件。完整详情见 reference.md。
• 触感层次（零依赖）。 对截图所暗示的控件——可滑动图库、滑块、弹出的爱心、拖动吸附卡组——使用纯 JS + CSS（指针拖动、速度吸附、按压/缩放），让它们像手工打造的一样。这些效果都不需要动效库。模式和可直接复制的代码片段见 references/interaction.md。

阶段 5 — 最终检查

• 并排对比渲染结果与目标，观感应当是“同一个页面”。
• 文本准确；颜色/对比度正确；字号比例和字重匹配。
• 响应式检查：在第二种宽度下渲染（例如 --width 390），确保没有重叠或溢出。
• 交互： 所有看起来可点击的元素都是真实控件，并显示悬停/焦点状态；--verify 检查通过。
• 内容自包含且有效；不要遗留探测/临时文件（交付内容中不要包含 tmp/screenshot-to-html/）。报告最终文件路径和最终渲染结果。

阶段 6 — 添加动效（可选，仅按要求执行）

交互（阶段 4）默认包含在交付中；GSAP 动效/动画则不包含。 丰富的触感反馈——拖动、吸附、点赞弹跳——不需要任何库（references/interaction.md）； GSAP 仅用于更复杂且明确要求的动画编排。不要自行添加动效，也不要询问是否需要——只有用户明确要求动画（“加动效”、 “make it animated”）时才添加。此时添加克制的 GSAP 动画——聚焦影响力大的瞬间， 不要到处堆砌 AI 式动效。阅读 references/animation.md，了解 相关模式（加载时交错动画、滚动触发显现、悬停微交互）、 CDN 设置和注意事项。保持 HTML 自包含（通过 CDN 引入 GSAP），并遵循 prefers-reduced-motion；使用 node scripts/shot.mjs --motion 验证动画稳定后的画面。 此技能可独立使用；如需更深入的动画编排，也可以选择安装官方 GSAP skills （npx skills add github.com/greensock/gsap-skills），但并非必需。

脚本（路径相对于此技能目录）

scripts/shot.mjs — 使用 playwright-core 和已安装的 Google Chrome 渲染本地 HTML 文件 （无需下载浏览器）；用于工作流程中的渲染步骤。

# full-page (default), crisp 2x:
node scripts/shot.mjs --in replica.html --out tmp/screenshot-to-html/v1.png --width 1280
# exact-pixel overlay: add --scale 1 ; above-the-fold only: --viewport-only ; keep motion: --motion

如果缺少 Chrome，则回退到捆绑的 chromium（npx playwright install chromium）。

scripts/crop.mjs — 从源截图中裁剪矩形区域，以便重复使用真实图像素材（素材层 2）。如果已安装 sharp，则使用它；否则使用 macOS sips。

node scripts/crop.mjs --in <target.png> --rect x,y,w,h --out assets/hero.png

技术栈

按需选择；两者都会生成一个独立的单文件。

vanilla（默认）——在一个文件中使用 HTML + 纯 CSS。令牌放在 :root 中。最适合还原定制的视觉风格，同时不引入依赖。

tailwind——添加 <script src="https://cdn.tailwindcss.com"></script>，并使用实用类构建；通过内联的 tailwind.config 对象映射调色板和比例。

两种技术栈都支持：

• 字体：使用 Google Fonts <link>（选择与图片最接近的字体）。
• 图标：使用内联 SVG，或 Font Awesome https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css。
• 缺失的图片：采用分层回退方案（从源图中裁剪 -> Unsplash/picsum -> placehold.co）。

输出与临时文件约定

• 最终 HTML：使用用户指定的路径。默认是 index.html；如果该路径下已存在无关文件，请勿覆盖——先确认，或写入 replica.html。
• 截图/中间文件：tmp/screenshot-to-html/（可安全删除）。如果目录不存在，请创建。

质量要求

• 语义清晰、易读、易维护；优先使用设计令牌，而非随意设置数值。
• 不要把所有元素都用绝对定位布局；不要使用“测量得出的”像素坐标。
• 忠实还原图片：布局、准确文本、颜色、字体、间距、圆角、阴影。
• 多张截图 = 多个页面/标签：合理地将它们链接起来或搭建相应结构。

附加资源

• reference.md — 分析评分标准、比较方法、计算状态陷阱、字体/颜色/资源、四层资源策略。
• references/interaction.md — 零依赖的触感优化标准（第 4 阶段）：指针拖动原语、滑动/轮播吸附、点赞弹跳、切换控件、减少动态效果。
• references/animation.md — 可选的 GSAP 动效模式（第 6 阶段）：CDN 设置、加载/滚动/悬停方案、减少动态效果、注意事项。