CSS变量（自定义属性）命名规范

CSS变量（自定义属性）命名规范与最佳实践指南

CSS变量（自定义属性）是现代CSS开发的核心工具，能显著提升代码可维护性和设计一致性。本文基于行业标准和最佳实践，提供完整的CSS变量规范体系。

一、核心命名规范原则

语义化命名

✅ 描述用途而非具体值（如--color-primary而非--color-blue）

✅ 避免与视觉特征直接绑定（如避免--large-font）
命名格式
- 小写字母+连字符 ：--border-radius-md
- BEM衍生结构 ：--button__background--hover
- 前缀分组 ：--color-, --spacing-, --font-

作用域标识

css 复制代码

:root { /* 全局变量 */ 
  --color-primary: #3498db;
}

.card { /* 组件级变量 */
  --card-padding: 1.5rem;
}

二、CSS变量分类规范

1. 色彩系统（Color）

类型	命名格式	示例
基础色	`--color-{语义名}`	`--color-primary`
状态色	`--color-{状态}`	`--color-hover`
主题色	`--theme-{名称}`	`--theme-dark-surface`
透明色	`--color-{名}-{透明度}`	`--color-primary-10`

完整示例:

css 复制代码

:root {
  /* 基础色 */
  --color-primary: #3498db;
  --color-secondary: #2ecc71;
  
  /* 状态色 */
  --color-hover: rgba(52, 152, 219, 0.8);
  --color-active: #2980b9;
  
  /* 功能色 */
  --color-success: #27ae60;
  --color-error: #e74c3c;
  
  /* 中性色 */
  --color-text: #333;
  --color-background: #f8f9fa;
}

2. 间距系统（Spacing）

类型	命名格式	示例
基础间距	`--spacing-{size}`	`--spacing-md`
轴向间距	`--spacing-{axis}-{size}`	`--spacing-top-lg`
组件间距	`--{组件}-spacing`	`--card-padding`

尺寸梯度表:

css 复制代码

:root {
  --spacing-xxs: 0.25rem;
  --spacing-xs: 0.5rem;
  --spacing-sm: 0.75rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-xxl: 3rem;
}

3. 排版系统（Typography）

类型	命名格式	示例
字体	`--font-family-{类型}`	`--font-family-base`
字号	`--font-size-{级别}`	`--font-size-heading1`
字重	`--font-weight-{类型}`	`--font-weight-bold`
行高	`--line-height-{类型}`	`--line-height-dense`

示例:

css 复制代码

:root {
  /* 字体系列 */
  --font-family-base: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'Fira Code', monospace;
  
  /* 字号梯度 */
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-md: 1rem;
  --font-size-lg: 1.125rem;
  
  /* 特殊字号 */
  --font-size-heading1: 2.5rem;
  --font-size-heading2: 2rem;
  
  /* 字重 */
  --font-weight-regular: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;
}

4. 效果系统（Effects）

类型	命名格式	示例
阴影	`--shadow-{类型}`	`--shadow-card`
圆角	`--radius-{size}`	`--radius-pill`
过渡	`--transition-{属性}`	`--transition-color`
透明度	`--opacity-{状态}`	`--opacity-disabled`

效果变量库:

css 复制代码

:root {
  /* 阴影 */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --shadow-card: 0 4px 12px rgba(0, 0, 0, 0.08);
  
  /* 圆角 */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-pill: 999px;
  
  /* 过渡 */
  --transition-fast: 150ms ease;
  --transition-medium: 250ms ease;
  --transition-color: color 200ms ease;
}

三、作用域管理规范

全局变量

css 复制代码

:root {
  --color-primary: #3498db;
  --spacing-md: 1rem;
}

组件级变量

css 复制代码

.button {
  --btn-height: 40px;
  --btn-padding: 0 var(--spacing-md);
  
  height: var(--btn-height);
  padding: var(--btn-padding);
}

主题级变量

css 复制代码

.theme-dark {
  --color-background: #121212;
  --color-text: #e0e0e0;
}

.theme-light {
  --color-background: #ffffff;
  --color-text: #333333;
}

四、响应式变量规范

媒体查询中的变量覆盖

css 复制代码

:root {
  --font-size-heading: 2rem;
}

@media (max-width: 768px) {
  :root {
    --font-size-heading: 1.5rem;
  }
}

容器查询支持

css 复制代码

.card {
  --card-padding: 1rem;
}

@container (min-width: 400px) {
  .card {
    --card-padding: 1.5rem;
  }
}

五、最佳实践指南

变量分层结构

scss 复制代码

├── 基础变量 (Base) 
│   ├── 颜色
│   ├── 间距
│   ├── 排版
│   └── 效果
│
├── 组件变量 (Components)
│   ├── button
│   ├── card
│   └── form
│
└── 主题变量 (Themes)
    ├── light
    └── dark

命名冲突预防
diff 复制代码
```
- --primary-color  
+ --color-primary
```

回退机制

css 复制代码

.element {
  color: var(--color-custom, var(--color-primary));
}

JS交互规范

js 复制代码

// 获取变量
const primaryColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary');

// 设置变量
document.documentElement.style.setProperty('--color-primary', '#ff0000');

六、完整应用示例

css 复制代码

/* ===== 全局变量 ===== */
:root {
  /* 颜色系统 */
  --color-primary: #3498db;
  --color-surface: #ffffff;
  --color-text: #333333;
  
  /* 间距系统 */
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* 排版系统 */
  --font-size-base: 16px;
  --line-height-base: 1.5;
  
  /* 效果系统 */
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.12);
  --radius-md: 8px;
}

/* ===== 组件变量 ===== */
.card {
  --card-padding: var(--spacing-md);
  --card-bg: var(--color-surface);
  
  padding: var(--card-padding);
  background: var(--card-bg);
  box-shadow: var(--shadow-sm);
  border-radius: var(--radius-md);
}

/* ===== 主题系统 ===== */
.theme-dark {
  --color-surface: #121212;
  --color-text: #e0e0e0;
}

/* ===== 响应式调整 ===== */
@media (max-width: 768px) {
  :root {
    --spacing-md: 0.75rem;
  }
}

七、兼容性处理方案

特性检测

css 复制代码

@supports not (--css: variables) {
  /* 传统样式回退 */
  .card { 
    padding: 15px; 
  }
}

渐进增强

css 复制代码

.element {
  margin: 15px; /* 传统值 */
  margin: var(--spacing-md); /* 变量值 */
}