核心是用CSS自定义属性抽离可变值并在根元素或主题容器上批量切换，通过data-theme选择器覆盖变量，组件直接使用var()引用，配合语义化命名、对比度校验与初始HTML设置避免FOUC。
用 CSS 自定义属性（CSS Variables）管理主题色
多主题样式的核心不是写多套 class，而是把颜色、间距、字体等可变值抽成 --primary-color 这类自定义属性，在根元素或主题容器上批量切换。浏览器原生支持，无需构建时处理，运行时也能动态换肤。
关键点：:root 定义默认主题，再用 [data-theme="dark"] 或 .theme-dark 选择器覆盖变量值。所有组件直接使用 var(--primary-color)，不硬编码颜色值。
- 避免在
:root里写具体颜色值，改用语义化命名：如--color-bg、--color-text-primary，而非--bg-blue-50 - 深色主题不要只改背景，必须同步调整文字对比度——
--color-text-primary在暗背景下应为浅灰（如#f0f0f0），而非纯白（易眩光） - 慎用
!important覆盖变量；若需局部覆盖，优先用更具体的选择器（如.card[data-theme="high-contrast"]）
主题切换时避免样式闪烁（FOUC）
用户点击“切暗色”后页面闪一下白底黑字，是因为新主题 CSS 还没加载完，浏览器先渲染了旧样式。本质是 DOM 更新与 CSS 变量注入的时序问题。
解决方案不是加 loading，而是让初始 HTML 带上正确 data-theme 属性：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- 服务端渲染（SSR）：根据用户偏好或 UA，在 HTML 标签上直接输出
- 客户端首屏：JS 在
执行前，用内联脚本读取 localStorage 并同步设置document.documentElement.setAttribute('data-theme', '...') - 禁止在 CSS 中用
@media (prefers-color-scheme: dark)自动切主题——它仅响应系统设置，无法和用户手动选择同步
主题色生成与可访问性校验
一套可用的主题不能只靠设计师给几个 hex 值。主色确定后，必须程序化生成配套色板，并验证对比度是否达标（WCAG AA/AAA 要求文本与背景对比度 ≥ 4.5:1）。
推荐做法：
- 用工具（如 WebAIM Contrast Checker）校验关键组合：
--color-text-primaryvs--color-bg、--color-linkvs--color-bg - 避免手写
hsl(200, 50%, 80%)这类值——用 CSScolor-mix()或 JS 计算衍生色（如color-mix(in srgb, var(--primary-color), white 80%)生成浅色按钮背景） - 禁用纯黑（
#000）和纯白（#fff）作大面积背景——深色主题用#121212，浅色用#f9f9f9更柔和
:root {
--color-bg: #ffffff;
--color-text-primary: #1a1a1a;
--color-primary: #0066cc;
}
[data-theme="dark"] {
--color-bg: #121212;
--color-text-primary: #e0e0e0;
--color-primary: #2196f3;
}
body {
background-color: var(--color-bg);
color: var(--color-text-primary);
transition: background-color 0.2s, color 0.2s;
}
真正难的不是写几组变量，而是确保每个组件都尊重这些变量，且在主题切换后不破坏布局（比如深色模式下图片没加 filter: brightness(0.9) 导致过曝）。主题不是颜色开关，是整套视觉契约的执行。
