# 暗金荒野主题调研记录

## 图片观察

- 原图尺寸为 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`；未重复调用，待服务恢复
  后可再刷新本地索引，不影响运行代码。