语义化CSS变量命名应以用途和层级为核心，如--color-error、--color-text-primary，分基础色、语义色、组件色三层定义，并通过媒体查询与calc()动态适配，配合文档规范与PR审查保障落地。

用语义化 CSS 变量命名，能从根本上解决颜色命名混乱、难以维护的问题。核心不是给颜色起“好听的名字”，而是让每个变量名表达它在产品中的用途和层级关系。

用功能或场景代替物理色值命名

避免 --red-500、--blue-light 这类依赖视觉感知的命名。它们在换肤、适配深色模式或品牌升级时极易失效。

• 推荐写法：--color-error、--color-success、--color-border-subtle
• 说明：这些名字不绑定具体色值，只表达“这个颜色用在哪、起什么作用”。后期调整主题时，只需改变量值，所有使用处自动同步。
• 小技巧：对同一语义，在不同场景下可加后缀区分，如 --color-text-primary 和 --color-text-secondary，体现信息层级而非明暗程度。

分层定义变量：基础色 → 语义色 → 组件色

把颜色体系拆成三层，既保证灵活性，又避免过度抽象导致难理解。

• 基础色（brand palette）：仅用于存品牌主色、中性灰等原始色值，如 --color-brand-primary、--color-gray-100。不直接在组件中使用。
• 语义色（role-based）：由基础色计算而来，代表通用角色，如 --color-error = var(--color-red-500)，--color-bg-surface = var(--color-gray-50)。
• 组件色（component-specific）：仅当某个组件有独特配色逻辑时才定义，如 --button-primary-bg = var(--color-brand-primary)。保持窄口径、高复用。

配合 CSS 自定义属性 + calc() 实现动态适配

语义化变量不是静态标签，它可以参与计算，支撑深色模式、对比度调节等需求。

• 例如：--color-text-primary 在浅色模式下是 #1a1a1a，深色模式下是 #f0f0f0，通过 @media (prefers-color-scheme: dark) 切换。
• 再如：用 color-mix(in srgb, var(--color-brand-primary), white 20%) 动态生成悬停态背景，无需额外定义 --color-button-primary-hover。
• 关键点：语义变量本身要稳定，变化逻辑交给计算或媒体查询，而不是靠一堆“hover”、“disabled”、“inverted”后缀变量堆砌。

配套建立命名规范文档与审查机制

再好的命名策略，没人遵守就等于没有。需要轻量但可持续的落地保障。

• 在项目根目录放一份 COLORS.md，列出所有已定义语义变量、用途说明、是否允许覆盖、示例用法。
• 在 PR 检查中加入简单规则：禁止在 CSS 中直接写十六进制/rgb 值；新增变量必须出现在文档中并说明语义依据。
• 设计系统组件库中，所有颜色都只接受语义变量作为输入（如 textColor="--color-text-secondary"），从源头收口。