---
name: create-cc-web-theme
description: 为 cc-web 创建、复刻、重做或审计视觉主题，从参考图、概念图、背景图、图标板或素材板完成需求澄清、源素材归档、主题隔离、可复现切图、CSS/DOM 接入、响应式、回归和真实浏览器视觉验收。用户提到新建主题、换肤、复刻设计稿、主题高保真、主题对比、切图、图标重做、欢迎卡、输入框装饰框、消息气泡磨砂、视觉错位或主题返工时使用。
---

# 创建 cc-web 主题

把参考设计转成一个独立、可切换、可维护并经过真实浏览器验收的 cc-web 主题。保留设计证据和生成链路，避免只留下无法继续扩展的最终切片。

## 按需读取参考

- 开始定位主题系统前，读取 [cc-web-theme-architecture.md](references/cc-web-theme-architecture.md)。
- 收到背景、图标板、边框板或概念图时，读取 [asset-workflow.md](references/asset-workflow.md)。
- 遇到“不像设计图”“改了没变化”“边框/图标/透明度/居中反复不对”时，读取 [lessons-learned.md](references/lessons-learned.md)。
- 准备声明完成前，完整读取并执行 [acceptance-checklist.md](references/acceptance-checklist.md)。

## 遵守硬约束

1. 为新主题创建新的稳定主题 ID 和独立资产目录。除非用户明确要求，禁止覆盖、重命名或删除现有主题。
2. 修改前检查工作树与相关文件差异。保留用户和其他任务的未提交改动，不格式化或重排无关大文件。
3. 先归档所有源概念图、素材板和背景，再生成派生资产。保留裁剪脚本、坐标、manifest 和来源哈希。
4. 把参考图当作构图与层级契约，不只提取颜色和“氛围”。先量化，再编码。
5. 只使用本地主题资产。禁止让产品运行时依赖参考站点、临时附件 URL 或远程图片。
6. 同步维护静态首屏 DOM 与动态渲染 DOM。动态项目名、Agent、会话标题等内容禁止写死在静态模板中。
7. 只修改用户指出的层级。用户说“气泡背景”时，不得顺手重做所有卡片、工具层或布局。
8. 自动化通过不等于视觉完成。没有真实浏览器对照、动态状态检查和多视口验收时，不得声明完成。
9. 不删除源图、概念图、素材板、切片或提取脚本；后续功能可能需要重新切片。
10. 需要重启 cc-web 时，先按仓库 `AGENTS.md` 检查其他运行中会话；不满足条件时不重启。

## 执行工作流

### 1. 固定需求和完成标准

明确并记录：

- 新建、复刻、扩展还是修复主题。
- 主题稳定 ID、显示名、是否与旧主题并存、默认主题是否变化。
- 参考图、背景图、图标板、边框板、字体和其他输入素材的角色。
- 用户要求保留的既有视觉与明确禁止改动的区域。
- 参考图原始视口、桌面目标视口和移动端目标视口。
- 必须覆盖的动态状态：空会话、长消息、多行输入、工具调用、展开菜单、运行/停止、弹层和窄屏。

在任务资料中建立资产表和验收清单。输入素材含义不明确且会影响构图或切片时，先向用户确认。

### 2. 建立代码与改动基线

优先使用 `codebase-memory-mcp`：

1. 调用 `list_projects` 和 `index_status(project="home-cc-web")`。
2. 使用 `search_graph` / `search_code` 定位主题注册、应用、静态 bootstrap、动态 welcome 和回归入口。
3. 需要调用关系时使用 `trace_path`，需要源码时先取得 `qualified_name` 再调用 `get_code_snippet`。
4. 最后使用 `rg` 和 `git diff` 校验文本、行号与未索引资源。

记录主题相关脏文件、既有主题 ID、缓存版本、共享选择器和任务开始时的资产清单。只在明确边界内修改。

### 3. 把参考图拆成可验证规格

先输出“参考区域 → 实际 DOM → 资产 → CSS 责任”的映射，再实施。

至少量化：

