统一 Web UI 主题与颜色 Token 治理计划

[limityan]

背景

当前 Web UI 已经具备主题预设、运行时 CSS 变量注入、组件库 token 和 generated widget theme payload 等多条主题链路，但颜色定义分散在多个层级。组件样式、运行时主题服务、静态 token、widget iframe、编辑器/终端/语法高亮等专用区域之间缺少统一的治理边界，导致主题调整、视觉一致性验证和后续维护成本持续上升。

这个 issue 是主题与颜色 token 治理的顶层规划入口，用于描述背景、问题、核心方案、风险和关键里程碑。它不用于维护逐项进度，也不用于记录具体 PR 列表。后续 PR 可以引用此 issue 作为背景，但不应使用自动关闭关键字关闭它。

核心问题

1. 颜色字面量和 fallback 分散在大量组件文件中，同一语义角色存在多种写法，容易形成隐性的第二套色板。
2. 静态 token、运行时 ThemeService 注入变量、generated widget payload 暴露变量之间没有完全统一的注册契约，某些 UI 形态可能依赖局部 fallback 或运行时偶然存在的变量。
3. 近似色、重复色和历史命名 alias 混在一起，缺少判断标准。直接合并可能削弱区域边界、交互状态、状态语义、diff/git 语义或主题个性。
4. editor、terminal、Mermaid、syntax、diff、generated widget 等专用视觉域与通用 app token 的边界不够清晰，容易在“减少色值数量”时被错误归一。
5. 当前缺少可重复的审计工具和颜色预算约束，新增组件仍可能继续引入 raw color、局部 fallback 或未登记的 token 名称。

核心解决方案

采用分层 token 治理模型：

• Primitive palette：承载基础 hue、neutral、alpha ramp，不直接作为普通组件的业务语义色使用。
• App semantic token：承载背景、文本、边框、状态、交互、intent 等产品级语义，是普通 UI 的默认使用层。
• Component token：只在通用 semantic token 无法表达组件契约时使用，例如 Flow Chat、tool card、diff/git、widget frame、editor/terminal 等。
• Compatibility alias：保留历史命名和迁移期别名，先补齐契约再逐步迁移调用点，避免删除 fallback 后造成早期渲染、嵌入式渲染或隔离 iframe 样式丢失。
• Exception namespace：为 editor、terminal、syntax、diff、Mermaid、theme personality 等专用色板建立明确例外空间，避免它们被错误压缩到普通 app token。

治理原则：

• 极其相似、肉眼难以区分且语义一致的颜色可以直接合并。
• 其他近似颜色必须有明确依据，包括语义角色、相邻显示风险、状态区分、数据含义、主题覆盖和可访问性影响。
• 目标是减少色值数量，但不是抹平有用户理解价值的视觉差异。
• 一个应用的色值数量应有明确上限，新增 raw color 或 component token 必须能说明语义和边界。

相关风险

• 相邻 surface 的近似背景色被错误合并，可能导致 panel、card、input、canvas、floating overlay 等区域边界变弱。
• hover、active、selected、focus、disabled、loading、drag-over 等状态色被合并，可能削弱交互 affordance。
• success、warning、error、info、destructive、git/diff 等 intent 或数据语义被过度归一，可能影响用户判断。
• 静态 token、运行时注入和 widget payload 不一致，可能在 iframe、静态渲染、早期渲染或主题切换场景下出现 UI 差异。
• 大规模迁移 PR 容易产生 review 疲劳，导致视觉回归、contrast 回归或专用色板误迁移漏审。
• 过早启用严格 CI 约束可能被历史债务阻塞；过晚启用约束则可能继续新增同类问题。

关键里程碑

1. 建立颜色审计基线：统计 raw color、fallback literal、token 使用、未定义 token、重复色、近似色和高风险 surface。
2. 明确 canonical token 契约：对齐静态 token、运行时主题注入和 generated widget payload，补齐兼容 alias。
3. 迁移精确重复项：优先处理完全重复、格式差异、历史 alias 和明确等价 fallback，不改变用户可见视觉语义。
4. 收敛组件 fallback：按 component-library、Flow Chat、tool card、review panel、git/diff、widget 等 surface 分批迁移。
5. 抽取必要 component token：为高密度或专用 UI surface 建立清晰的组件级 token，而不是让组件继续携带 raw color。
6. 审慎合并近似色：每个非完全等价合并都需要调用点、相邻关系、状态语义和视觉证据支持。
7. 建立防回退约束：在迁移期使用 baseline-aware audit，逐步阻止新增普通组件 raw color、未登记 token 和无依据的 fallback。

