团队协作规范

团队协作规范的重要性

代码风格一致性直接影响项目维护成本。多人协作开发时，如果没有统一规范，会出现命名混乱、格式随意、结构差异大等问题。统一的CSS规范能减少代码冲突，提高可读性，让新成员快速上手。

命名规范

BEM命名方法论

BEM(Block Element Modifier)是最常用的CSS命名约定。通过双下划线__连接块与元素，双中划线--表示修饰符。

/* 块组件 */
.search-form {}

/* 元素 */
.search-form__input {}
.search-form__button {}

/* 修饰符 */
.search-form__button--disabled {}
.search-form__input--focus {}

命名语义化

避免使用表现形式的命名，应该基于功能或内容命名：

/* 不推荐 */
.red-text {}
.left-box {}

/* 推荐 */
.error-message {}
.sidebar-navigation {}

代码格式规范

缩进与换行

统一使用2个空格缩进，规则声明之间保留空行：

.selector {
  property: value;
  
  &:hover {
    property: value;
  }
}

属性顺序

按照以下分组顺序排列属性：

1. 布局属性 (display, position, float等)
2. 盒模型 (width, margin, padding等)
3. 文本相关 (font, color, text-align等)
4. 视觉样式 (background, border等)
5. 其他 (animation, transition等)

.modal {
  /* 布局 */
  position: fixed;
  top: 0;
  left: 0;
  
  /* 盒模型 */
  width: 100%;
  padding: 20px;
  
  /* 文本 */
  font-size: 16px;
  color: #333;
  
  /* 视觉 */
  background: #fff;
  border: 1px solid #ddd;
  
  /* 其他 */
  transition: all 0.3s;
}

预处理器规范

SCSS嵌套限制

嵌套不超过3层，避免选择器过于复杂：

// 不推荐
.page {
  .content {
    .article {
      .title {
        // 嵌套过深
      }
    }
  }
}

// 推荐
.page-content {
  .article-title {
    // 合理嵌套
  }
}

变量管理

将颜色、间距等定义为变量，集中管理：

// _variables.scss
$primary-color: #4285f4;
$spacing-unit: 8px;

// 使用
.button {
  background: $primary-color;
  padding: $spacing-unit * 2;
}

注释规范

文件注释

每个CSS文件开头添加注释说明用途：

/**
 * 主导航栏样式
 * 包含logo区域、主导航菜单、用户控制区
 * @author 张三
 * @update 2023-05-20
 */

区块注释

使用特定注释标记区分样式区块：

/* ========== 按钮样式 ========== */
.primary-btn {
  /* ... */
}

.secondary-btn {
  /* ... */
}

/* ========== 表单元素 ========== */
.input-field {
  /* ... */
}

性能优化规范

选择器效率

避免使用过于复杂的选择器：

/* 不推荐 */
div#header ul.nav li a {}

/* 推荐 */
.nav-link {}

避免过度使用通用选择器

通用选择器*会导致性能问题：

/* 不推荐 */
* {
  box-sizing: border-box;
}

/* 推荐 */
html, body, div, span, ... {
  box-sizing: border-box;
}

响应式设计规范

断点管理

使用预定义断点变量保持一致性：

$breakpoints: (
  'small': 576px,
  'medium': 768px,
  'large': 992px,
  'xlarge': 1200px
);

@mixin respond-to($breakpoint) {
  @media (min-width: map-get($breakpoints, $breakpoint)) {
    @content;
  }
}

// 使用
.sidebar {
  width: 100%;
  
  @include respond-to('medium') {
    width: 250px;
  }
}

移动优先原则

基础样式针对移动设备，逐步增强：

/* 基础移动样式 */
.component {
  padding: 10px;
}

/* 平板适配 */
@media (min-width: 768px) {
  .component {
    padding: 20px;
  }
}

/* 桌面适配 */
@media (min-width: 1024px) {
  .component {
    padding: 30px;
  }
}

代码审查要点

常见审查项

1. 是否遵循命名规范
2. 属性顺序是否正确
3. 是否有未使用的样式
4. 选择器是否过于复杂
5. 是否合理使用预处理器特性

自动化检查

配置stylelint进行自动化检查：

// .stylelintrc
{
  "extends": "stylelint-config-standard",
  "rules": {
    "selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
    "property-no-unknown": true,
    "declaration-block-no-redundant-longhand-properties": true
  }
}

版本控制策略

分支管理

1. main分支存放稳定版本
2. dev分支用于日常开发
3. 功能分支按feature/xxx格式命名

提交信息规范

使用约定式提交格式：

feat(button): 新增主要按钮样式

- 添加primary-btn样式
- 调整hover状态效果

设计系统集成

Token转换

将设计Token映射为CSS变量：

:root {
  /* 颜色 */
  --color-primary: #4285f4;
  --color-secondary: #34a853;
  
  /* 间距 */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  
  /* 字体 */
  --font-size-base: 16px;
}

.button {
  background: var(--color-primary);
  padding: var(--spacing-sm);
}

组件库开发

建立基础组件规范：

// _button.scss
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 4px;
  padding: 8px 16px;
  
  &--primary {
    background: var(--color-primary);
    color: white;
  }
  
  &--disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }
}