css变量控制主题需通过模板向根元素注入data-theme属性，由css选择器响应，而非硬编码类名；data-theme避免fouc、性能更优；主题权收口于根元素，子组件禁用data-theme；变量命名需统一为--theme-{category}-{name}格式。
模板中怎么用CSS变量控制主题样式
HTML模板本身不直接支持主题切换，真正起作用的是CSS变量 + 模板渲染时注入的data-theme属性或类名。关键不是“模板语法”，而是你如何把主题标识（比如dark、blue）传给根元素，并让CSS能响应它。
常见错误是把主题逻辑写在模板里硬编码，比如<div class="card {{ theme }}">——这会导致每个组件都要手动加类，维护成本高，且无法复用同一套CSS变量。
<ul>
<li>正确做法：模板只负责输出<code>或
:root和[data-theme="dark"]这类选择器定义，模板不参与样式计算localStorage或props读取主题值，避免首次渲染闪白/闪黑（FOUC）为什么data-theme比切换<link>更适配模板场景
模板（尤其是服务端渲染或静态生成）通常一次性输出完整HTML，此时<link href="dark.css">切换需要JS执行后才生效，而用户看到的是未样式化的页面，尤其在SSR中极易出现FOUC。用data-theme则可让CSS提前加载，JS只负责更新属性，样式始终在线。
性能影响明显：切换<link>会触发CSS重新下载、解析、重排；data-theme仅触发属性变更和CSS变量重计算，浏览器优化充分，响应更快。
- 模板中无需动态改
<link>的href，省去路径拼接、文件存在性校验等逻辑 - 支持服务端直出主题类名，如
，首屏即带样式 - 注意：若模板引擎不支持
data-属性（如旧版Jinja2默认过滤），需显式启用或改用theme等兼容属性名
模板里怎么安全传递主题并避免覆盖冲突
多个模板嵌套时，容易出现主题被子组件意外覆盖，比如父模板设data-theme="dark"，子组件又写<div data-theme="light">——这会让CSS选择器<code>[data-theme="light"]失效，因为它的权重低于html[data-theme]。
根本原则：主题控制权必须收口到根元素，子模板一律禁止设置data-theme，只允许通过class或CSS变量消费主题，例如：<button class="btn-primary"></button>，样式由.btn-primary { background-color: var(--primary-color); }驱动。
- 模板中用
{{ theme }}或{{ $theme }}等变量插入根元素属性，而非组件内部 - 若需局部覆盖（如弹窗强制浅色），用独立class（如
modal-light）+ 更高权重选择器，而不是再设data-theme - 检查模板继承链：BaseLayout.html设
data-theme，PageTemplate.html只扩展内容，不碰主题属性
主题变量命名和模板协作的坑
CSS变量名如果和模板变量名撞车，可能引发意外交互。比如模板里有{{ primaryColor }}用于生成内联style，同时CSS里又定义了--primary-color——两者语义不同但名字相似，容易让人误以为是同一来源。
更隐蔽的问题是大小写：模板变量常为primary_color（snake_case），CSS变量强制--primary-color（kebab-case），中间转换环节若没处理好（如自动转连字符），会导致var(--primary_color)无效。
- 约定：CSS变量统一用
--theme-{category}-{name}格式，如--theme-color-background、--theme-font-size-body - 模板中只负责传原始值（如
"#1a1a1a"），不拼CSS声明；CSS变量定义和映射全部留在CSS中 - 避免在模板里写
style="color: {{ theme.text_color }}"，这绕过了CSS变量体系，失去主题切换能力
localStorage读取的竞态。用户刚打开页面时，JS还没执行，模板只能靠服务端判断或默认主题；但服务端不知道用户上次选了什么，除非你用HTTP Cookie同步或做一次客户端fallback。这个衔接点不处理好，第一次访问永远不是用户想要的主题。
