主题化必须从html语义标签和css作用域边界设计开始，用[data-theme]属性而非class控制主题，结合语义化标签分层、css自定义属性按角色命名、禁止dom重绘切换，才能稳定支撑多主题。
大规模中后台系统做主题化，不是靠改 color 或 background 临时覆盖就能落地的；真正能稳定支撑多主题、可维护、不崩 layout 的结构，必须从 HTML 标签语义和 CSS 作用域边界开始设计。
为什么直接用 class 命名主题会失控
很多团队早期用 theme-dark、theme-blue 这类 class 挂在 上，再写一堆嵌套选择器。结果是：新功能加个卡片组件，开发随手写 <div class="card">，样式却依赖 <code>body.theme-dark .card —— 一旦某处漏挂 theme class，或父级被 JS 动态移除，整个区域就回退到默认色；更麻烦的是，多人协作时没人敢删旧主题规则，CSS 文件半年涨到 8000 行。
根本问题不在“换色”，而在 HTML 结构没为多主题预留语义锚点。
- 避免把主题 class 塞进业务组件内部（如
<button class="btn theme-red"></button>），它该由容器统一注入 - 所有主题相关样式必须限定在
[data-theme]属性选择器下，不用 class，防止 class 冲突或遗漏 -
是唯一可信的根标识，JS 切换主题只改这一个属性，不操作 classList
<main></main>、<aside></aside> 等语义标签不是摆设，是主题作用域切分点
中后台页面通常有固定区块：顶部导航栏、左侧菜单、主内容区、右侧面板。如果全用 <div class="header"> 堆砌，主题色一换，你得挨个确认每个 <code>.header 是否都继承了 data-theme；而用语义标签后，CSS 可以自然分层：
html[data-theme="dark"] header { background: #1e1e1e; }
html[data-theme="dark"] aside { background: #252525; }
html[data-theme="dark"] main { color: #e0e0e0; }
好处是：语义标签本身不带样式，但天然具备 DOM 层级稳定性 —— 即使未来重构 sidebar 为 Web Component，只要它仍包裹在 <aside></aside> 内，主题规则依然生效。
-
<nav></nav>适合放全局导航，主题色需与权限状态联动（如禁用项灰度） -
<section></section>是主题色最常变动的区域，建议按功能模块加data-section="user-list"辅助控制粒度 - 避免在
<footer></footer>里塞业务按钮，它的语义是“文档结尾”，主题色应保持最低干预（仅文字/分割线）
CSS 自定义属性（--）必须按语义分组，而非按颜色值命名
写 --primary-blue: #1890ff 看似直观，但换主题时你要批量替换所有 blue → purple，且无法表达“这个蓝是按钮背景，那个蓝是链接悬停”。真正可持续的做法是：
:root {
--color-brand-primary: #1890ff;
--color-brand-secondary: #722ed1;
--color-text-primary: #333;
--color-text-secondary: #8c8c8c;
--color-bg-canvas: #fff;
--color-bg-surface: #f5f5f5;
}
这些变量名描述用途，不描述视觉值。深色主题只需重载：
[data-theme="dark"] {
--color-text-primary: #ffffff;
--color-bg-canvas: #1f1f1f;
--color-bg-surface: #2d2d2d;
}
- 变量名中禁止出现
dark、light、blue等具体值词，只保留角色（brand / text / bg / border） - 所有组件 CSS 必须用
var(--color-text-primary)，禁止硬编码#333 - 深色模式下，
--color-brand-primary可以不变（品牌色通常跨主题一致），但--color-bg-canvas必须变
主题切换时 DOM 结构不能重绘，否则表单状态、滚动位置全丢
常见错误是用 JS 渲染整页 HTML 模板来切主题 —— 用户正在编辑表格某行，切主题后 input 失焦、输入内容清空、当前 tab 重置。正确做法是只改根节点属性 + 同步更新 localStorage，让 CSS 自动响应：
function switchTheme(theme) {
document.documentElement.setAttribute('data-theme', theme);
localStorage.setItem('preferred-theme', theme);
}
// 页面加载时读取 localStorage，不触发重绘
const saved = localStorage.getItem('preferred-theme') || 'light';
document.documentElement.setAttribute('data-theme', saved);
关键约束：
- 主题切换函数不能调用
location.reload()，也不能用 innerHTML 替换 body - 所有动态组件（如 Vue/React）必须监听
attributeChangedCallback或 useMediaQuery，而非监听 class 变化 - 如果用了第三方 UI 库（如 Ant Design），务必关闭其自带主题 loader，改用 CSS 变量注入，否则两套主题机制打架
主题化真正的复杂点不在配色，而在于 HTML 结构是否经得起多次主题叠加、是否允许子系统局部覆盖、以及切换时能否保住用户当前上下文 —— 这些都得从第一个 <header></header> 标签的语义开始卡死。
