docs(迭代09/10): Tab 设置统一管理 + UI 主题适配 全量文档
迭代09 (R-011 Tab 设置统一管理): - 需求 R-011 (定稿 Q1-Q5) + 需求池索引 - 计划 PLAN-010 + 迭代09 四件套 (目标/技术方案/验收/复盘) - 约束: 产品约束-009 / UI约束-003 / 技术约束-014 - UI约束-002 修订: 通用设置→Tab 设置 迭代10 (R-012 UI 适配 DSH 主题): - 需求 R-012 (定稿: 暂定跟随系统) + 需求池索引 - 计划 PLAN-011 + 迭代10 四件套 - 约束: UI约束-004 (主题适配约定)
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
# 技术实现方案：10-UI 适配 DSH 主题
|
||||
|
||||
> 迭代编号：10 ｜ 依据：PLAN-011、R-012
|
||||
|
||||
## 1. 主题机制（已查明）
|
||||
|
||||
- 宿主深色主题挂 `body[data-ds-dark-theme]`；
|
||||
- 宿主注入 `--dsw-*` CSS 变量（定义在宿主 runtime，随 light/dark/system 切换）；
|
||||
- 插件内联 style 直接引用 `var(--dsw-alias-xxx)` 即可自动适配。
|
||||
|
||||
## 2. 语义映射（实施基准，来自 R-012）
|
||||
|
||||
```
|
||||
背景: #fff(表面) → var(--dsw-alias-bg-layer-1)
|
||||
遮罩: rgba(0,0,0,.4) → var(--dsw-alias-bg-mask-1)
|
||||
hover面: #f5f5f5 → var(--dsw-alias-interactive-bg-hover)
|
||||
激活绿底: #e8f5e9/#f1f8f2 → color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent)
|
||||
错误红底: #fdecea → color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent)
|
||||
信息蓝底: #e3f2fd → color-mix(in srgb, var(--dsw-alias-state-business-primary) 10%, transparent)
|
||||
主文字: #333/#222 → var(--dsw-alias-label-primary)
|
||||
次文字: #555/#666 → var(--dsw-alias-label-secondary)
|
||||
弱文字: #888/#999/#aaa → var(--dsw-alias-label-tertiary)
|
||||
蓝字: #1565c0 → var(--dsw-alias-state-business-primary)
|
||||
细线: #eee → var(--dsw-alias-border-l1)
|
||||
描边: #ddd/#ccc → var(--dsw-alias-border-l2)
|
||||
红(涨/错/删): #d32f2f/#c62828 → var(--dsw-alias-state-error-primary)
|
||||
绿(跌/成/主): #2e7d32 → var(--dsw-alias-state-success-primary)
|
||||
实心按钮字: #fff → var(--dsw-alias-button-contrast-fill)
|
||||
```
|
||||
|
||||
## 3. 替换细则
|
||||
|
||||
- 替换范围：inline style 对象、模板字符串中的颜色字面量；
|
||||
- `color-mix(in srgb, var(--xxx) 10%, transparent)` 用于需要「淡底 + 文字同色」的提示/激活态；
|
||||
- 带透明度的原色（如 rgba(255,215,0,.5) 价格闪动高亮）保留动画语义，改 `color-mix(in srgb, var(--dsw-alias-state-warn-primary) 50%, transparent)`；
|
||||
- 注释中色值仅作说明可保留（不影响运行，验收时以无运行色为准）；
|
||||
- 每文件替换后 `node --check` 校验 JSX 语法。
|
||||
|
||||
## 4. 风险
|
||||
|
||||
- **语义偏差**：个别颜色无法精确定位语义 → 保留原色并在验收清单标注，交老师确认；
|
||||
- **color-mix 兼容性**：现代浏览器（Chrome 111+/Safari 16.2+）支持，DSH 目标为 Chromium 系，可接受；
|
||||
- **fallback**：`var(--xxx, <原色>)` 提供兜底，宿主 token 缺失时视觉不变（更安全）。
|
||||
@@ -0,0 +1,38 @@
|
||||
# 迭代复盘：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 值），个别较浅卡片阴影在深色下可能几乎不可见——可后续微调。
|
||||
@@ -0,0 +1,18 @@
|
||||
# 迭代目标：10-UI 适配 DSH 主题（浅色 / 深色 / 跟随系统）
|
||||
|
||||
> 迭代编号：10 ｜ 创建：2026-09-02 ｜ 状态：进行中
|
||||
> 依据计划：PLAN-011 ｜ 需求：R-012（已定稿，2026-09-02，暂定跟随系统）
|
||||
|
||||
## 目标描述
|
||||
|
||||
神之一手客户端 UI 全部硬编码色值替换为宿主 `--dsw-*` token，使插件在 DSH 浅色 / 深色 / 跟随系统主题下均可读、协调，随主题自动切换。
|
||||
|
||||
## 目标分解
|
||||
|
||||
1. 10 个文件 141 处硬编码色按语义映射替换为宿主 token / color-mix；
|
||||
2. 涨跌红涨绿跌 → 宿主 state-error/success；主按钮/徽标/提示底色 → 宿主语义色；
|
||||
3. 构建 + typecheck + 深浅主题人工验收。
|
||||
|
||||
## 对老师的配合需求
|
||||
|
||||
- 验收：DSH 设置切换 浅色/深色/跟随系统，检查各页面可读性与协调性。
|
||||
@@ -0,0 +1,22 @@
|
||||
# 验收标准：10-UI 适配 DSH 主题
|
||||
|
||||
> 迭代编号：10 ｜ 依据：PLAN-011 验收要点 + R-012
|
||||
|
||||
## 验收标准线
|
||||
|
||||
1. 浅色主题下插件各页面观感与现状基本一致（无突兀色差）；
|
||||
2. 深色主题下所有页面可读（背景/文字/边框/按钮/涨跌/徽标/提示/下拉菜单协调）；
|
||||
3. DSH 设置切换 浅色/深色/跟随系统 实时生效；
|
||||
4. 涨跌色（红涨绿跌）在深浅两主题下均醒目可辨；
|
||||
5. 运行代码无残留硬编码色（#xxx / rgb / rgba），注释可留；
|
||||
6. 布局与交互不变（仅色值）；
|
||||
7. build + typecheck 通过。
|
||||
|
||||
## 验收方法
|
||||
|
||||
- build + typecheck；
|
||||
- 老师切 DSH 浅/深主题人工检查：设置页（Tab 设置/策略分组/QMT 卡片）、全部持仓、交易记录、策略持仓、会话头部 QMT chip 下拉、Toast。
|
||||
|
||||
## 验收目标
|
||||
|
||||
- 7 条验收线通过，迭代 10 标记「验收通过」，R-012 更新实现状态。
|
||||
Reference in New Issue
Block a user