screenshot-to-code

截图转代码

将截图视为视觉证据，而不只是灵感来源。在保持实现响应式、无障碍且易于维护的同时，复现其设计语言和可见行为。

执行标准

分五个阶段推进，并设置阶段门槛。不要从查看截图直接跳到润色 CSS：

1. 探索 — 了解截图、代码仓库、目标路由、可用资源和运行时环境。
2. 明确规范 — 将视觉证据转化为布局、设计令牌、组件、内容、状态和响应式决策。
3. 构建 — 先搭建语义结构并确保整体几何尺寸正确，再进行精细样式设计。
4. 对比 — 在受控视口中渲染页面，并根据参考图测量差异。
5. 优化 — 修复影响最大的差异，重新截取页面并重复此过程，直到通过完成门槛。

优先保证视觉还原度，而非个人设计偏好；优先保证工程质量，而非只针对截图进行修补。优秀的结果必须兼顾两者。

从上下文着手

1. 以完整分辨率打开并检查每张附加截图。记录其像素尺寸、方向、可见的浏览器／设备界面、裁切范围、内容密度以及可能的 CSS 视口尺寸。
2. 编写代码前先检查代码仓库。找出所用框架、路由、样式方案、组件库、设计令牌、字体、资源、断点、测试工具，以及正确的页面或组件入口。
3. 如果存在匹配的实现，应先渲染并逐步改进。保留现有架构和可正常工作的行为。
4. 如果从头开始，请使用用户指定的技术栈。否则优先使用代码仓库现有的技术栈；不要为了方便而替换它。
5. 仅在无法安全推断且会实质性影响结果时，才询问用户，例如关键资源无法辨认或目标路由未知。

修改现有应用、选择组件边界或实现多个页面之前，请先阅读 references/project-and-architecture.md。

合理判断目标视口

对每张截图，判断其主要属于桌面网页、平板还是移动设备参考图。应根据完整的视觉证据判断，而非仅依据文件名或原始像素宽度。

• 宽屏导航、多列布局、固定侧边栏、以悬停为主的控件和宽阔的内容边距，均表明目标可能是桌面端。
• 中等宽度的布局、适合触控的控件、减少的列数以及部分折叠的导航，均表明目标可能是平板端。
• 狭窄的单列流程、紧凑或底部导航、纵向堆叠的操作项、铺满屏幕边缘的内容以及触控优先的控件，均表明目标可能是移动端。
• 应考虑 Retina／设备像素缩放、浏览器缩放、图像调整大小、裁切，以及嵌入更大画布的截图。图像像素尺寸不一定等于 CSS 像素尺寸。
• 如果证据相互矛盾，应选择最能解释布局行为的设备类型，并说明这一假设。只有当选择会实质性改变所需结果，且无法负责任地推断时，才询问用户。

使用推断出的设备类型来选择初始实现和对比视口。桌面截图应按桌面网页重建和检查，平板截图应按平板重建和检查，移动设备截图应按移动设备重建和检查。同时还应确保页面在参考视口之外也能响应式适配，而非只针对某一种固定尺寸构建。

构建视觉规范

实施之前，先提取以下信息：

• 页面区域、阅读顺序、网格、对齐方式、宽度、间距和垂直节奏
• 字体系列、字重、相对字号、行高、字距、换行方式和层级
• 颜色、渐变、边框、圆角、阴影、不透明度和表面之间的关系
• 图像裁切、宽高比、图标、插画和装饰层
• 重复组件、变体、状态和内容模式
• 可见控件及可能的交互
• 固定、粘性、重叠、裁切或受滚动驱动的元素
• 所提供视口图像中响应式行为的证据

区分观察结果与推测。记录不确定的细节，并选择能够解释截图的最小一致规则集。阅读 references/visual-analysis.md，了解提取方法。

在大量编码之前，先创建一份简短的重建规范：

• 目标路由/组件，以及每张截图对应的参考视口
• 完整的可见内容和所需资源
• 共享外壳和重复组件
• 主要布局与排版规则
• 有证据支持的响应式变化
• 需要实现的交互/状态
• 可能影响还原度的未解决假设

将这些内容保留在工作笔记中，除非用户要求，否则不要添加到项目文档里。

忠实实现

1. 为颜色、字体、间距、圆角、阴影、容器宽度和断点建立共享设计令牌。
2. 先构建语义结构，再处理装饰细节。标题、导航、按钮、表单、列表和表格应使用真实元素。
3. 为确实重复的模式创建组件；既不要把所有内容塞进一个超大组件，也不要进行不必要的抽象。
4. 先匹配整体几何关系：页面宽度、区域高度、网格、对齐方式和主要间距。然后再调整排版、组件和细节。
5. 使用 CSS 布局系统，而不是硬编码截图坐标。仅将绝对定位用于真正的叠加层和艺术元素。
6. 如果文案清晰可读，就原样保留可见文案。截图未提供营销文案时，不要自行编造。
7. 实现可见交互和实用状态：在截图有暗示时，实现悬停、焦点、激活、展开、选中、禁用、加载和错误状态。
8. 将数据驱动的重复内容放在数组或项目数据源中，而不是重复编写标记。

