admin/OpenTerminal
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases 17 Wiki Activity
Files
619e4ac57f801ca6bf5df45128d81ef094bb0113
OpenTerminal/docs/superpowers/specs/2026-10-16-theme-overhaul-design.md
T

18 KiB
Raw Blame History

主题系统全面改造（A+B+C）设计文档

  • 日期：2026-10-16
  • 状态：待交叉审核（未实现）
  • 范围：浅色主题可读性（A）+ 底色柔化（B）+ 全量 CSS/TSX 颜色变量化（C）
  • 关联：docs/ROADMAP.md、AGENTS.md「主题机制」章节（M4 需同步更新）

1. 背景与问题

用户主诉：白色主题下整体刺眼，终端内大量文字看不清（截图为 GitHub Light 下运行 Claude Code 的实际效果）。

1.1 根因清单

# 根因 位置 影响
R1 内置浅色主题 ANSI 调色板是暗底色直接搬来的 src/shared/theme.ts 终端内 16 色大半不可读
R2 drawBoldTextInBrightColors: true 写死 TerminalView.tsx:864 粗体强制跳到 bright 变体，放大 R1
R3 minimumContrastRatio 仅背景图模式开 4.5，平时恒 1 TerminalView.tsx:869,1268 xterm 渲染时对比度兜底完全关闭
R4 antd 写死 darkAlgorithm main.tsx:227 浅色下弹层/边框/hover 按暗色派生
R5 CSS/TSX 194 处真硬编码颜色（另有 122 处 var() 兜底值） 见 §3 清单 白底白字、灰字对比不足、深色面板突兀
R6 GitHub Light 纯 #ffffff 铺满终端+chrome+antd 表面 theme.ts:298 刺眼
R7（外部） Claude Code 等 TUI 经 ConPTY 拿不到真实底色，按暗色出图 应用侧，不可控 只能靠 R3 的渲染时兜底

1.2 关键实测数据（WCAG 对比度）

GitHub Light（bg #ffffff）16 色中 10 个 < 3:1：brightWhite 1.00（白字白底）、brightYellow 1.06、brightCyan 1.24、brightGreen 1.38、white 1.69、yellow 1.85、brightMagenta 2.26、green 2.41、brightRed 2.75、brightBlue 3.89。仅 fg/black/blue/red/brightBlack 达到 4.5。

One Half Light（bg #fafafa）ANSI 15 色中 7 个 < 3:1（white 1.00、brightWhite 1.04、brightYellow 1.65、brightGreen 1.93、brightBlue 2.26、brightCyan 2.27、brightMagenta 2.82），13 个 < 4.5:1（另含 red/green/yellow/cyan/brightRed 3.0–3.5）；仅 magenta、brightBlack 达标（fg/black 同为 #383a42 达标）。

Solarized Light 未逐色测，其 bright 系列为 Solarized 体系的去饱和色，预计大部分达标；white #eee8d5 vs bg #fdf6e3 明显不足，需纳入统一修复。

2. 目标与非目标

目标

  1. 三套内置浅色主题下，终端与应用全部文字达到 WCAG AA（正文 ≥4.5:1，大字/图形 ≥3:1），以脚本验证。
  2. 浅色主题不再刺眼（柔化底色，见 §5.3）。
  3. 深色主题视觉零回归（语义色深色分支逐值对齐现状）。
  4. 建立语义 token 层 + fail-closed 防护测试，杜绝硬编码颜色再次积累。
  5. 主题切换时全 UI（终端、chrome、antd 弹层）一致跟随。

非目标

  • 不新增主题/柔化强度设置项（YAGNI）。
  • 不改关键词高亮引擎的着色算法（highlightThemeColors 跟随主题机制已存在，默认关，维持现状；预设颜色本身在浅色下的对比度由 R3 兜底，不单独重调）。
  • 不动 node_modules 内 xterm.css。
  • 不新增内置主题。

3. 现状盘点

3.1 硬编码分布（raw = 规则内真硬编码；fallback = var(x, 兜底) 内的值）