[limityan]

当前关联 PR 的上下文补充

关联 PR：#1195

本评论只记录当前 PR 对该主题治理计划的首轮落地信息，方便后续理解背景；它不是进度表，也不表示该顶层 issue 已完成。

关键变更

• 新增主题颜色审计脚本，用于统计 raw color、fallback literal、组件非 token 色值、近似色候选和未定义或动态定义的 CSS 变量。
• 新增主题与颜色 token 优化方案文档，明确分层 token 模型、近似色合并规则、风险清单、关键里程碑和 review checklist。
• 对齐静态 token、运行时 ThemeService 注入变量和 generated widget theme payload，补齐一批历史命名 alias 与 app 级常用 token。
• 将大量完全重复或低语义风险的硬编码颜色、白/黑 overlay、root-token fallback palette 迁移到 canonical token 或明确 alias。
• 保留错误边界、tool card error boundary、static widget HTML、generated widget iframe 等隔离或早期渲染边界的关键 fallback。
• 复核动态 CSS custom property key，确认新增动态 key 仅来自类型化 theme config map；同时补齐 --color-primary-rgb 的静态定义、runtime 传递和使用点 fallback。

收益

• 减少普通 UI 组件中分散维护的颜色字面量和 fallback 色板，降低主题调整时的跨文件修改成本。
• 让静态样式、运行时主题切换和 widget iframe 三种形态具备更一致的 token 契约，降低某些 UI 形态漏样式的风险。
• 为后续迁移提供可重复审计指标，使“减少色值数量”可以被量化，而不是依赖人工印象。
• 明确近似色不能无依据合并，保护相邻区域、交互状态、git/diff 语义、editor/terminal 专用色和主题个性。
• 给后续 CI 或 baseline-aware audit 约束提供落点，便于逐步阻止新增普通组件 raw color。

遗留风险

• 仍然存在大量历史 raw color 和 component/non-token 色值；当前 PR 只是首轮契约对齐和低风险迁移，尚未完成全部收敛。
• 近似色合并仍需要按 surface 做视觉证据复核，尤其是 Flow Chat、tool card、review panel、git/diff、editor、terminal 和 generated widget。
• 部分历史 alias 会继续存在一段迁移期，后续需要明确哪些是长期语义 alias，哪些只是兼容 alias。
• 当前审计主要覆盖静态代码和 token 注册关系，不能替代 light/dark theme、hover/active/selected/focus/error 等状态下的截图或可访问性复核。
• 若后续过早启用严格失败型检查，可能被历史债务阻塞；更合适的方式是先使用 baseline-aware 规则阻止新增问题。

[limityan]

当前关联 PR 的上下文补充

关联 PR：#1199

本评论只记录当前 PR 对主题治理计划的本轮落地信息，方便后续理解背景；它不是进度表，也不表示该顶层 issue 已完成。

关键变更

• 继续扩大 Phase 3 fallback 迁移范围，覆盖 shared UI、Flow Chat、tool cards、git/diff 相邻 UI、config surface、editor/markdown surface 和 generated widget theme payload 边界。
• 在 tokens.scss 中补齐 Flow Chat card/control/code/Markdown spacing 以及 tool-card header/action 的 root 契约，把大量 selector 级重复 fallback 收回到统一 token。
• 在 themePayload.ts 中补齐 typography、opacity、spacing、Flow Chat、Markdown 和 tool-card 变量，减少 app surface 与 generated widget surface 的 token 漏传。
• 保留 generated widget iframe、component preview、global root、Markdown mono、DotMatrix loader、pet size、动画 index 等真实边界或动态/local fallback。
• 本次独立复核新增修复 9 个“无 fallback 且无全局/运行时定义”的 token 使用：将 --line-height-normal、--shadow-md、--border-heavy 等收敛到既有语义 token；将 Git graph selected row 从未定义的 --color-selected 改为与 selected hit-area 一致的 --color-accent-100。
• 对 tool-card error boundary 补语义 fallback 链，保持异常 UI 可读，同时不重新引入颜色字面量 fallback。
• 复核动态 CSS key：--card-index、--char-index、--group-color、--tag-color、--member-accent、pet dimensions、--dm-cell、--dm-gap 等仍有运行时或组件局部设置路径，没有被本轮误删。

