83 lines
7.5 KiB
Markdown
83 lines
7.5 KiB
Markdown
# 风格对比页
|
||
|
||
把几个候选放在同一页里并排比较，由用户挑选。用户可以并排或单张查看、切换桌面和手机、按实际尺寸看、筛选、选定并写备注。对比页的外壳只负责比较和挑选，不带风格倾向，也不作为候选的参考。
|
||
|
||
先保持核心内容、主要动作和目标用户一致，再改变构图、信息组织、字体气质、色彩关系、密度与图像语言。数量按请求和有效差异决定，不复制整个产品来凑方案，也不把内置外壳的风格套给候选。
|
||
|
||
对比页是视觉探索工具。HTML 小样默认不执行脚本和提交，标记为可操作的小样和本机地址候选除外（见“准备输入”）；需要真实数据、登录或后端的交互验收，仍在项目里进行。
|
||
|
||
## 准备输入
|
||
|
||
一轮只生成一个对比页，候选能跑就用真实页面：单独写的 HTML 小样直接嵌入，项目里的方案用本地地址。只有拿不到可运行的页面时才用截图。每个方案一个画面：存量项目选入口或差别最大的那一步，整站方案只放代表页，其他页面写进说明。手机版只在手机是主要设备时另出，不手写汇总页。
|
||
|
||
在任务目录放置 `manifest.json` 和候选文件。HTML 候选为带 `head` 的文档，CSS 写在页面里。图片、字体和视频用相对路径引用任务目录里的文件，例如 `img/hero.jpg`，生成器会把它们内嵌进对比页；不要自己把图片转成 base64 写进候选，文件会变得很大、难以修改。不引用网络资源和任务目录以外的文件，链接只使用本页锚点。可以保留代码供独立打开，但比较页不执行其脚本。
|
||
|
||
候选必须在不运行脚本时也能显示设计内容。依赖脚本生成界面的页面，先取得静态 HTML 或实际截图；不能把只有空挂载节点的应用入口交给对比页。
|
||
|
||
候选内部不使用 iframe、object 或 embed 等嵌套文档；先将需要的内容转为静态页面或截图。另存的现有页面常带 `srcset` 或 `<picture><source>` 响应式图片，生成器会拒绝：改成一张用相对路径引用的 `<img>`，或直接用截图作为图片候选。
|
||
|
||
图片候选支持 PNG、JPEG、WebP。实际查看图片并记录它代表的页面与状态，避免拿不同任务或不同状态的图比较风格。源文件必须位于 manifest 同目录或子目录。
|
||
|
||
manifest 使用固定字段，结构如下。尖括号内是占位说明，全部换成本轮方向卡里的实际内容；不要沿用占位文字作为风格：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 1,
|
||
"project": "<项目名称>",
|
||
"brief": "<所有候选共同表达的内容与主要任务>",
|
||
"round": "<轮次，例如 01>",
|
||
"candidates": [
|
||
{
|
||
"id": "<小写唯一标识>",
|
||
"name": "<方向名称>",
|
||
"concept": "<北极星：一句能指导取舍的体验意图>",
|
||
"typography": "<实际使用的字族、字重与尺度关系>",
|
||
"palette": ["<十六进制色值>", "<十六进制色值>", "<十六进制色值>"],
|
||
"traits": ["<可观察特征>", "<可观察特征>"],
|
||
"kind": "html",
|
||
"source": "<候选文件的相对路径>"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
自己写的可运行小样（单个 HTML、脚本内联），在 manifest 里给候选加 `"interactive": true`。单张查看时就能直接操作，对比页仍是可离线移动的单个文件，不需要服务器；卡片左下角标注“可操作”。这类候选只能运行内联脚本，不能联网或加载外部文件；浏览器存储换成页面关闭即清空的内存版本；`alert`、`confirm` 这类系统弹窗不会出现，需要确认时用页面内的对话框。
|
||
|
||
已有仓库里要运行起来的应用（例如 React、Vue 项目），把 `kind` 设为 `url`，用 `url` 字段代替 `source`，指向本机开发服务器上的页面，例如 `http://localhost:5173/orders?variant=b`。这类候选在对比页里实时运行，脚本和表单照常工作，切换手机视口时应用会真实重排；卡片左下角标注“本地运行”。地址只能是 localhost、127.0.0.1 或 ::1；页面空白时，确认开发服务器已启动，且没有用响应头禁止被嵌入。这类候选要靠开发服务器才能看，所以：
|
||
|
||
- 在 manifest 顶层写下启动方式，就是你刚才自己用过的那条命令：`"serve": {"command": "pnpm dev", "cwd": "<项目的绝对路径>", "url": "http://localhost:3456"}`。
|
||
- 交付时让开发服务器开着，用户打开对比页看到的就是真实页面。
|
||
- 服务没在运行时，对比页会提示用户在对话里说“打开对比页”，并附上这条命令。
|
||
|
||
不默认另存截图版。用户要长期留档或发给别人时，再用 [工具](tools.md) 里的截图工具另截一份。
|
||
|
||
给当前版本加 `"baseline": true`，它会排在第一位，编号显示为“现状”，其余方向从 01 开始编号。每轮最多一个基线。改动存量页面时，都把现状放进来，让每个方向都和它对照。
|
||
|
||
`id` 使用唯一的小写字母、数字、连字符或下划线。`typography` 描述实际使用的文字关系，`palette` 使用十六进制颜色，`traits` 简述可观察差异。图片候选将 `kind` 改为 `image`、`source` 指向对应图像。
|
||
|
||
## 生成和打开
|
||
|
||
确认 Python 不低于 3.10，将脚本与输入输出参数解析为绝对路径后运行 [生成器](../scripts/build_explorer.py)：
|
||
|
||
```text
|
||
<python> <skill>/scripts/build_explorer.py <任务目录>/manifest.json --output <任务目录>/style-explorer.html
|
||
```
|
||
|
||
macOS/Linux 通常使用 `python3`，Windows 通常使用 `py -3`；执行前确认实际解释器。没有生成器运行能力时保留输入与候选供直接查看，说明尚未组装对比页，不临时重写另一套工具。
|
||
|
||
默认拒绝覆盖。确实要更新已有本轮对比页时显式加 `--force`，或使用新的输出文件名。输入错误时保留旧产物；生成器不覆盖源候选，也不允许把运行产物写入 Skill 目录。
|
||
|
||
用浏览器打开返回的本地 HTML。HTML 小样和截图已经内嵌，单个文件移到哪里都能看；本地地址候选要开发服务器开着。模板原文件只有空状态，不是用户最终对比页。
|
||
|
||
用户之后说“打开对比页”时：读对比页旁边的 manifest 里的 `serve`，在 `cwd` 里后台运行 `command`，等 `url` 能访问了，再用浏览器打开对比页。端口被占用时先确认占着它的是不是同一个项目。
|
||
|
||
## 查看与记录选择
|
||
|
||
默认使用相同逻辑视口展示 HTML 候选：桌面 1280×900，手机 390×844。卡片等比缩放以便同屏比较；判断文字大小与细节时进入单张查看，使用“实际尺寸 100%”检查真实排版；适应窗口仍可能缩小，不能据此宣称可读性通过。切换手机视口后确认真实重排，而非仅看缩小后的桌面。
|
||
|
||
点“选择”时会复制一句简短的文字，例如“<轮次>：选 03 <方向名>”，有备注时再附一行。用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到项目设计说明，继续实现。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。
|
||
|
||
## 检查实际结果
|
||
|
||
核对候选：每张画面和 manifest 里写的页面、状态、视口一致，中文字体真实渲染出来了。对比页本身的并排、单张、筛选、复制和离线打开由 Skill 自带的回归测试保证，任务里不验证、不读模板源码，也不在用户自己的浏览器里清除任何存储。
|