cc-web/.codex/skills/create-cc-web-theme/references/acceptance-checklist.md

cc-web 主题完成验收清单

把本清单作为完成门禁。任一强制项未验证时，保持任务未完成并说明原因。

1. 范围与隔离

• 新主题使用独立稳定 ID，未覆盖现有主题。
• THEME_OPTIONS、bootstrap、持久化和 picker 的语义一致。
• 现有主题仍可选择/迁移，并通过其专项回归。
• 所有专属 selector 都限定新主题 ID。
• 未修改主题无关业务逻辑、交互或大文件格式。
• 已复核相关脏文件，没有覆盖用户或并行任务改动。

2. 源素材与派生资产

• 概念图、完整参考、背景和素材板已归档到任务目录。
• 归档文件与原始输入 hash 已核对。
• 生成脚本和 manifest 已保留且可重放。
• 派生资产记录源文件、裁剪框、规格、尺寸和用途。
• 透明 PNG 无棋盘格、黑边或被裁掉的尖角。
• 图标 alpha 主体尺寸和光学中心符合控件层级。
• 所有运行时资产位于 public/assets/themes/<id>/。
• 主题实现与 manifest 不包含远程图片 URL。

3. DOM 与组件实现

• 静态 index.html 与动态 welcome 构建函数结构同步。
• 项目名、Agent、会话标题等动态内容没有写死。
• 新主题图标未与原生文字、SVG、图片或旧伪元素重叠。
• 新会话加号、下拉、操作菜单和设置入口仍可见、可点击。
• 菜单展开不被父级 overflow 裁切。
• 固定框与动态尺寸框使用了合适的切片策略。
• 输入框单行、多行、聚焦、拖拽和特殊模式都没有双边框或错位。
• 工具块、协作卡、弹层和消息嵌套层没有意外不透明底色。
• prefers-reduced-motion 能关闭主题动画/过渡。

4. 视觉对照

参考视口

• 在参考图原始尺寸或同等宽高比下截图/检查。
• 背景主体、人物、纹理和安全区与参考构图一致。
• 侧栏、顶栏、消息区和输入区比例无明显偏差。
• 面板层级清楚，没有全页面卡片化或遮罩过暗。
• 边框轻重、切角范围和阴影符合参考层级。
• 主文字可读，用户指定的颜色与对比度已满足。
• 没有重复图标、莫名边框、虚线、色块或“一坨”叠层。

几何证据

• 主卡片中心与实际聊天画布中心误差可接受。
• 图标以 alpha 主体/光学重心居中，不只看画布。
• 文字与图标基线一致。
• 欢迎卡、输入框和菜单没有横向溢出或裁切。
• 记录关键 bbox、中心差、间距或 computed style。

透明与磨砂

• 背景纹理在设计要求透明的层中实际可见。
• 外层气泡与内层工具块分别检查背景。
• blur 没有把背景细节抹成实心色块。
• computed style 的最终 background/backdrop-filter 来自预期 selector。

5. 动态状态

• 新建空会话欢迎页。
• 当前项目名称/其他动态文案刷新正确。
• 短消息、长消息、代码块和工具调用。
• 用户/助手/系统/跨会话气泡。
• 单行与多行输入。
• 附件、笔记、队列、发送和停止状态。
• 会话 hover、active、操作菜单展开。
• 设置页、主题选择器、弹层和移动端侧栏。

6. 多视口

至少检查：

• 参考设计原始视口，例如 1672×941。
• 常规桌面，例如 1440×900。
• 窄屏，例如 500px 宽。
• 移动端，例如 390×844。
• 各视口横向溢出为 0 或有明确设计原因。
• 背景定位、侧栏宽度、输入框和欢迎卡在断点处连续。

7. 自动化与静态检查

根据实际主题 target 调整 <theme>：

timeout 60s node --check public/app.js
timeout 60s node --check scripts/regression.js
timeout 60s npm run regression -- --target <theme>-theme
timeout 60s npm run regression -- --target <related-existing-theme>-theme
timeout 60s npm run regression
git diff --check

• 新主题专项回归通过。
• 相关旧主题专项回归通过。
• 全量回归通过。
• JS 语法检查通过。
• git diff --check 通过。
• 回归覆盖注册、隔离、静态/动态 DOM、资产、响应式、对比度、reduced-motion 和 cache bust。

8. 在线与浏览器校验

• 先用 curl http://127.0.0.1:<port>/ 确认本地服务。
• 如远程浏览器不能访问 localhost，使用 hostname -I 中的 11.144.144.* 地址。
• CSS、JS 和每个新增资产请求返回 200。
• 浏览器实际加载的 cache-busted URL 是最新版本。
• 使用 Firefox/Playwright/Selenium 读取关键 computed style 和几何值。
• 浏览器截图或实测记录已写入任务进度。

不要仅因浏览器访问 127.0.0.1 失败就判断服务未启动。

9. 交付与保留

• 列出新主题 ID、显示名和资产目录。
• 列出修改文件和未触碰的旧主题边界。
• 列出源素材归档、manifest 和提取脚本路径。
• 报告真实浏览器结果和多视口数据。
• 报告专项/全量回归结果。
• 说明任何未验收状态或环境限制。
• 未删除概念图、素材板、切片或生成脚本。

只有工程检查、真实浏览器视觉和参考图对照全部满足后，才能把主题标记为完成。