收益

• var(--token, fallback) 总量从上一版 refactor(web-ui): continue theme token fallback migration #1199 的 340 继续降到 328；相对更早的本 PR 扩容基线 1504，累计减少 1176。
• var(--token, fallback-color) 字面量继续保持 0；此前扩容基线是 98。
• PR 改动文件中的无定义 no-fallback token 从复核发现的 9 个降到 0。
• component/non-token color occurrences 保持在 1760，没有为了追求数量而扩大近似色合并范围。
• Flow Chat、tool card、Markdown/code block、config 表单和 widget payload 的尺寸/排版 token 更集中，减少同一默认值在多个 selector 中重复维护。

遗留风险

• 近似色候选仍未做大规模合并；需要按相邻 surface、交互状态和主题形态逐个拿视觉证据后再处理。
• 剩余 fallback 的前排主要是 widget iframe 根默认、动态动画 index、数据驱动颜色、pet 尺寸、DotMatrix 局部尺寸、Markdown mono 边界等，不适合只凭静态扫描删除。
• --color-shadow、--core-accent、--border-light、--color-border-default 等局部/历史 token 仍需后续判断是转成 app semantic token、component token，还是继续作为局部 override。
• 当前验证覆盖静态审计、类型、lint 和测试；不同主题下的 Flow Chat、tool card、generated widget、editor/markdown surface 仍建议后续做 focused visual review。

[limityan]

Follow-up PR: #1201

This follow-up continues the P3 theme-token migration after #1199.

Key changes

• Added --markdown-font-mono as a canonical markdown/code font token, wired through ThemeService, static tokens, and generative-widget payload export.
• Removed another broad set of redundant fallback chains across app scenes, component-library controls, flow chat surfaces, editor styles, tool cards, and config UI.
• Replaced obsolete or undefined historical keys with canonical semantic tokens, including --border-color-light, --element-bg-muted, --color-bg-input, --border-soft, --color-surface-base, --color-accent-rgb, semantic RGB aliases, secondary border aliases, and focus/error surface aliases.
• Preserved dynamic/local or boundary defaults where fallback behavior is still intentional, including runtime group/card keys, Markdown schema variables, preview/startup/iframe/error-boundary paths, and agent companion sizing variables.

Benefits

• Theme audit fallback occurrences reduced from 328 after refactor(web-ui): continue theme token fallback migration #1199 baseline to 187 in refactor: expand web theme token contract migration #1201.
• Generative widget payload remains deduplicated: 265 tokens, 265 unique, 0 duplicates.
• More UI surfaces now rely on the same canonical root token contracts instead of component-local historical names.

Residual risks

• Component-library controls now depend more directly on root theme token bootstrap. This matches BitFun runtime expectations, but standalone embedding must still load token CSS or provide equivalent root variables.
• Remaining hard-coded/near colors are intentionally not merged in this PR unless they had a clear semantic replacement; reducing those further needs per-area visual evidence to avoid removing intentional region/status distinctions.
• Remaining fallback hotspots are mostly dynamic keys or boundary fallbacks; removing them should be handled only after confirming the host always supplies those variables.

[limityan]

本轮已更新 PR #1201，范围从单纯 fallback 清理扩大到主题 token 契约与审计能力加固。

关键变更：

