cc-web/.planning/dark-gilded-theme/findings.md

暗金荒野主题调研记录

图片观察

• 原图尺寸为 1000×1500，纵向 2:3 构图。
• 人物从头盔到腿部完整，披风、法杖、四角铆孔和烧蚀边框均属于有效视觉信息。
• 主体位于中部偏左，右上与人物两侧存在较平静的灰米色留白。
• 下方深色山坡与橙棕草丛适合衔接煤黑界面底色。
• 结论：原图已经适合作为竖向主题画面，不裁切、不扩图、不生成替代图。
• 原图复核后确认右侧法杖与左侧披风均接近边缘，任何实体裁切都容易损失角色轮廓； 应保留资产本身，仅在容器层使用 object-fit/背景定位适配视口。

初始色彩方向

• 煤黑：人物盔甲与前景阴影，用作主背景和深色控件。
• 旧纸米灰：天空与纸面，用作高对比文本和柔和边界。
• 铜棕/赭石：烧蚀边框与山体，用作导航悬停和次级强调。
• 暗金：盔甲纹饰，用作主操作、焦点与选中态，严格控制面积。
• 深褐：人物中间调，用作面板层级和输入框背景。

量化色板

Pillow 对原图缩小后进行 16 色中位切分量化，主要颜色如下：

• #1d1f20（10.10%）：煤黑主背景。
• #bead8a（9.04%）：旧纸主文字/柔和高亮。
• #857e6e（8.56%）：灰褐弱文字。
• #a16a38（8.15%）：铜棕次强调。
• #b0a182（6.97%）：暖灰浅层级。
• #161b1d（6.32%）：蓝煤黑面板。
• #713e1e（6.07%）：深赭边框/警告。
• #3a291f（5.99%）：深褐输入层。
• #d8c396（5.91%）：浅金米色主强调。
• #44392f（5.73%）：褐灰浮层。

色板实测表明界面应避免纯黑、纯白、亮黄和蓝紫色，优先使用带灰度的暖色。

降级视觉验收数据

• CSS 注释/字符串感知的花括号检查通过：1041 个规则块，结构闭合。
• 对比度：主文字/主背景 12.97:1，次文字/主背景 8.77:1，弱文字/主背景 4.79:1，按钮文字/暗金按钮 10.07:1，主文字/面板 11.11:1，均达到常规文本 WCAG AA，主要组合达到 AAA。
• 构图几何：1440×900 时原图显示 600×900，1024×768 时显示 512×768， 390×844 时移动规则显示 358.8×538.2；三类视口均无图像裁切。
• 未发现可复用的浏览器服务端口；11011 返回通用 400，现有 Docker 服务也不包含 browserless/Chromium。

独立代码审查

• 审查结论整体通过，但发现 gilded 在会话 ID 按钮、信息态系统消息、拖拽上传焦点环 和 select 箭头上仍可能继承旧蓝/青色固定值，需要主题专属覆盖。
• 主按钮 hover 渐变的铜棕端 #a16a38 与 #161b1d 约 3.83:1，需要换成 对比度更高的矿物棕端点。
• 回归测试需从 PNG 尺寸提升到固定 SHA-256，并显式断言上述状态覆盖，避免测试通过 但细节泄漏。
• 图片为未跟踪新文件是正常交付状态；最终需在交付清单明确列出，不能只看 tracked diff。

审查修复结果

• 会话 ID、信息态消息、拖拽上传焦点环与 select 箭头均已有 gilded 专属暖色覆盖。
• 主按钮 hover 深色端改为 #a2865f，与 #161b1d 的最低对比度为 5.06:1。
• PNG 回归增加固定 SHA-256；状态覆盖与旧蓝/青色禁止项已加入专项契约。
• 修复后 gilded-theme 专项回归通过，完整回归再次输出 Regression checks passed.。

图片适配决策门槛

1. CSS 的完整侧展或氛围背景能保证操作区可读、关键主体完整时，保留原图。
2. 只有 CSS 构图必然丢失关键主体时才做实体裁切。
3. 只有目标容器必须展示画布外区域时才做扩图。
4. 当前图像可通过桌面独立侧展、移动低对比背景满足第 1 条，因此不裁切、不扩图。

主题资产

• 原图已无损复制到 public/assets/themes/gilded-wasteland.png。
• 源文件与目标文件 SHA-256 均为 11bf3ffed4422c08f6be217c63060ba68d63367e747a3604fc2d7b877e9c5955。
• 目标仍为 1000×1500 RGBA PNG，没有重新编码、裁切或扩图。

仓库状态

• home-cc-web codebase-memory 索引状态为 ready（3264 节点、7795 边）。
• 当前工作树存在用户的未提交修改，主要涉及另一项子代理卡片任务。
• 当前 Trellis 任务属于其他工作，本任务使用独立 .planning/dark-gilded-theme/ 记录。

主题实现入口

• public/app.js 的 THEME_OPTIONS 注册 9 个主题；normalizeTheme 校验主题名， applyTheme 写入 html[data-theme] 与 localStorage。
• public/style.css 顶部定义主题变量；carbon、nocturne、cinder 共用暗色组件层， 文件尾部还有一组补充暗色覆盖。
• public/index.html 提供稳定的 .sidebar、.chat-main、.input-wrapper DOM 入口， 不需要为了主题改动页面结构。
• scripts/regression.js 已有 CSS 源码契约断言，可新增主题注册、资源路径、变量和 响应式规则断言；该文件已有用户未提交改动，新增测试必须落在独立函数/调用点。
• 现有 public/app.js 未提交改动集中在 6541 行后的子代理卡片逻辑，与 109 行附近的 主题注册无重叠；可以在保留现有差异的前提下修改。
• 暗色完成层共有 230 个相同的 :is(carbon, nocturne, cinder) 选择器；新增暗色主题 若不加入该共用层，会让设置面板、附件、工具调用等次级控件回退到浅色固定背景。
• 实现采用两层：将 gilded 纳入暗色完成层以保证全量控件一致，再在文件末尾追加 该主题专属的图片构图、导航、按钮、输入聚焦与状态色覆盖，消除共用层里的蓝色焦点环。

工具限制

• 本机未安装 ImageMagick（identify、magick 均不可用）；色板量化改用已安装的 图像读取库或浏览器取样，不重复执行相同命令。
• 当前工具集中没有 Playwright/Chrome DevTools MCP，本机也没有 Chromium、Firefox、 Playwright、Puppeteer、WeasyPrint 或 wkhtmltoimage；不能直接生成真实浏览器截图。
• 现有 cc-web 进程会实时提供静态资源，无需重启；首页与新主题 PNG 均通过 http://127.0.0.1:8002 返回 200。
• 完成后按项目约定尝试 index_repository(mode=full, persistence=false)，但 codebase-memory MCP 连接已关闭并返回 Transport closed；未重复调用，待服务恢复 后可再刷新本地索引，不影响运行代码。