Web 开发：从截图或 brief 还原可验收页面

截图看起来一样，页面却还不能交付

桌面稿在 1440 像素下很漂亮。Codex 很快复制出相似布局，可一到手机，说明文字被挤成竖列，按钮也无法用键盘聚焦。

截图是目标证据之一，不是全部产品契约。 这节课先读现有组件和 token，再做最小实现，最后回到真实路由验收。

这节课要交付什么

这不是一份只需要读完的功能介绍。你要在真实但可控的环境中留下一个可以复查的结果，并且能回答三个问题：Codex 看到了哪些事实，它实际做了哪些动作，你用什么独立证据确认结果成立。

最终结果是：一个复用现有组件和 token、通过双视口验收的页面改动。开始前先创建一份简短记录，把当前环境、目标、禁止动作和验收方式写下来。后面的命令、截图和修改都回到这份记录，不靠聊天窗口里的“应该已经好了”判断完成。

先看官方边界

官方 Web 开发案例强调先理解仓库现有组件、设计 token 与页面模式，再把截图或 brief 翻译成实现；验证需要回到真实浏览器。截图只说明可见结果，不能自动证明路由、数据流和可访问性。教程因此把设计相似度、行为正确和回归风险分开验收。

官方页面会随产品更新。教程引用的是当前可核对的能力与命令，不把界面位置、套餐权限或预览功能包装成永久承诺。你在自己的设备上看到不同按钮时，先核对官方页面和本机版本，再决定是否继续；不要用过期截图覆盖现场事实。

任务现场

产品给你一张 1440 像素桌面稿和一句“移动端也适配”。仓库里已有 Button、Card 和 spacing token，但旧页面又混有自定义 CSS。若直接让 Codex“照着做”，最容易产生第二套组件体系，并在 390 像素下溢出。先让它读页面、相邻路由和设计系统，再确定差异清单。

先把现场写成四行：工作目录或项目、当前版本或输入、允许动作、完成证据。如果其中任何一行只能写“让 Codex 自己看”，说明上下文仍然不够具体。Codex 可以帮助检查，但不能替你决定哪些数据能上传、哪个生产动作已获授权，或一个异常是否可以忽略。

动手前准备

保存目标截图与来源，记录必须一致的结构、允许近似的装饰和完全未知的交互。启动项目并确认基线页面能访问。让 Codex 只读查找路由、组件、token、字体和响应式断点，输出“可复用—需新增—需确认”三列清单；不要在调研阶段创建通用组件。

把练习放在可恢复的位置，保留原始输入，并记录开始时的状态。涉及代码时先看版本控制状态；涉及数据时先复制脱敏样例；涉及外部服务时先使用只读或草稿模式。准备工作看似慢，却能让失败变成一次可以解释和回退的实验。

第一步：只读建立基线

要求 Codex 对目标截图逐区映射到现有实现：信息层级、容器宽度、网格、排版、颜色、状态和移动折叠。每个判断附文件证据。先标出会改变业务逻辑的部分并排除，本轮只做视觉结构与明确交互。

这一阶段不要急着要求“直接修好”。先让 Codex 复述目标、列出它实际读取的来源，并指出还缺哪些证据。你要检查它有没有打开正确目录、有没有把搜索摘要当原文、有没有把旧日志误当当前状态。基线不可信，后面的修改越多，返工成本越高。

第二步：限制范围后执行

一次只实现一个区块，优先组合现有组件和 token。任务约束写明不改 API、路由与数据契约，不引入新的 UI 库，不为了复用抽象只有一个消费者的组件。每完成一块就看 diff 和页面，发现系统性偏差再调整，不让错误复制到整页。

执行指令应该同时包含目标、范围和停止条件。把“不要乱改”换成可观察边界，例如只允许修改两个文件、不安装依赖、不发送消息、不触碰生产数据。出现新的权限、需要改变既有契约或发现输入口径不一致时，要求 Codex 停下来报告，而不是自行选择更大的方案。

第三步：用独立证据验收

在目标路由分别用 1280×720 和 390×844 验收：检查折行、裁切、横向滚动、焦点、键盘操作、加载与空状态。截图使用同一数据和缩放。再运行已有测试、类型检查和构建，把视觉通过与工程检查分别记录。

验收必须尽量脱离生成答案本身：安装类任务看版本、路径和真实启动结果；界面任务看目标视口与交互；数据任务用独立计算和异常清单；安全任务用原始复现、补丁 diff 与回归测试。把通过、失败和未验证分开记录，未验证不是失败，但绝不能伪装成通过。

完整案例

一个知识库首页的内容地图在桌面设计稿中有四列。Codex 初稿把说明文字放到最右侧窄列，中文被压成单字换行。团队没有改字体大小掩盖问题，而是回到网格语义：编号、标题、描述、篇数各自锁定区域；平板降为三列，移动端单列。桌面和移动截图、无横向滚动检查与源代码 grid placement 一起成为验收证据。

案例的重点不是复制同一句 prompt，而是观察决策顺序：先确定权威来源，再缩小动作面，最后让证据闭环。如果你的项目结构不同，保留这个顺序，替换文件名、命令和验收对象。任何会产生外部影响的步骤，都应在真正执行前再次获得明确授权。

故障诊所

页面“差不多”但不稳定时，先锁定同一路由、视口、数据和字体，再比较。出现整页 CSS 重写时撤回到最小区块。文字被压成竖列通常是网格列宽或隐式放置错误，不要先缩小字号。移动端出现横向滚动时逐层检查固定宽度、min-width 和绝对定位，并用真实浏览器复现。

恢复时一次只改变一个变量。先保存错误原文和当前状态，再判断问题属于安装路径、权限、上下文、实现还是验收环境。不要连续重装、重写和切换工具，因为那会抹掉因果关系。修复后重复最小复现，再跑相邻路径，确认没有用一个新问题遮住旧问题。

迁移练习

选一个现有二级页面，只改一处信息层级。先提交只读映射，再提交最小 diff，最后提供两个视口截图、键盘路径和测试结果。让另一位读者仅凭验收记录判断是否能发布，并记录他仍然缺少的证据。

完成练习后，把其中的产品名和文件名遮住，只保留“输入—动作—证据—停止条件”。如果这四项仍能指导另一个任务，说明你学到的是方法；如果离开示例 prompt 就不会继续，回到任务现场，补出你真正依赖的判断规则。

把视觉相似、行为正确和工程健康分开证明

交付时同时给出双视口截图、交互路径、diff 和工程检查。任何一项缺失，都写成未验证，不用一张漂亮截图遮过去。

下一次面对设计 brief，先问仓库已经拥有什么。复用不是节省几行代码，而是让新页面继续属于同一个产品。

完成检查

• 实现前已盘点现有组件、token 与相邻页面
• 业务路由、数据流和 API 契约没有被视觉任务意外改动
• 桌面与移动端使用同一路由和真实数据验收
• 视觉、交互、测试和构建结果分别记录
• 我保留了开始状态、实际动作和最终证据
• 我把失败、未验证和已通过分开记录
• 需要新权限或外部影响时，Codex 会停下来询问