• 增强 theme:color-audit：现在区分 contract-defined、runtime/inline-defined、dynamic family、fallback-only unresolved、required unresolved、cross-file non-contract，并单独列出动态输入和组件私有变量。
• 扩展 tokens.scss / ThemeService / generative widget payload 的契约变量，覆盖 surface/bg/semantic/border/z-index/scrollbar/glass/motion/tool-card/NavPanel 等稳定别名。
• 继续移除 app shell、component-library、Flow Chat、tool cards、config、Git views、generative widget 等范围内的稳定 fallback。
• 修复或收敛 --tag-color、--color-surface、--color-text、--color-background 等游离/历史泛化 key。
• 保留 --card-index、--group-color、--tag-color 等动态输入，以及 editor/config/review-team 等组件私有变量，避免把用于区分 UI 状态或局部布局的 key 误提升为全局主题 token。

收益：

• Fallback var occurrences 从 refactor(web-ui): continue theme token fallback migration #1199 后的 328、本轮开始前的 187 降到 53。
• requiredMissing=0，当前没有大量真实未定义且必须存在的 CSS var。
• 剩余跨文件非契约 key 被审计拆分为 3 个动态输入和 9 个组件私有变量，后续可以逐项判断是否提升，而不是继续靠人工 grep。
• tool-card 字体上提时保留了原有命令字体栈，降低用户可见的字体漂移风险。

遗留风险：

• 剩余 53 个 fallback 中包含 preview sandbox、动态动画序号、Markdown/schema fallback、组件独立渲染边界等，不应批量删除。
• 剩余非契约组件私有变量仍需按具体场景评估；例如 editor 双实现共享、config/review-team 局部布局变量可能不适合进入全局主题契约。
• 仍未合并“近似但有语义差异”的颜色；后续颜色数量收敛需要按相邻 UI 区域和状态语义逐项取证。
• generative widget 依赖 payload 提供稳定主题变量，本轮已扩展 payload 并通过 build，但后续新增 iframe 内 token 时仍需要同步 payload 列表。

验证：

• pnpm run theme:color-audit
• git diff --check
• pnpm run lint:web（仅既有 fast-refresh warnings）
• pnpm run type-check:web
• pnpm --dir src/web-ui run test:run（201 files / 1100 tests）
• pnpm run build:web（通过；保留既有 Vite warnings）

[limityan]

本轮关联 PR：#1211

关键变更：

• 将一批精确等价的 Web UI 颜色字面量迁移到已有 CSS/SCSS token，覆盖 app、component-library、flow_chat、shared context 与 tools 局部样式。
• 更新治理基线：app UI 色值出现次数 1683 -> 1612，唯一色 742 -> 727；token-equivalent literal 194 -> 127，唯一值 54 -> 39。
• 保留动态色值、语法/终端/主题预设、生成式 widget fallback、近似但非同值色，以及会参与 alpha 拼接的颜色 key。

收益：

• 进一步降低主题色值游离度，并收紧后续治理审计门槛。
• 保持 unresolved / fallback-only / required-missing vars 为 0，未扩大动态 key 或私有 key 债务。

遗留风险：

• 剩余高频 alias 多数来自动态颜色表、语法高亮、注入脚本、主题 fallback 或业务语义色，后续合并需要逐项证明用户层面不会丢失区分度。
• 仍存在 3 个已 allowlist 的动态输入 key 和 12 个跨文件非 contract key，本轮未改变这些边界。

[limityan]

PR #1211 has been expanded with the next two planned cleanup rounds.

Key changes:

• Promoted/renamed the 12 previously allowed non-contract CSS vars into governed surface/component contracts.
• Removed stale non-contract allowlists and tightened the baseline to require nonContractCrossFile, nonContractDynamicInputs, and nonContractCssPrivate to remain at 0.
• Preserved identity-bearing dynamic colors: mission-control group colors and inline context tag colors remain runtime inputs, only the keys are now governed.
• Removed an unused group-color-rgb dynamic style path instead of promoting it as a dead token.

Measured benefit:

Metric	Before	Current PR
App UI color occurrences	1683	1609
App UI unique colors	742	727
Token-equivalent app literal occurrences	194	127
Token-equivalent app literal unique colors	54	39
Fallback var occurrences	34	31
Non-contract cross-file vars	12	0
Non-contract dynamic input vars	3	0
Non-contract component-private vars	9	0

Residual risk:

