BUG-0394project-13中已修复frontend-ux

引用未定义的 CSS 变量 var(--color-text) 使深色主题下文字与背景同色（对比度约 1.05:1）

发现：2026-10-03验证：2026-10-09置信度：90%

症状

AI 助手面板的「智能诊断/即时答疑/考前陪练/自适应刷题」等标签在深色主题下完全看不清（文字与背景同色）。

根因

主题的「兼容旧变量名」桥接层只定义了 --color-text-primary/-secondary/-muted，没有 --color-text。组件写 var(--color-text, #171717)，浏览器取 fallback 近黑色，而面板背景是深色 #0F172A，于是文字几乎不可见。同一类隐患共有 6 个变量只被使用、从未定义（--color-surface-muted、--color-bg-page、--color-bg-tertiary、--color-danger、--color-warning、--color-accent-soft），且部分使用点连 fallback 都没写，会退化成透明。

修复方案

①把两处 var(--color-text, #171717) 改为 var(--color-text-primary, #F1F5F9)；②在 :root 桥接层补齐 6 个缺失变量（--color-surface-muted:var(--bg-tertiary)、--color-bg-page:var(--bg-primary)、--color-bg-tertiary、--color-danger:var(--danger)、--color-warning:var(--warning)、--color-accent-soft:color-mix(in srgb, var(--brand-300) 18%, transparent)）；③加回归测试：静态断言组件源码不得出现 var(--color-text 前缀（JSDOM 不解析 CSS 变量，渲染测试抓不到，但「引用了未定义变量名」在源码层是确定的）；④全仓扫描建立「使用的 --color-* 变量是否都已定义」的一致性检查。

错误签名

var(--color-text, #171717) 在 :root 中未定义；深色主题 --bg-primary:#0F172A 上文字取 fallback #171717，对比度≈1.05:1

技术信息

来源项目

project-13

涉及文件

frontend-web/src/components/AssistantFloating.tsx, frontend-web/src/index.css, frontend-web/src/components/__tests__/AssistantFloating.contrast.test.ts

标签

CSS变量, 深色主题, 对比度, 静默降级, project-13...