返回
聊聊
CSS 变量命名
2025/03/24
写于北京
没耐心看全文？试试作为播客来收听
在设计系统的建设过程中，我负责定义大量 Design Token，其中最具挑战性的部分，是如何为 CSS 变量建立一套清晰、可扩展的命名体系。这个过程不仅涉及命名规范的探索，还包括与研发同学就命名结构、作用域、语义映射等方面的深入讨论。本文是对这段实践的系统回顾，记录我在变量命名上的思考与选择。
对我而言，命名从不是可有可无的风格问题，而是构建可维护、可扩展前端架构的核心。尤其在 CSS 中，清晰有序的变量命名不仅表达设计意图，也大幅降低维护成本，为主题化等能力打下基础。
"命名结构：建立可预测性"
我为变量设定结构，是为了让人一眼就能看出它的作用。最有效的方式之一，是采用三段式命名法（Triptych Notation）：[namespace]-[type]-[name]
namespace：标识变量来源，避免在多项目或多人协作中发生命名冲突。我通常会用 ds（设计系统）或项目缩写作前缀。
type：说明变量的值类型，比如 color、fontSize、duration，能防止误将变量用于不匹配的 CSS 属性。
name：描述变量具体用途。我倾向使用驼峰式（camelCase）命名，让它在视觉上与 type 部分形成清晰区隔，提升可读性。
这一命名结构为设计系统带来了可预测性，也为后期维护与协作打下基础。
来源、类型、用途一目了然，代码的意图也因此更加明确。
"命名的分层逻辑"
我通过分层命名来隔离变化，常见做法是划分为两层：原始值层和语义层。
原始值层（Value-based） 是系统的设计原子，承载色彩、字号、间距等基础值。它们不绑定具体使用场景，仅描述“是什么”，不涉及“用在哪”。我的目标是通过这一层约束设计选项，保持视觉的一致性与系统性。
在命名上，我更倾向使用具象的复合词（如 skyBlue、cherryRed），而非抽象编号（如 blue-400）。这不仅更易读，也让设计语言更具温度。
语义层是我用来连接原子值与 UI 场景的桥梁。在这层中，变量描述的是用途，而不是具体数值。它们通常通过引用原始值层的变量来获得最终样式。
我的目标，是通过命名传达设计意图，实现样式与内容的关注点分离。这也是支持主题切换（如浅色与深色模式）的关键机制。
在命名时，我会避免两种极端：太宽泛的名称（如 --color-primary）含义模糊，太具体（如 --color-mainToolbarBackground）则失去复用性。一个好的语义名，应准确、清晰、可迁移。
通过这种分层，当需要调整主题或进行全局样式变更时，我们只需修改语义层的映射关系，而无需触及任何具体的组件代码，极大地提升了系统的可维护性。
在我看来，变量命名不只是语法技巧，而是设计系统架构的体现。结构清晰、层次分明、作用域明确的命名方式，是我构建可理解、可维护、可演进 CSS 样式的基础。