• Near-color pairs are still intentionally not mass-merged without surface-by-surface evidence.
• Theme presets, syntax highlighting, terminal palettes, injected debug scripts, and generated widget payload fallbacks remain outside this PR.
• Review-team extra-member fallback now uses a governed neutral surface token; current consumers treat it as a CSS color string, and no hex parsing contract was found.

[limityan]

PR #1211 update after the latest strict architecture review:

• Preserved the Review Team extra-member default accent as the original fixed #64748b data value, instead of passing a CSS var through shared service/manifest defaults. This avoids theme-dependent identity color drift and keeps UI token usage out of the review-team data contract.
• Removed redundant local --inline-context-tag-color defaults from UserMessage CSS/SCSS after confirming the root token contract and dynamic inline tag colors cover the active rendering paths.
• Re-ran the token/key audits: old non-contract key names no longer have source references, promoted keys have root defaults and consumers, and governance still requires unresolved/fallback-only/required-missing and all non-contract categories to stay at zero.
• Current measured benefit in PR scope: app UI color occurrences 1683 -> 1610, app UI unique colors 742 -> 727, token-equivalent app literal occurrences 194 -> 129, fallback var occurrences 34 -> 31, and non-contract key categories 12/3/9 -> 0/0/0.
• Residual risk remains intentionally bounded: near-color theme preset decisions, syntax highlighting, terminal palettes, injected debug scripts, generated widget fallback payloads, and semantic identity colors are still deferred unless they are exact or contract-equivalent.

Latest pushed head: bc818bf7; GitHub Actions run 27550101384 passed: Frontend Build, Rust Build Check (ubuntu-latest), Rust Build Check (macos-15), and Rust Build Check (windows-latest).

[limityan]

Follow-up PR: #1215

Key changes:

• Expanded token-backed color migration across component-library primitives, Flow Chat input/tool-card surfaces, and Git UI surfaces.
• Added scoped aliases for tool-card positive/write states, Flow Chat inline/copy success states, and GitGraph lane colors.
• Preserved boundary/identity colors where merging could change user interpretation: debug injected scripts, syntax palettes, TextStrokeEffect, language identity colors, agent capability maps with hex alpha concatenation, and generative widget iframe fallbacks.

Measured benefit:

Metric	Before	After
Component/non-token color occurrences	1610	1409
Unique component/non-token colors	727	669
Token-equivalent app literal occurrences	129	91
Token-equivalent app literal unique colors	40	36

Residual risk:

• Remaining literals are still high because several domains need separate follow-up treatment rather than blind merging.
• Agent capability color tables need a dedicated refactor because current rendering derives alpha values by concatenating hex suffixes.
• Syntax/debug/widget boundaries should remain exception-reviewed unless their rendering contracts change.

[limityan]

PR #1215 已继续扩大范围，本轮关键增量：

• 覆盖 app chrome、workspace/context/notification、component-library 状态、旧 FlowChatCards、FlowChat/tool-card 状态、Git/editor UI、config/update 面板、NurseryView 语义状态等更大范围。
• 将重复的透明 accent/warning/error/success/purple literal 迁到现有 runtime token + color-mix(...)；对 inline context tag、Git graph lane、Git/terminal/risk-high 等身份色使用精确 surface token，避免近似合并导致用户误解。
• Git graph canvas 增加 CSS var 解析缓存，并在主题切换时重绘，避免 token 化后 canvas 颜色滞留旧主题。
• 审计基线继续收紧：component/non-token occurrences 1610 -> 1014，unique 727 -> 517；token-equivalent literals 129 -> 91，unique 40 -> 35；unresolved/non-contract CSS vars 保持 0。

遗留风险：

• contract token unique colors 上升到 691，原因是精确身份色被纳入显式 surface contract；这不是颜色合并，后续仍应继续按域收敛总色值上限。
• 已保留 agent/language/review-team/mini-app/TextStrokeEffect/debug injected/WorkspaceSessionBatch/syntax/theme preset/crash fallback 等身份色或动态路径，避免误合并导致 UI 语义混淆。
• 仍有 mermaid/syntax/theme preset/editor theme 等例外域和部分身份色未迁，需要后续按域单独设计上限和迁移策略。