直接在:root中声明--color-primary等语义化变量可全局生效；需用#前缀小写十六进制、确保声明早于调用、区分品牌色与功能色命名，并配合媒体查询或JS动态切换主题。
用 :root 声明语义化自定义属性
直接在 :root 里写 --color-primary: #2563eb; 是最简但有效的起点。关键不是“能不能生效”，而是变量名是否绑定业务含义——--color-brand-accent 比 --color-blue-500 更可靠，因为设计系统升级色阶时，后者需要全量查映射，前者只需改一次值。
注意三点：
• 十六进制必须带 # 前缀且小写，#2563eb 和 #2563EB 在 iOS 13.3 以下 Safari 中会被视为不同变量
• 声明位置要早于任何 var(--x) 调用，建议放在 <style></style> 最顶部或单独引入的 base.css 中
• 别用 html 替代 :root，SVG 内联样式等场景下行为不一致
区分品牌色与功能色的命名逻辑
品牌色聚焦视觉识别，功能色聚焦语义表达，两者命名策略不同：
- 品牌色用用途+层级：如
--color-primary、--color-secondary、--color-brand-accent - 功能色用语义+状态：如
--color-success、--color-error、--color-warning - 中性色按灰阶分级：如
--color-gray-100到--color-gray-900，避免--color-light这类模糊词
这样写，组件里就能直接用 color: var(--color-error);，既可读又便于无障碍逻辑复用（比如屏幕阅读器提示“错误状态”时同步读出颜色语义）。
立即学习“前端免费学习笔记（深入）”；
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
深色模式下如何动态切换颜色值
仅靠 @media (prefers-color-scheme: dark) 重设变量是轻量方案，但用户手动切换主题时必须用 JS 动态改 :root 上的值。
常见错误是把深色规则写在前面，被浅色规则覆盖。正确顺序是：
:root {
--color-primary: #2563eb;
--color-bg: #ffffff;
}
@media (prefers-color-scheme: dark) {
:root {
--color-primary: #3b82f6;
--color-bg: #1e293b;
}
}
如果页面右上角有“日/夜”按钮，JS 需执行：document.documentElement.style.setProperty('--color-primary', '#3b82f6');
别忘了同步设置 data-theme="dark" 属性，方便后续用 [data-theme="dark"] 做更精细控制。
为什么 var(--x) 有时显示 invalid
DevTools 的 Computed 面板里出现 invalid，大概率是以下原因：
-
--color-brand-accent拼写错误，或大小写不一致（--Color-Accent≠--color-accent） - 变量声明在异步加载的 CSS 文件里，而调用它的样式已提前解析
- 写了空值或非法值，如
--color-primary: ;或--color-primary: inherit;，这些不会触发 fallback - 嵌套 fallback：
var(--a, var(--b))是非法语法，整条声明被浏览器忽略
调试时先检查 :root 是否真有该变量，再确认它是否在调用前已加载——这点在 Gradio 等框架里尤其容易踩坑，因为其样式可能分多文件注入。
--color-primary，只是局部覆盖，不影响其他模块，反而让排查颜色来源变得困难。真正统一管理，就得守住 :root 这一根线。 
