CSS变量是主题切换最优解，因其集中定义于:root、动态响应且免编译；错误做法是组件内定义变量，正确方式是全局声明+var()引用，并为每个变量设fallback值。
用 CSS 自定义属性（CSS Variables）管理主题色
主题切换的本质是批量替换颜色、字体、阴影等视觉变量，硬编码多套 CSS 文件维护成本高，且无法动态响应。CSS 自定义属性是当前最轻量、最可控的方案——所有主题值都集中定义在 :root 下，换肤只需修改这些变量值，样式自动重绘。
常见错误是把变量写死在组件级选择器里（如 .card { --bg: #fff; }），导致无法全局覆盖；正确做法是只在 :root 定义，并用 var(--bg) 在各组件中引用。
- 深色主题示例：
:root[data-theme="dark"] { --bg: #121212; --text-primary: #e0e0e0; --border: #333; --accent: #bb8f00; } - 浅色主题保持默认
:root值，或显式声明data-theme="light"分支 - 避免在 JS 中直接操作
style.color等内联样式，这会覆盖 CSS 变量优先级
JS 控制 data-theme 属性并持久化用户偏好
切换主题不是改几个变量就完事，必须同步更新根元素的 data-theme 属性（如 ），否则 CSS 选择器无法匹配生效。同时要保存用户选择，否则刷新后回到默认主题。
容易忽略的是系统偏好（prefers-color-scheme）与用户手动选择的优先级冲突：用户点了一次“深色”，但系统设为“自动”，下次打开可能又被拉回浅色。
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 读取本地存储：
localStorage.getItem('theme')，不存在则 fallback 到matchMedia('(prefers-color-scheme: dark)').matches - 写入时同时更新
document.documentElement.dataset.theme和localStorage - 监听系统变化：
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，但仅当用户未手动设置过主题时才响应
避免 CSS 变量未定义导致的样式断裂
当某个组件用了 var(--hover-bg)，但当前主题没定义这个变量，浏览器会按 CSS 级联规则回退到继承值或初始值（通常是透明、黑色或不可预期的颜色），造成按钮无悬停反馈、文字消失等问题。
这不是 bug，是 CSS 变量的默认行为。必须为每个变量提供 fallback 值，尤其在跨主题复用同一套组件时。
- 写法必须是：
background-color: var(--hover-bg, #e3f2fd);，括号内逗号后是兜底色 - 不要依赖“所有主题都定义了同名变量”这种假设，主题配置应视为不完整输入
- 可借助构建工具（如 PostCSS 插件）扫描缺失变量，但运行时仍需 fallback 保底
动画过渡与性能注意事项
直接切换 data-theme 会导致颜色突变，用户体验生硬。加 CSS 过渡看似简单，但 color、background-color 等属性对 CSS 变量的过渡支持有限——浏览器不会插值两个 var() 的计算结果，而是直接跳变。
真正能平滑过渡的是原生属性本身，所以关键在于：把变量映射到可动画的属性上，并控制过渡时机。
- 给
html或body加transition: background-color 0.3s, color 0.3s;，再确保变量实际作用于这些属性 - 避免在
transition中包含大量重绘属性（如box-shadow、transform），否则卡顿明显 - 深色模式下慎用
filter: invert(1) hue-rotate(180deg)类似 hack，它破坏文本可访问性且无法局部控制