文件 raw fallback 备注
connections.css 26 1 最大真硬编码户
workspace.css 22 42 fallback 多为 --chrome-* 旧兜底
terminal.css 20 0 含白底隐形文字（:243/:312 #ffffff on 白）与深色工具条
sftp.css 18 17
global.css 16 0
theme/chrome.ts 16 0 混色锚点 #000/#fff，属算法参数，入白名单
monitor.css 15 12
settings.css 11 25
MonitorPanel.tsx 10 0 内联语义色
TerminalView.tsx 10 0 搜索高亮色 + 背景图深底衬 #0d1117（AGENTS.md 铁律，保留）
HighlightTab.tsx 9 0 预设规则色板，属数据非 chrome，入白名单
commands.css 8 0
highlight.css 6 18
ErrorBoundary.tsx 2 0
lock.css 2 7
main.tsx 2 0 antd token 的 mix() 失败兜底（暗色偏置，需顺手修正）
highlightEngine.ts 1 0 规则默认色，属数据，入白名单
合计 194 122

3.2 颜色族归类（按出现频次）

族 代表值 处数级 去向
中性灰文本 #cccccc #8a8a8a #9a9a9a #6a6a6a #d0d0d0 ~120（含 fallback） 文本层级变量
GitHub 暗色语法色 #3fb950 #f85149 #d29922 #58a6ff #e3b341 #f0a55a #3fd06a ~70 语义色变量
白色半透明叠加 rgba(255,255,255,.04–.2) ~20 hover/overlay 变量
深色面板 rgba(24,26,31,.85) #101418 #181818 少量 surface 变量
滚动条 rgba(125,145,170,.5) 4 scrollbar 变量
阴影 rgba(0,0,0,.4–.55) 少量 shadow 变量

3.3 失败模式

  1. 白底白字：terminal.css:243,312 的 color:#ffffff + 半透明白底、#8a8a8a 级灰字在浅色下 < 3.5:1。
  2. 暗底语法色硬上浅底：语义色全部取自 GitHub 暗色系（#3fb950 对白底 2.5:1）。
  3. 深色构件不随主题：搜索面板/工具条深色底在浅色窗口里成黑块（观感问题，可接受项，但颜色值需收敛进变量才可调）。

4. 总体架构