- 侧栏、顶栏、消息区、输入区的比例和基线。
- 主视觉安全区、文字阅读区和背景裁切/遮罩策略。
- 面板层级、透明度感知、边线宽度、阴影和切角使用范围。
- 每类控件的容器尺寸、图标视觉主体、间距和光学中心。
- 固定尺寸与动态高度组件的区别。
- 静态空页面和有内容页面的布局差异。

先处理背景与大布局，再处理容器层级、边框、图标和微交互。禁止从局部颜色微调开始掩盖结构偏差。

### 4. 建立可复现资产链路

把源素材复制到当前主题任务的 `references/source-assets/`，不要只引用会话附件路径。为每个派生资产保存：

- 源文件名和哈希。
- 源裁剪框、规格或素材板单元格。
- 输出尺寸、格式和用途。
- alpha/颜色分离方法和必要的光学校正。
- 生成脚本与 manifest。

按用途选择实现：

- 背景保留构图和清晰度，遮罩只服务可读性。
- 主交互小图标优先使用干净 mask 或对应尺寸切片；多色状态、头像和装饰图标保留原色。
- 非对称图标按 alpha 加权重心校正，不按透明画布机械居中。
- 固定尺寸框可使用完整切片；动态高度框优先使用 `border-image`/九宫格或拆分稳定边角，禁止把固定比例整图放在伪元素上随内容拉伸。

具体方法见 [asset-workflow.md](references/asset-workflow.md)。

### 5. 分层、隔离地接入主题

按以下顺序实现：

1. 在 `THEME_OPTIONS` 新增主题元数据，保持单一数据源。
2. 检查首屏 bootstrap、`normalizeTheme()`、`applyTheme()` 和本地持久化是否接受新 ID。
3. 在 `html[data-theme='<id>']` 变量块中先定义语义 token。
4. 把新暗色主题加入确实需要复用的共享 completion selector。
5. 把高风险视觉放在文件后部的主题专属组件层，所有选择器都限定主题 ID。
6. 把资产放入 `public/assets/themes/<id>/`，避免根目录同名覆盖。
7. 同步静态 `index.html` 和动态构建函数中的 welcome/装饰 DOM。
8. 检查真实 DOM 内原生文字、SVG、图片和主题伪元素，防止加号、头像、图标或边框重复。
9. 更新 CSS/JS cache bust，并同步回归契约。

不要为了视觉方便复制第二套业务逻辑、主题列表或交互组件。

### 6. 用真实浏览器形成短反馈环

先按参考图原始尺寸验收，再检查常规桌面和窄屏。每轮只解决一个明确层级，并记录修改前后证据。

遇到异常时按顺序排查：

1. 浏览器是否实际加载了最新缓存版本和资源。
2. 选择器是否命中真实 DOM，伪元素或原生子节点是否重复。
3. computed style 的最终来源和 specificity，特别检查 `:is()` 与旧 `!important`。
4. 外层看似透明时，内层工具块、标题层或伪元素是否仍不透明。
5. 动态高度、文字换行、菜单展开和运行状态是否改变真实尺寸。
6. 几何中心、文字基线和图标 alpha 重心是否一致。

优先测量，不盲调数值。把“看着偏”转换为中心差、边距、主体 bbox、computed background 或溢出量。

### 7. 完成工程与视觉验收

执行 [acceptance-checklist.md](references/acceptance-checklist.md) 的全部强制项，至少包含：

- JS 语法检查、主题专项回归、相关旧主题回归、全量回归和 `git diff --check`。
- 本地资产存在性、格式、尺寸、hash/manifest 与 HTTP 200。
- 参考视口、常规桌面和窄屏的真实浏览器检查。
- 空页面、长内容、多行输入、菜单、工具块、按钮状态和动态文案检查。
- 与参考图逐组件对照，确认没有多余边框、重复图标、视觉实心层或明显错位。

最后报告实际视觉证据、验证命令和保留的源资产/脚本路径。测试失败、浏览器不可用或视觉证据不足时明确说明，保持任务未完成状态。

## 交付要求

- 列出新增主题 ID、资产目录、源资产归档和提取脚本。
- 列出修改过的主题链路文件与隔离边界。
- 给出真实浏览器实测结果，不只写“回归通过”。
- 说明仍未覆盖的视口、状态或素材限制。
- 保留所有主题概念图、素材板、切片、manifest 和生成脚本。