# 迭代复盘：10-UI 适配 DSH 主题（浅色 / 深色 / 跟随系统）

> 复盘日期：2026-09-02 ｜ 迭代状态：**已完成（老师确认）**
> 关联需求：R-012（UI 适配 DSH 主题，已定稿：暂定跟随系统）
> 关联计划：PLAN-011（计划-UI主题适配）

## 结果

迭代 10 达成：神之一手客户端 11 个文件共 141 处硬编码颜色全部替换为宿主 `--dsw-*` token（含 fallback），插件在 DSH 浅色 / 深色 / 跟随系统主题下自动适配；不自行维护主题偏好（跟随宿主）；仅色值 token 化，布局与交互不变。

## 过程事实

1. **需求定稿（R-012）**：老师提出适配 DSH 浅/深/系统主题 → AI 查明宿主机制（body[data-ds-dark-theme] + --dsw-* token，深色挂 data-ds-dark-theme、alias token 双值定义）→ 老师确认「暂定跟随系统」（D1-D5 + 语义映射表）；
2. **替换实施**：PriceCell / LoadState / Toast / PlaceholderTab / RangeSelector / AllPositionsTab / StrategyTab / TradeRecordsTab / QmtConnectionChip / SettingsSection 共 10 文件（+market 目录无颜色）；
3. **语义映射执行**：白底→bg-layer-1、淡灰底→bg-layer-2、hover→interactive-bg-hover、主/次/弱文字→label-primary/secondary/tertiary、边框→border-l1/l2/l3/l4、红（涨/删/错）→state-error-primary、绿（跌/成/激活）→state-success-primary、蓝（信息/业务）→state-business-primary、实心按钮字→button-contrast-fill、遮罩→bg-mask-1、阴影→shadow-lv3；
4. **淡色底**：激活/提示底色用 color-mix(in srgb, var(--语义色) 10-12%, transparent)，深浅主题自适应；
5. **验证**：typecheck + build 通过；headless Chrome 实证宿主 token 系统完整（238 处 dsw-alias 引用、浅/深双值定义、data-ds-dark-theme 选择器）；残留硬编码色 = 0。

## 经验教训（复盘沉淀）

### 1. 宿主主题机制：body[data-ds-dark-theme] + --dsw-* token（已实证）
- DSH 主题不是 data-theme 属性切换，而是宿主在深色时给 body 挂 `data-ds-dark-theme`，token 以「alias 链 → static 值」双主题注入（light: neutral-bluish-00 白系；dark: neutral-bluish-875 深系）；
- **沉淀**：插件适配宿主主题只须引用 `var(--dsw-alias-xxx, fallback)`，fallback 保证 token 缺失时浅色可用；不要自建主题偏好。

### 2. var() 带 fallback 是安全的迁移策略
- 每处替换写成 `var(--dsw-alias-xxx, #原色)`：宿主 token 定义齐全时自动适配；万一某 token 缺失（宿主版本差异），退回原浅色值不破相；
- **沉淀**：对宿主 token 的依赖一律带 fallback，兼容宿主版本演进。

### 3. 批量替换的 edit 冲突处理
- 多个相同 style 片段（如表头、输入框、删除按钮）导致 old_string 多处匹配：用 replace_all 处理真正相同的模式，或用带上下文的更精确 old_string；
- **沉淀**：批量替换前先 grep 去重确认唯一性，相同模式直接用 replace_all，不同上下文逐条处理。

## 遗留/后续

1. **语义色待老师验收**：深色下个别语义色（state-error 红 / state-success 绿在深色底的对比度、紫/蓝徽标）观感需老师切主题确认；若个别不满意可后续加 `--odl-*` 覆盖（D5 暂缓项）；
2. **color-mix 兼容性**：现代 Chromium 支持；若遇旧内核浏览器个别淡底失效，fallback 无（color-mix 无 fallback 语法）——可后续降级处理；
3. **Toast 样式**：随宿主语义色变化，实心绿/红底 + 白字在深色下对比度已由 token 保证；
4. **shadows**：boxShadow 用了 shadow-lv3 token（宿主完整 shadow 值），个别较浅卡片阴影在深色下可能几乎不可见——可后续微调。