必须用:root定义才真正全局可用，因其语义正确、优先级更高、跨文档兼容且天然覆盖整个文档树；写在body或class中仅限局部作用域，无法跨组件复用。
变量必须用:root定义才真正全局可用
直接写在body或某个.container里，变量只在该选择器及其后代生效，不是“全页面都能用”。真正跨组件、跨文件复用的起点只有一个：:root。它等价于html元素，但优先级更高，且天然覆盖整个文档树。
-
:root里定义的--color-primary，任何地方写var(--color-primary)都能取到 - 别用
html代替:root——虽然效果一样，但:root是标准写法，兼容性更稳 - 如果项目用 CSS 预处理器（如 Sass），注意：预处理器变量（
$primary）和 CSS 变量（--primary）完全不互通，别混用
var()函数必须带括号且变量名拼写严格匹配
写成var(--text-color)是对的；写成var( --text-color )（空格多、少、位置不对）或var(--TextColor)（大小写错）都会失效——浏览器不报错，但样式不应用，排查时容易卡住。
- 变量名区分大小写：
--bg≠--BG≠--Bg - 不能省略括号：
color: --text-color是无效语法，必须套var() - fallback 值要谨慎用：比如
color: var(--text-color, #333)，当 JS 动态删掉变量或拼错时，能兜底；但别滥用，比如font-size: var(--size, 16px)可能掩盖变量未定义的真实问题
主题切换必须靠 JS 修改:root上的值，纯 CSS 无法触发
很多人以为加个.dark类就能切主题，其实那只是“换一套预设变量”，真正的“切换动作”必须由 JS 完成。CSS 本身没有事件响应能力，@media只能响应屏幕尺寸，不能响应用户点击或 localStorage 变化。
- 正确写法是：
document.documentElement.style.setProperty('--bg-color', '#1a1a1a')，不是document.querySelector('html').style.setProperty(...) - 批量改多个变量时，避免逐个调用
setProperty——高频触发会强制重排。建议用cssText一次性注入，或封装一个setThemeVars函数统一处理 - 刷新后保留主题？必须搭配
localStorage：先读localStorage.getItem('theme')，再根据值设对应变量，否则每次都是默认主题
变量不能用在@keyframes和content里，这是硬限制
哪怕你把--anim-duration定义得再规范，在@keyframes里写animation-duration: var(--anim-duration)也无效；同理，::before { content: var(--label) }永远输出空字符串。这不是 bug，是 CSS 规范明确禁止的场景。
立即学习“前端免费学习笔记（深入）”；
-
@keyframes里所有值必须是静态的，想动态控制动画？得用 JS 创建新规则或切换 class -
content属性只接受字符串字面量、attr()、counter()，不支持var() - 阴影、渐变等复合值要拆开定义：比如
--shadow-color和--shadow-blur分开存，再组合成box-shadow: 0 2px var(--shadow-blur) var(--shadow-color)
