[wanchun]

背景

此前 FConfigProvider 的 theme prop 是死参数（applyTheme 收了不用），组件背景大量硬编码 var(--f-white)，暗色模式无从谈起。本 PR 采用 element-plus 路线（设计令牌全走 CSS 变量、暗色整组翻转）补齐暗色主题。

改动内容

一、表面色语义化（52 处 / 29 个样式文件）

• 组件背景使用的 var(--f-white) → var(--f-component-bg-color)
• 「彩底白字」「勾选标记」等 22 处前景用法保留 white（暗色下依然正确）
• componentBgColor 语义定为组件表面色：亮色 = white，暗色 = #1f1f1f

二、baseTheme 派生链暗色分派（非机械 tint↔shade 互换）

类别	亮色	暗色	理由
灰阶淡化（边框/次级文字/禁用）	tint 向白	shade 向黑	梯度方向一致
hover 强调	tint	tint 保持	正文已浅，hover 趋近白
active 按下	shade 加深	tint 提亮	加深不可见
fade 透明（遮罩/阴影）	fade(fontColorBase)	锚定 #0f1222	避免发灰发亮

布局反转/tooltip 底色暗色下显式定值；亮色路径逐锚点对齐旧实现（回归零差异）。

三、预设与接线

• 新增 _theme/dark.ts：fontColorBase: #e8ecf2 + bodyBgColor: #141414
• applyTheme 合并预设，用户 themeOverrides 优先；theme 参数从死参数变为生效
• FConfigProvider theme="dark" → 60+ CSS 变量整组翻转 + 容器挂 fes-dark class（作用域覆盖钩子）
• 新增 getThemeStyleTag()：SSR 首屏防闪白，从包具名导出

四、文档

configProvider 文档新增「暗色模式」章节（基础用法 / 跟随系统 / SSR 防闪白 / 深度定制）+ 可运行 demo。

验证

• dark-theme.spec（6 用例）：亮色基线无回归、灰阶梯度方向、遮罩锚定、hover 提亮、tooltip 可读性、覆盖优先级
• dark-mode.spec（7 用例）：CSS 变量真实翻转、class 钩子、overrides 优先、dark↔light 切换还原、子组件集成、applyTheme/getThemeStyleTag 单元
• 全量单测 2539/2539（main 基线 2525 + 新增 14）

已知限制（后续 PR）

• useTheme 为 shared composable，仅首个调用组件的 Provider 生效（已有 TODO，非本 PR 引入）
• 部分组件残留 #fff 硬编码（对比报告已列）建议独立 PR 清理

[wanchun]

Review 修复（第二轮独立 review 后）

1. componentBgColor 亮色回归

亮色路径恢复 main 的 tint(fontColorBase, 0.97) 派生（暗色保持 #1f1f1f）。用户覆盖 fontColorBase 继续联动组件底色，52 处替换点亮色输出与 main 一致。

2. carouselColor / carouselHoverColor 别名链断裂

恢复 main 的别名关系（shadowColorSm / maskColor），用户覆盖这两个变量继续传导到轮播箭头底色。新增别名传导回归用例。

3. LESS 注释乱码恢复

批量替换脚本经 PowerShell 管道时产生的 GBK 乱码（10 个文件），全部从 main 逐行恢复原文，仅保留功能性替换。全仓库扫描确认零残留。

4. 其他

• interface.ts：ThemeCommon 补 maskDarkColor、paddingXsmall 命名对齐（落实 PR 描述承诺）
• docs demo darkTheme.vue：getContainer 限定 demo 容器，不再污染整个文档站
• 新增 light-regression.spec.ts：复刻 main 全部派生公式逐变量断言零差异 + 别名传导用例（覆盖 41 个派生变量）

全量 2541/2541 通过

遗留 P2（建议后续 issue 跟进）

• resolveThemePreset 仅精确匹配 'dark'（'auto' 可作为后续扩展点）
• getThemeStyleTag selector 未转义（当前来源固定，理论风险）
• useTheme 共享单例在多 app / 嵌套 provider 场景的限制（见代码 TODO）

[wanchun]

第四轮独立 review 修复（26a531b1）

1. maskDarkColor / borderColorBase 恢复 main 的可覆盖语义

review 发现这两个变量在 main 位于 getDefaultThemeBase（可被 themeOverrides.common 覆盖），重写后被移入无条件派生区导致覆盖失效。已按 shadowColorSm 同款模式修复（base 值优先 + ?? 派生兜底），borderBase 字符串模板同步引用覆盖后值。新增覆盖传导回归用例。

2. interface.ts derivedColor 补 4 个缺失声明

hoverSuccessTextColor / hoverWarningTextColor / hoverDangerTextColor / hoverBaseTextColor——baseTheme 全部 40 个派生 key 现有类型声明。vue-tsc 通过。

3. dropdown / layout / menu 漏网乱码恢复（5 行注释）

第三轮已发现的三文件乱码，从 main 字节级恢复。全分支乱码/PUA 终扫 CLEAN。

全量 2542 用例：2541 绿 + 1 个已知 flake（onOk reject 节流轮询，单跑 13/13 绿）

---

四轮 review 汇总

轮次	发现	状态
一	componentBgColor 亮色回归、别名断裂、乱码 ×10	✅ fa5c4a1
二	IME 守卫（aria 侧）、inputInner 脏字节、漏网乱码 ×3	✅ 9338de0 / 26a531b
三	破坏性验证全部 P1 修复真实有效；亮色 65 key 零差异	✅ 通过
四	maskDarkColor/borderColorBase 覆盖收窄、接口缺 4 key、乱码 ×3 提交	✅ 26a531b

可合。