直接用 --primary 变量套进 linear-gradient() 会失效，因浏览器不支持渐变内 CSS 变量运行时插值（Firefox 至今不支持），且 background-image 不触发平滑过渡；需拆分为独立变量（如 --grad-start）、显式声明初始值、避免简写混用固定色值。
为什么直接用 --primary 变量套进 linear-gradient() 会失效？
浏览器对 background-image 的 transition 和变量插值有硬性限制：哪怕你写了 background-image: linear-gradient(var(--primary), var(--secondary))，只要变量值变了，旧版行为是整条声明重计算，不触发平滑过渡；更关键的是，Firefox 至今（2026 年中）仍不支持在 linear-gradient() 内部对 CSS 变量做运行时插值——它会直接回退到初始值或报错。
常见错误现象是：主题切换后背景“啪”一下突变，或者压根没反应。这不是 JS 没执行，而是 CSS 层面变量根本没被识别为可动画属性。
- 必须把渐变的每个颜色停靠点都拆成独立变量（如
--grad-start、--grad-end），不能只靠一个--primary推导 - 所有变量必须在 :root 或目标元素上显式声明初始值，否则插值起点为空
-
background简写必须完整引用变量，不能混写固定色值（比如linear-gradient(to right, var(--grad-start), #ff0)会导致整个渐变失效）
怎么用 @property 让颜色变量支持跨格式插值？
@property 是目前唯一能让浏览器明确知道“这个变量是颜色类型、允许从 red 插值到 hsl(120,100%,50%)”的机制。不注册，Chrome/Safari 会按字符串处理，插值结果不可控。
使用场景很具体：当你需要浅色主题用 #4a5568 → #718096，深色主题切到 hsl(210,20%,15%) → hsl(210,25%,25%)，又想保持同一段动画代码复用时，@property 就是刚需。
立即学习“前端免费学习笔记（深入）”；
- 注册语法必须带
syntax: "<color>"</color>，且inherits: false（颜色变量通常不继承） - 变量名要和你在
linear-gradient()里引用的一致，比如注册了--grad-start，就不能在样式里写var(--start) - 示例：
@property --grad-start { syntax: "<color>"; inherits: false; initial-value: #4a5568; }然后在元素上：.card { --grad-start: #4a5568; --grad-end: #718096; background: linear-gradient(to right, var(--grad-start), var(--grad-end)); transition: background 0.4s ease; }
主题切换时渐变闪白或文字消失怎么办？
这是典型的 FOUC（Flash of Unstyled Content），根源有两个：变量回退值缺失 + JS 设置 dataset 的时机晚于 CSS 计算。
比如你只在 JS 里设了 document.documentElement.dataset.theme = 'dark'，但 :root 里没给 --grad-start 定义默认值，浏览器渲染第一帧时变量为空，linear-gradient() 解析失败，回退成 transparent 或 inherited 色，导致背景透明、文字叠在底色上发虚甚至看不见。
- :root 必须定义所有渐变变量的初始值（哪怕只是浅色主题的默认值），例如：
:root { --grad-start: #e2e8f0; --grad-end: #cbd5e0; } - 媒体查询里只覆盖变量值，不要重写整套样式，避免重复声明冲突
- 切换主题时，先同步更新 dataset，再批量 setStyle（
document.documentElement.style.setProperty()），别等 DOM 加载完才操作
多色渐变怎么根据单个主题色动态生成？
没法真“生成”，只能预设逻辑映射。比如你定下规则：“主色是 --primary，起始色取其 desaturate 20% + lightness +10%，终止色取其 spin +30deg + saturate 10%”，那就要用 HSL 拆解 + JS 计算，再写回 CSS 变量。
但注意：纯 CSS 无法做 color math。所以实际方案是：
- 在 JS 初始化时读取
--primary的 computed value（用getComputedStyle(document.documentElement).getPropertyValue('--primary')） - 用库如
tiny-color或原生hsl()字符串解析，算出两个衍生色 - 把结果写入
--grad-start和--grad-end - CSS 层只负责消费这两个变量，不做任何计算
容易被忽略的一点：HSL 插值比 RGB 更可控，但前提是饱和度和亮度不能全放开——如果 --primary 是纯灰（hsl(0,0%,50%)），spin 操作就无效。得加 fallback 判断，比如检测 saturation < 10% 时，改用明度阶梯替代色相旋转。