采用恰当的还原方式：

• 对需要重新排布的内容使用正常文档流。
• 对可见的行列对齐使用网格布局。
• 对单向对齐和分布使用 Flexbox。
• 对真正的叠加层、徽章、悬浮艺术元素和刻意分层的构图使用绝对定位。
• 使用伪元素实现简单装饰，不要用它承载有意义的内容。
• 仅在能清晰复现简单几何形状时使用 SVG/CSS 图形；复杂艺术图形应使用真实资源。
• 如果截图表明尺寸需要插值，就使用流式或设有上限的尺寸；不要将整个页面尺寸固定为单一画布大小。

不要把原始设计改造成通用模板。除非有证据支持或用户提出要求，否则不要添加时髦的渐变、玻璃效果、卡片、徽章、动画或圆角容器。

阅读 references/frontend-quality.md，了解组件架构、样式规范、数据、路由、性能和可维护性。

如实处理素材

在创建替代素材前，先在代码库中搜索完全匹配的徽标、图标、字体、照片和插图。找到匹配项时，优先重复使用现有素材。如果已有图标库中的字形明显对应，则使用该图标。

不要用渐变矩形或随意的表情符号代替醒目的图片。如果没有完全匹配的素材，请使用法律允许的近似替代素材；在获得授权且工具允许时生成素材；或创建清晰区分的占位内容并予以说明。切勿伪造品牌徽标，也不要在不说明的情况下热链未知来源。

如果截图中包含重要图像、徽标、图标或不清晰的文字，请阅读 references/assets-and-content.md。

推断响应式行为

综合参考所有截图进行推断，确定哪些尺寸是固定、流动、封顶、重排、隐藏、折叠或可滚动的。不要创建一个仅仅缩小尺寸的桌面画布。

如果用户未指定视口，则由 Agent 决定视口。在工作总结中说明推断的桌面、平板或移动端分类，并在该分类的代表性视口下验证结果。不要将所有附件都默认为桌面端。

如果只提供了一个视口，请根据内容优先级和组件语义制定保守的响应式规则。让关键内容和操作保持可见，确保行长易读，适当折叠导航，仅在必要时堆叠内容，并防止溢出。不要声称在未提供的视口下实现了像素级还原。

在完成多视口、移动端、表单、导航或交互密集型工作前，请阅读 references/responsive-and-accessibility.md。

重建行为，而不仅是外观

根据可见的操作暗示和常见语义推断交互，但不要凭空添加截图未体现的大型产品流程。实现足够的行为，让重建的界面可信且易用。

• 让截图中出现的导航、标签页、手风琴、菜单、对话框、轮播、筛选器、表单和选择控件正常工作。
• 如果代码库已定义 URL／路由行为，则予以保留。
• 区分仅用于演示的视觉数据与真实应用接线；不要用静态模拟数据替换正常工作的后端。
• 对组件合理需要的空内容、加载、错误、长内容和窄屏状态提供稳定表现。
• 动效应克制且有据可依。只有在截图序列或实时参考支持时，才匹配时长、方向和缓动效果。

有关状态建模和安全推断，请阅读 references/interaction-and-states.md。

通过渲染结果进行验证

1. 运行项目，并在每个参考视口下截取实现效果。
2. 使用并排对比，或在条件允许时使用叠加／差异工具，对比参考图与渲染结果。
3. 按以下顺序修复差异：结构和尺寸、排版和换行、间距和对齐、颜色和表面样式、素材，最后是细小装饰。
4. 重复上述步骤，直到剩余差异不明显，或确实由源信息缺失造成。
5. 在用户未提供的至少一个中间宽度下进行检查，找出脆弱的断点设置。
6. 检查键盘导航、焦点可见性、语义地标、可访问名称、对比度、缩放、减少动态效果设置和溢出情况。
7. 根据代码库情况运行格式化工具、Lint／类型检查、测试和生产构建。

未经渲染验证，绝不要声称已忠实还原。有关对比优先级和完成标准，请阅读 references/verification-loop.md。

使用 references/fidelity-rubric.md 为结果评分。细小装饰得分再高，也无法弥补构图、排版、响应式表现或交互方面的错误。

禁止使用的捷径

• 不要将截图本身嵌入页面或用作全屏背景。
• 如果可以用语义化 HTML 和 CSS 重现界面，就不要用 canvas/SVG 路径描摹整个界面。
• 不要使用数百个硬编码坐标来匹配单一视口。
• 不要用模糊、过多渐变、叠加层或裁切容器来掩盖差异。
• 不要用表情符号、随机图标或无关的图库图片替换精确的可见素材。
• 除非当前项目缺少合适的基础框架且有充分理由，否则不要安装新的框架、CSS 系统或组件库。
• 不要仅仅因为静态截图中没有呈现，就移除现有行为。
• 未经测试，不要声称具备响应式还原度、无障碍性或像素级准确度。

报告

概述已实现的内容、变更的路由/组件、验证过的截图和视口、运行的命令、仍然存在的视觉差异、推断的行为，以及仍需用户提供源文件的素材或字体。