Vibe Coding 视觉参考拆解：从截图线索到组件交付计划

一张桌面截图能说明某一时刻“看起来怎样”，却不说明内容从哪里来、按钮按下后发生什么、窄屏如何排列、空数据是否隐藏区域、焦点顺序是什么。让 Agent 直接“照图实现”，往往会产出大量绝对定位、临时颜色和为了截图存在的空标签；首屏相似，但文字一变长、错误一出现或键盘导航一开始，布局立即失效。

视觉参考应当作为需求证据之一，不是完整规格。先确认图片来源、授权范围和可使用资产；第三方品牌、照片、图标和字体不能因为出现在截图里就自动拥有复制许可。需要替换的素材在计划中明确标成占位，不让模型伪造来源。

对参考图做六层观察

第一层是内容：标题、说明、数据字段、动作和状态提示分别是什么，哪些是固定文案，哪些来自服务。使用真实长度区间的合成文本，而不是整齐的 Lorem ipsum。中文、英文、长 URL、空值与多行错误会暴露完全不同的布局约束。

第二层是信息结构：页面有哪些 landmark，标题层级如何，主要动作与次要动作是什么。HTML 语义元素先于视觉容器；nav、main、form、button 不能为了样式全部退化成 div。HTML 标准提供元素语义，参考图只能提供视觉线索。

第三层是布局约束：内容最大宽度、列之间关系、对齐线、可伸缩区、固定区和溢出策略。记录“侧栏在内容不足时保持可用宽度”这类关系，不猜一个截图里的绝对坐标。断点由内容失效点决定，而不是先套设备名称。

第四层是组件候选：重复的按钮、字段、标签和列表项属于基础或组合组件；包含权限、请求和业务状态的区域属于 feature。不要把每个矩形都建组件，也不要把整页塞进一个文件。React 设计模式可帮助选择组合方式，设计系统与 Design Tokens则提供既有视觉语言。

第五层是状态：默认、hover、focus-visible、pressed、disabled、loading、empty、partial、error、success 和无权限。截图中没出现的状态记为 UNKNOWN，由产品或设计 owner 决定，Agent 不应默认为隐藏或弹 toast。

第六层是行为：点击、键盘、滚动、弹层焦点、提交、取消和返回。复杂控件优先按 WAI-ARIA Authoring Practices 中相应模式核对键盘与语义；如果原生控件已经满足需求，不为了视觉重写一套行为。

输出组件计划而不是目录猜测

计划为每个组件记录责任、props/事件、数据 owner、允许状态、语义角色、响应式规则、token、测试夹具和依赖。页面组件只负责编排，业务 feature 管理用例，基础组件不直接取数。跨层数据与错误要有明确输入，不从全局随意读取。

component: SearchResults
owns: [result-layout, empty-state, retry-action]
inputs: [query, resultPage, status]
states: [loading, empty, ready, recoverable-error]
semantics: [section-labelled-by-heading]
viewports: [single-column, content-plus-filter]
unknowns: [partial-result-copy]

这份计划不是要求项目采用 YAML，而是让接口在写 JSX 前可审。未知状态、无素材授权和服务契约未定都应阻断对应实现，不影响其他独立组件先行。若现有仓库已有组件，先通过编程 Agent 的仓库地图确认入口与用法，避免 Agent 生成第二套 Button、Dialog 或表单字段。

按依赖与风险安排实现顺序

先落实 token 与页面结构，再做无业务副作用的 primitives，随后实现静态组合、状态夹具，最后接真实数据与写操作。每一步都能单独展示和验收。Storybook 之类的组件工作台可以隔离状态，但它不是强制工具；仓库已有 preview 或测试页面时沿用现有方式，关键是所有批准状态都能由确定性夹具重现。

高风险组件先做行为骨架。例如 Dialog 先验证打开、关闭、焦点进入与归还，再调阴影；表单先验证 label、错误关联与重复提交，再微调间距。参考图与可访问性冲突时，语义和可操作性是硬约束，视觉差异作为有理由的设计决策记录。React 组件可访问性给出组件层基础，Web 无障碍 WCAG用于页面级验收。

Agent 每次只实现计划中的一个可审单元，并回报实际触碰文件、复用组件和未决项。若出现计划外全局 CSS、复制资产、深层导入或新增依赖，停止扩展并重新评估。视觉接近不能抵消依赖越界。

用场景矩阵完成交付

最终验收不是把当前页面与单张截图并排。建立“组件或页面 × 状态 × 内容长度 × 视口 × 主题”的风险矩阵，选出有代表性的组合：正常桌面、最窄支持宽度、长文本、空与错误、键盘 focus、深浅主题。对每项同时检查结构断言、关键视觉差异和语义行为。

差异分为需求理解错误、实现错误、参考图缺失状态和有意改进。只有后两类经过 owner 决策后才能更新计划。结果及截图绑定当前提交，进入编程 Agent 的改动验证门；旧截图或只验证默认态不能证明本次实现完成。

从视觉线索到组件计划的价值，是把“像不像”变成一组可讨论、可测试的合同。Vibe Coding 仍然可以快速产出界面，但速度建立在清楚的内容、边界与状态之上，而不是建立在一张静态图的空白处。