这项任务的最终产物是一个能在现有项目中运行的页面,以及桌面和窄屏两组验收截图、交互检查结果和仍有差异的清单。验收者可以打开同一路由,在约定视口重做截图,对照间距、层级、换行和控件状态。单张看起来相似的静态画面,不能证明响应式行为已经完成。
把截图变成可执行的约束
准备分辨率清楚的参考图,注明它对应的视口宽高、页面状态和素材来源。截图中看不见的行为要另写说明,包括菜单怎样打开、表单怎样报错、列表是否滚动、窄屏如何折叠。若只有一个尺寸,把不确定处列成假设,先选最简单且符合现有项目习惯的方案。
同时交给 Codex 当前仓库、运行命令、目标路由和设计系统入口。先让它阅读已有组件、颜色变量、字阶、间距和断点。提供图片时,还要说明需检查的区域、目标和限制,不能让一张图替代全部任务说明。
建立一张对照表,按页面骨架、内容宽度、排版、颜色、边框、素材、组件状态和响应式变化记录。可见结果是每项都有参考依据或明确假设,避免实现到一半才发现标题、卡片或导航各自采用了另一套规则。
素材也要单独核对。确认图片能否裁切、图标来自哪个库、品牌标志是否已有矢量文件,以及高分屏需要什么尺寸。缺失素材先用标注清楚的占位内容,不能从低清截图里抠出模糊图标再当成正式资源。

先还原骨架和内容层级
先做页面容器、主要区域、网格与内容顺序,再处理装饰细节。复用仓库已有组件和令牌,不另建一套平行样式。结构完成后启动本地服务,检查路由可达、内容顺序正确、控制台没有阻断错误。此时页面可以朴素,但骨架应与参考图一致。
接着处理字体大小、行高、留白、边框和素材比例。不要用大量绝对定位追一张截图,它会在另一尺寸立刻失效。让容器、网格和弹性布局表达真实约束,断点只在内容开始挤压或层级需要重排时出现。长标题、缺图、更多列表项和浏览器缩放也要能承受。
每完成一组改动就保存同一视口的截图。先比较页面外框和主要分栏,再看组件内部细节。差异清单写出位置、参考状态、实际状态和下一次只改哪项。一次混改颜色、结构与行为,会让后续无法判断是哪项修正造成了新的偏差。
对照时固定浏览器缩放、设备像素比和页面数据。先用边界框或测量工具核对容器宽度、元素间距和文本基线,再判断肉眼差异。动画页面要等到稳定帧再截图,加载中的随机内容则换成确定夹具。

在两个尺寸上来回验证
至少选择一个桌面视口和一个窄屏视口。桌面验收后马上切到窄屏,检查导航折叠、内容顺序、点击区域、横向溢出和图片裁切,再回到桌面确认修正没有破坏原布局。可以启用并调用 $playwright-interactive 保存固定视口的整页或元素截图,也可以使用桌面端 @Browser 或由人手工截图。使用哪种路径都要在验收记录中写清。
视觉相似之外,还要用键盘走过主要控件,检查焦点可见、语义标题、表单标签和错误提示。悬停、展开、加载、空状态与失败状态都需要明确结果。若参考图本身存在低对比或不可用交互,应保留视觉方向并修正可访问性,在差异清单中说明理由。
浏览器中的最终检查应使用生产构建能够运行的代码。记录构建命令、浏览器、视口、路由和截图路径。参考图与实现图并排查看,剩余差异按是否影响层级、操作和品牌判断能否接受。
若页面依赖接口,把成功、空结果和失败响应固定为可重复数据。这样复核者重开页面时看到的是同一状态,截图差异才有意义。验收记录还应说明哪些内容会随账号或时间变化。

风险与限制
截图只提供一个时刻的像素,无法说明数据变化、内容极值和全部交互。系统字体、浏览器渲染和平台控件也会造成小差异。追求像素接近时不能牺牲语义结构、可访问性和可维护性。没有设计源文件时,所有推断都应留在验收记录中。
交付清单
- 参考图注明视口、状态和素材来源
- 现有组件、令牌和路由约束已经复用
- 桌面与窄屏都没有横向溢出
- 主要交互、键盘焦点和异常状态已检查
- 构建命令和浏览器验收能够重跑
- 最终截图与剩余差异清单已经保存