CSS设计令牌必须全部声明在:root以确保全局可访问和主题切换一致性，变量名需语义化、用途明确、避免硬编码值与色值绑定。
CSS变量管理字号、颜色、间距三套设计令牌，核心不是“能不能”，而是“怎么组织才不翻车”——必须全部挂载在 :root，且变量名要语义化、可推导、不带硬编码值。
为什么必须用 :root 声明所有变量
局部作用域（比如写在 .button 里）会导致变量无法跨组件复用，主题切换时得手动遍历每个选择器去改；:root 是唯一能保证全页面访问的锚点。浏览器解析 CSS 时，:root 的变量优先级高于继承链上的任何局部声明，也支持被 JS 动态修改（如 document.documentElement.style.setProperty('--color-primary', '#ff6b6b')）。
常见错误现象：--spacing-m: 16px 写在某个组件 CSS 文件里，结果 .card 用不了，只能复制粘贴，后期改间距要搜 12 个文件。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 新建
design-tokens.css文件，只放:root块和注释，不混入任何样式规则 - 入口 CSS 用
@import 'design-tokens.css';，确保它最先加载 - 禁止在 Vue/React 组件的
<style>块里重复定义同名变量（哪怕只是临时调试）
--font-size-body 这类字号变量怎么命名才不踩坑
别用 --fs-16 或 --text-md 这种模糊命名：前者绑定具体像素值，换响应式字体（如 clamp()）就失效；后者缺乏上下文，不知道是正文、按钮还是表单标签。
正确做法是按用途+层级命名，例如：
-
--font-size-heading-1：一级标题，对应h1和主 Banner 标题 -
--font-size-body：正文段落，默认字号基准 -
--font-size-caption：图注、辅助说明文字
关键细节：font-size 变量推荐用无单位数值（如 --font-size-body: 1），配合 rem 使用；若需响应式，直接在使用处写 font-size: clamp(0.875rem, var(--font-size-body), 1.125rem)，变量本身保持稳定。
--space-m 间距变量为什么不能直接写 16px
写死 px 会破坏缩放一致性：用户调大系统字体时，间距不变，视觉节奏断裂；深色模式下微调间距也得重写整套规则。
更可靠的方式是用相对单位 + calc() 构建弹性系统：
-
--space-unit: 4px作为原子单位（不直接使用） --space-xs: calc(var(--space-unit) * 1)--space-s: calc(var(--space-unit) * 2)--space-m: calc(var(--space-unit) * 4)
这样后期想整体放大 25%，只需改 --space-unit: 5px，所有间距自动等比变化；媒体查询中也能精准覆盖，比如 @media (max-width: 768px) { :root { --space-m: calc(var(--space-unit) * 3); } }。
颜色变量命名必须脱离色值描述
--blue-500 看似规范，实则埋雷：一旦品牌色从蓝色换成青绿色，这个变量名就变成谎言，团队新人根本不敢动它；换主题时还得写一堆 .dark-theme { --blue-500: #0d6efd; } 来覆盖，维护成本爆炸。
应该按功能+语义命名：
-
--color-brand-primary：主品牌色，用于按钮、链接、重点标识 -
--color-text-primary：主要文本色，随主题切换自动适配亮/暗背景 -
--color-border-divider：分割线、边框色，通常比背景略深
额外提醒：不要把颜色变量和用途强绑定到单一组件，比如 --button-bg —— 按钮背景可能在不同状态（hover/disabled）或主题下需要不同值，应由组件自身通过 var(--color-brand-primary) + 状态类组合控制，而非预设“按钮专用色”。
最易被忽略的一点：所有变量必须在初始 :root 中预设完整，包括暗色模式下要用到的备用值（哪怕先写成同色），否则 JS 切换主题时读取 getComputedStyle 会返回空字符串，导致样式丢失。
