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

walking957
194 阅读4分钟

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

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

一、核心命名规范原则

  1. 语义化命名
    ✅ 描述用途而非具体值（如--color-primary而非--color-blue）
    ✅ 避免与视觉特征直接绑定（如避免--large-font）

  2. 命名格式

    • 小写字母+连字符：--border-radius-md
    • BEM衍生结构：--button__background--hover
    • 前缀分组：--color-, --spacing-, --font-

  3. 作用域标识

    :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

完整示例:

: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

尺寸梯度表:

: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

示例:

: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

效果变量库:

: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;
}

三、作用域管理规范

  1. 全局变量

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

  2. 组件级变量

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

  3. 主题级变量

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

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

四、响应式变量规范

  1. 媒体查询中的变量覆盖

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

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

  2. 容器查询支持

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

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

五、最佳实践指南

  1. 变量分层结构

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

  2. 命名冲突预防

    - --primary-color  
+ --color-primary

  3. 回退机制

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

  4. JS交互规范

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

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

六、完整应用示例

/* ===== 全局变量 ===== */
: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;
  }
}

七、兼容性处理方案

  1. 特性检测

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

  2. 渐进增强

    .element {
  margin: 15px; /* 传统值 */
  margin: var(--spacing-md); /* 变量值 */
}
avatar
文章
阅读
粉丝