在Web开发中，让页面支持多种视觉主题已经成为基础需求。所谓HTML主题，并不是把整套页面用不同HTML重写一遍，而是借助CSS变量与结构化的模板，将表现层与内容层分离。通过定义一组设计令牌，再在运行时切换这些令牌的值，就能以极低的成本实现深色模式、品牌换肤等功能。
一、使用CSS变量定义主题令牌
CSS自定义属性（常被称为CSS变量）是主题系统的基石。我们在全局作用域:root中声明颜色、字体、圆角等基础值，后续所有样式都引用这些变量而不是硬编码具体数值。这样做的好处是，只需要改变量本身，整站样式就会同步更新。
下面是一段基础的主题变量定义。我们把亮色主题作为默认令牌，所有组件都通过var()函数消费它们：
:root {
--color-bg: #ffffff;
--color-text: #333333;
--color-primary: #2f80ed;
--radius-base: 8px;
--space-padding: 16px;
}
.card {
background: var(--color-bg);
color: var(--color-text);
border-radius: var(--radius-base);
padding: var(--space-padding);
}
这种写法将“设计决策”集中存放，避免了样式散落在各处导致换肤时漏改的问题。同时，CSS变量支持级联，意味着我们可以在任意父元素上覆盖变量，从而影响其所有子节点。
要注意的是，CSS变量本身不会触发额外的重排，但颜色变化会引起重绘。为减少切换时的视觉抖动，建议对会变化的属性添加过渡：
body {
transition: background-color 0.3s ease, color 0.3s ease;
}
二、基于data-theme的属性选择器切换
最常见的主题切换方案，是给根元素添加data-theme属性，然后用属性选择器为不同主题提供变量覆盖。这种方式语义清晰，也方便在服务端渲染时直接输出对应主题。
我们在CSS中补充暗色主题的定义，当且仅当html[data-theme="dark"]时生效：
:root {
--color-bg: #ffffff;
--color-text: #333333;
--color-primary: #2f80ed;
}
html[data-theme="dark"] {
--color-bg: #1a1a1a;
--color-text: #e6e6e6;
--color-primary: #4f9bff;
}
切换逻辑非常简单，只需修改文档根节点的属性即可。下面是用原生JavaScript实现的切换函数，同时把用户选择存入本地存储：
function setTheme(theme) {
document.documentElement.setAttribute('data-theme', theme);
localStorage.setItem('theme', theme);
}
function initTheme() {
const saved = localStorage.getItem('theme');
if (saved) {
document.documentElement.setAttribute('data-theme', saved);
} else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.setAttribute('data-theme', 'dark');
}
}
initTheme();
这种方案的优点是CSS结构直观，不需要JS频繁操作样式；缺点是如果主题很多，CSS体积会随主题数量线性增长。对于只做亮暗双主题的场景，它是最稳妥的选择。
为了避免页面加载瞬间出现默认主题再跳变，应在HTML的head内联一段脚本，在解析body前就设好data-theme，防止闪烁（FOUC）。
三、用JavaScript动态改写CSS变量
如果主题是由用户自由调配的颜色（比如后台管理系统允许自定义品牌色），用属性选择器就不现实了。此时可直接通过style.setProperty改写根节点上的CSS变量。
以下示例演示了如何把用户输入的颜色实时应用到主色变量上：
const root = document.documentElement;
function updatePrimaryColor(value) {
root.style.setProperty('--color-primary', value);
}
const picker = document.querySelector('#brandColor');
picker.addEventListener('input', function(e) {
updatePrimaryColor(e.target.value);
});
这种方式的灵活度最高，适合“无限主题”场景。不过它把主题状态移到了DOM行内样式中，不利于SSR直出，也需要自行处理持久化。
在性能上，批量修改多个变量时，建议用requestAnimationFrame合并写入，或先加一个.no-transition类禁用过渡，改完再恢复，从而避免切换过程中的连续动画卡顿。
四、HTML模板与主题解耦的编写方式
所谓“模板”，是指HTML结构应保持稳定，不因为主题不同而改变标签。主题只负责变量，模板负责语义。例如一个卡片组件，无论亮暗主题，它的HTML都应是：
<div class="card"> <h3 class="card__title">标题</h3> <p class="card__desc">描述内容</p> <button class="card__btn">操作</button> </div>
对应的样式全部走变量，不写死颜色。这样在切换主题时，无需动HTML，只需替换CSS变量来源。若使用框架（如Vue、React），可把主题名存在状态里，通过动态绑定data-theme实现：
<div :data-theme="currentTheme"> <slot></slot> </div>
模板层还可以提供“主题预览”能力：用iframe或 scoped 容器包裹同一套模板，分别赋予不同data-theme，让用户直观对比。关键是保证模板不依赖具体主题类名（如.dark-card），否则就背离了变量驱动的思路。
最后提醒，主题切换应兼顾可访问性。不仅要支持prefers-color-scheme，还要确保对比度符合WCAG标准，并提供明确的切换按钮而非仅依赖自动识别。
五、小结与落地建议
编写HTML主题的核心原则就是“变量驱动、模板稳定”。小型项目用data-theme加属性选择器足够；个性化较强的系统可结合setProperty做运行时调色；无论哪种，都要把设计令牌收敛到:root并避免HTML随主题分叉。
实际落地时，推荐把主题变量单独抽成theme.css，在构建阶段按需引入，同时用一小段阻塞脚本在头部固化用户偏好，就能兼顾开发效率与体验细节。