ThemeColors (L0 主题原始色, theme.ts)
  └─ chrome.ts (L1 派生: --chrome-* 现有 8 个 + 新增 L2 语义变量 --ot-*)
       ├─ global.css / 各 *.css 消费语义变量（本改造主体）
       ├─ main.tsx ThemedConfigProvider（按亮度切 antd algorithm）
       └─ semantic.ts（TS 常量，供 TSX 内联样式与 chrome.ts 共用单一来源）
  • 亮度判定抽为共享纯函数 isLightTheme(colors)（chrome.ts 内已有 chromeIsLight 私有逻辑，抽出导出，配表驱动测试）。
  • 语义变量一律带 fallback 写法（var(--ot-text-muted, #8a8a8a)），fallback 值收敛到受控常量清单（见 §7）。

5. 设计细节

5.1 L2 语义变量（新增，--ot- 前缀）

变量 用途 深色分支（=现值，零回归） 浅色分支
--ot-text 正文 主题 foreground 混黑加深至 ≥7:1
--ot-text-secondary 次要文本 fg 78% 透明（现 color-mix 值） 同式，校验 ≥4.5:1
--ot-text-muted 弱化文本（#8a8a8a 族） #8a8a8a mix(bg,#000,0.55) 级，≥4.5:1
--ot-surface 面板底 现 color-mix(fg 4–6%, bg) 同式反向
--ot-surface-raised 浮层/工具条底 rgba(24,26,31,.85) 等 rgba(255,255,255,.9) 级
--ot-hover 控件/行 hover 叠加 rgba(255,255,255,.04–.1) rgba(0,0,0,.04–.1)
--ot-border / --ot-border-strong 边框 现 --chrome-border 族 同式
--ot-success(+-fg) 成功/运行态（#3fb950 族） #3fb950（fg 亮化） 加深变体 ≥3:1（fg ≥4.5:1）
--ot-danger(+-fg) 危险（#f85149 族） 同上策略 同上
--ot-warning(+-fg) 警告（#d29922/#e3b341） 同上策略 同上
--ot-info(+-fg) 信息/链接（#58a6ff/#3b8eea） 同上策略 同上
--ot-scrollbar / --ot-scrollbar-active 滚动条 现 rgba(125,145,170,*) rgba(0,0,0,.25/.4) 级
--ot-shadow 浮层阴影 rgba(0,0,0,.4–.55) rgba(0,0,0,.12–.2)
--ot-focus-ring 焦点环 现 rgba(59,142,234,.18) 同值（蓝环两底均可读）

规则：

  • 语义色不是深浅共用一个值：深色分支锁定现值（零回归），浅色分支用 mix(现值, #000, t) 自动加深并经对比度脚本校验，t 在 semantic.ts 里按色相手调一次后固化。
  • --tab-accent 机制不动（已有 -fg 明暗适配）。
  • :root 同步写 color-scheme: dark | light（chrome.ts 按分支写入）：原生滚动条、表单控件、::selection 等跟随明暗，避免变量化了的部分被原生控件的不跟随出卖。

5.2 A：终端画布可读性（M0）

  1. 浅色调色板重做（theme.ts 三套）：

    • 规则：16 色逐个过对比度脚本，<4.5:1 的用 mix(原值, #000, t) 加深至达标（保留色相，t 固化进表）；white/brightWhite 在浅色主题一律重映射为中灰（提案：github-light brightWhite → #57606f，其余主题按各自 fg 深度取灰），不允许任何颜色与背景对比 < 4.5:1。
    • 达标用新增 tests/theme-contrast.mjs 固化（见 §7），调色板具体数值在实现期以脚本为准微调，本设计只锁规则与阈值。

  2. minimumContrastRatio（MCR）动态化——按「背景图 × 主题亮度」矩阵取值：

    场景 现值 新值
    背景图模式（任意主题） 4.5 4.5（不变，铁律）
    无图 · 浅色主题 1 4.5
    无图 · 深色主题 1 1（不变）

    构造（TerminalView.tsx:869）与热更（:1268）两处同步改；拼写用 minimumContrastRatio（AGENTS.md 已记 minContrastRatio 静默失效的坑）。此项是对 R7（应用输出 arbitrary truecolor 低对比色）的唯一渲染时兜底，浅色必须开。已验证（2026-10-16，node_modules 实查）：WebGL 渲染器自带完整对比度执行路径（addon-webgl.mjs 的 _getMinimumContrastColor → ensureContrastRatio，含 dim 的 halfContrastCache），且 drawBoldTextInBrightColors/minimumContrastRatio 变更会随 options 同步进 webgl 配置；rendererMode 默认 auto（webgl 优先、dom 回退），两条路径均执行 MCR，无死角。

  3. drawBoldTextInBrightColors：浅色 false、深色 true（维持现状），两处同改。

  4. antd algorithm（main.tsx）：按 isLightTheme 切 defaultAlgorithm/darkAlgorithm——antd（含 v6）没有 lightAlgorithm，浅色就是 defaultAlgorithm（已在 node_modules/antd/es/theme/index.js 核实导出仅有 default/dark/compact 三种）；colorBgContainer/colorBgElevated 的 mix() 失败兜底改为按亮度取 #f5f5f5/#1f1f1f 两套。

5.3 B：底色柔化（M0）

  • GitHub Light background #ffffff → #f6f8fa（GitHub 官方 light canvas 色），cursorAccent 同步；其余 15 色按 §5.2.1 重算。
  • One Half Light #fafafa、Solarized Light #fdf6e3 本身带色调，不动（避免拍脑袋改两套成熟主题的观感）。
  • 不加「柔化强度」设置。

5.4 C：清扫批次（M1–M3，每批独立提交、独立可回滚）

映射规则（机械执行）：

现值模式 替换为
#8a8a8a/#9a9a9a/#6a6a6a 文本 var(--ot-text-muted, …)
#cccccc/#d0d0d0 文本 var(--ot-text, …) 或 -secondary（按语境）
color-mix(fg x%, …) 文本 var(--ot-text-secondary/muted)
#3fb950 族 var(--ot-success) / -fg
#f85149 族 var(--ot-danger) / -fg
#d29922/#e3b341/#f0a55a var(--ot-warning) / -fg
#58a6ff/#3b8eea/#3fd06a(链接) var(--ot-info) / -fg
rgba(255,255,255,.04–.1) 控件 hover var(--ot-hover)
rgba(255,255,255,.16–.2) / 成块白色半透明面板 var(--ot-surface-raised) / var(--ot-border-strong)（按语境：描边用后者）
rgba(125,145,170,*) var(--ot-scrollbar*)
rgba(0,0,0,.4+) 阴影 var(--ot-shadow)

批次：

  • M1 基座：semantic.ts + chrome.ts 写 L2 变量 + isLightTheme 导出 + global.css + terminal.css + TerminalView.tsx 内嵌色 + ErrorBoundary.tsx + main.tsx 兜底。
  • M2 主工作区：workspace.css + connections.css + commands.css。
  • M3 功能面板：sftp.css + monitor.css + MonitorPanel.tsx + settings.css + highlight.css + lock.css。

白名单（防护测试豁免，§7）：semantic.ts 自身（它是语义色的定义处，扫描它等于扫描标尺）；theme.ts（内置调色板是主题数据）；global.css 的 :root 静态兜底块（chrome.ts 变量缺失时的暗色默认值）；chrome.ts 混色锚点（#000000/#ffffff，属算法参数）；TerminalView 的 xterm ITheme 搜索色（主题数据）、背景图深底衬 #0d1117 与 #00000000 透明色（铁律）；HighlightTab.tsx/highlightEngine.ts 的规则色（数据）。扫描器必须先剥离注释再匹配（terminal.css:16、highlightEngine.ts:17 的命中都在注释里），且正则覆盖 3/4 位 hex（#fff）。

5.5 兼容性

  • 用户自建 customThemes 不受影响（L2 从 ThemeColors 派生，无需迁移）。
  • ThemeEditor 只能编辑/新建 customThemes（已核实 ThemeEditor.tsx:70-74），改内置主题颜色无兼容负担；想要旧色的用户可在编辑器里以旧值建副本。
  • getThemeById fallback（DEFAULT_DARK）不变。
  • 纯渲染层改动，无 IPC/settings 结构变更；settings.terminal.themeId 语义不变。

6. 测试与验收

6.1 新增测试（fail-closed，沿用仓库表驱动风格）

  1. tests/theme-contrast.mjs：直接 import '../src/shared/theme.ts'（Node 22.18+ 原生类型剥离，同 terminal-cwd 等三测试的既有做法）。对每套内置主题：计算全部 16 色对 background 的对比度，浅色主题（isLight=true）每色 ≥4.5，深色主题仅断言 foreground ≥4.5（不约束暗色系既定美学）。另覆盖 isLightTheme 判定表。
  2. tests/css-theme-vars.mjs：扫描 src/renderer/src 全部 .css/.tsx/.ts，正则提取色字面量，白名单外一律 exit 1；var() 内 fallback 必须命中受控常量清单。接入 package.json test 脚本链（纯文件扫描，无需 esbuild bundle）。

6.2 既有回归

npm test（pretest typecheck + 22 个离线测试）全绿。

6.3 手工验收清单（每批 M1–M3 + M0 各跑一次）

三套浅色主题 × {终端（含 Claude Code 实跑）、设置弹层/下拉/Tooltip、SFTP 面板、监控面板、锁屏（含 .lock-screen-boot 启动闪层）、命令面板、连接侧栏、zmodem 传输弹层}；深色主题抽查同清单确认零观感变化；背景图模式抽查（深底衬铁律不破）；运行中明暗主题热切换各一次（chrome/antd/xterm 三路同步）。

6.4 性能

minimumContrastRatio=4.5 生产先例即背景图模式（已在线上跑）；实现时用诊断日志对比开关前后的渲染层 stall 事件与高频输出场景，数据记入 PR 描述。

7. 防护测试细则

  • 扫描正则：#[0-9a-fA-F]{3,8}\b 与 rgba?\(；var(...) 内命中归 fallback 规则，其余归 raw 规则。
  • 白名单按「文件 + 值」二元组维护在测试内（表驱动用例风格）。
  • 受控 fallback 清单：semantic.ts 导出的常量表，测试同时校验「CSS 里出现的 fallback ⊆ 清单」与「清单无死值」双向一致。
  • 里程碑 M4 收尾时把扫描基线清零：除白名单外 raw 计数必须为 0，此后新增硬编码直接红。

8. 里程碑与提交切分

里程碑 内容 提交 验收
M0 §5.2 + §5.3（调色板、两开关、antd 算法、柔化）+ theme-contrast 测试 1 个 主诉立解；深色零回归
M1 语义层基座 + global/terminal + TSX 内嵌 1 个 手工清单浅色全过
M2 workspace/connections/commands 1 个 同上
M3 sftp/monitor/settings/highlight/lock 1 个 同上
M4 css-theme-vars 测试 + 基线清零 + AGENTS.md「主题机制」重写 + docs/STATE.md 更新 1 个 npm test 全绿含新测试

每个里程碑独立可回滚；M0 可单独先行发版验证效果。

9. 风险与缓解

风险 缓解
WebGL 渲染器不执行 MCR 已排除（2026-10-16 实查 addon-webgl 源码，见 §5.2.2）
MCR=4.5 渲染性能 背景图模式生产先例；诊断日志实测；不行则浅色降 3.5 并记录取舍（4.5 仍为目标值）
深色回归 语义色深色分支锁现值 + 每批手工清单深色抽查 + diff 审查
加深算法破坏色相辨识（如 red 混成棕） t 按色相手调固化，不许纯算法一路推到底；脚本只做下限校验
用户依赖旧浅色配色 主题编辑器可建副本还原；CHANGELOG 注明
大批量 CSS 改动引入选择器/特异性事故 只改颜色声明值，不动布局/盒模型属性；AGENTS.md 已记 sftp grid 教训

10. 待拍板问题（交叉审核请逐条确认）

  1. 语义变量命名空间 --ot-*（提案）还是并入现有 --chrome-*？
  2. GitHub Light 柔化目标 #f6f8fa 是否接受？
  3. 深色主题是否也统一开 MCR 4.5（提案：维持 1，最小改动）？
  4. var() fallback 是否按 §7 收敛为受控清单（提案：是，M4 落地）？
  5. One Half Light / Solarized Light 底色维持不动（提案）？
  6. M0 是否单独先行发版，还是 M0–M4 一起发？

11. 对抗性审查记录（2026-10-16）

审查执行：独立审查子代理（环境故障未产出有效报告）+ 主会话逐项自行验证。以下发现已全部落入正文：

# 发现 级别 处置
1 antd 无 lightAlgorithm，浅色应为 defaultAlgorithm Important（真实错误） §5.2.4 已改
2 §5.2.2「深色 1（维持现状）」与背景图模式现状（深色+图=4.5）表述冲突 Important §5.2.2 改为显式矩阵
3 WebGL 渲染器是否执行 MCR 未验证（承重假设） Critical（假设） 已实查源码排除：addon-webgl 有完整对比度路径，§5.2.2 记录证据
4 两 xterm 选项运行时热设未验证 Important（假设） 已核实：options 同步进 webgl 配置；生产代码本就在热设 MCR
5 防护测试扫描器会误伤 semantic.ts/theme.ts/global.css 兜底块自身 Important §5.4 白名单已显式枚举
6 扫描器须剥注释、覆盖 3/4 位 hex Minor（实现细节） §5.4 已写明
7 One Half Light「9 个 <3:1」计数错误（实为 7 个） Minor（数据错误） §1.2 已改
8 原生控件（滚动条等）不随明暗 Minor（遗漏） §5.1 增 color-scheme
9 锁屏启动闪层、zmodem 等面板浅色表现未入验收清单 Minor 已入 §6.3 手工清单
Reference in new issue View Git Blame Copy Permalink