css变量应按“用途→场景→状态”三级语义命名，如--color-surface-card-hover；禁用物理属性或设计术语命名；主题变量需与基础变量解耦，通过映射层切换。
直接用 --color-primary 这类命名，短期看着清爽，长期维护时会发现：改一个变量，三处样式崩；新加个组件，不知道该复用哪个 --bg- 前缀；设计师说“按钮悬停色再浅一档”，你翻遍 variables.css 找不到“浅一档”对应哪条变量——问题不在写法，而在层级没对齐。
变量按语义层级分三级，不是按颜色/尺寸/间距分组
很多人把 CSS 变量按物理属性归类：--color-red-500、--spacing-xs、--font-size-sm。这会导致语义断裂：按钮背景色和卡片边框色都用了 --color-gray-200，但改设计时只要求“按钮背景变浅”，你得手动去所有按钮相关选择器里找、改、测，无法靠变量名定位意图。
正确做法是按「用途 → 场景 → 状态」三级推进：
-
--color-surface-default（用途：表面色） -
--color-surface-card（场景：卡片容器） -
--color-surface-card-hover（状态：悬停态）
这样改需求时，只要更新 --color-surface-card-hover，所有卡片悬停背景、边框、阴影都会同步响应，无需改任何选择器。
避免使用设计系统术语如 “neutral” “success” “md”
像 --color-neutral-300 或 --spacing-md 这类命名，依赖外部文档解释含义，且极易过时。今天 neutral-300 是浅灰，明天设计规范升级，它变成米白，但变量名没变，团队成员照旧用，视觉就错位。
更可靠的是绑定具体 UI 角色：
- 用
--color-border-input代替--color-neutral-200 - 用
--spacing-gap-section代替--spacing-md - 用
--font-size-body-lg代替--font-size-16（像素值会随 root font-size 变化）
变量名本身就能回答“谁在用它”“为什么用它”，不依赖注释或 Figma 文档。
主题变量必须与基础变量解耦，用映射而非覆盖
常见错误是直接重定义基础变量：:root[data-theme="dark"] { --color-surface-default: #1a1a1a; }。问题在于：一旦某组件临时需要“暗色模式下的浅色卡片”，你就得写内联 style 或新增变量，破坏一致性。
应该拆成两层：
- 基础层（不变）：
--color-surface-default-light、--color-surface-default-dark - 映射层（可切换）：
--color-surface-default: var(--color-surface-default-light);
这样主题切换只需改映射层，所有组件仍用 --color-surface-default，新需求加个 --color-surface-card-inverted 也只影响特定场景，不影响全局逻辑。
最难的不是起名，而是守住边界：当产品经理说“这个弹窗标题字号再大一点”，别急着加 --font-size-modal-title-xl，先问一句——它是否属于现有 --font-size-heading- 体系？如果不是，说明层级漏了一环，得补上“模态框标题”这个语义节点，而不是打补丁。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
