团队协作规范

团队协作规范的重要性

多人协作开发CSS项目时，缺乏统一规范会导致代码混乱、维护困难。样式冲突、命名随意、冗余代码等问题频繁出现，严重影响开发效率和项目质量。建立明确的CSS协作规范能显著提升团队产出的一致性。

命名约定

BEM命名方法论

BEM(Block Element Modifier)是CSS类名命名的有效方案。通过以下模式定义类名：

/* 块级组件 */
.card {}
/* 元素 */
.card__header {}
/* 修饰符 */
.card--dark {}

命名空间前缀

为不同功能模块添加前缀避免冲突：

/* 布局模块 */
.l-grid {}
/* 工具类 */
.u-text-center {}
/* 状态类 */
.is-active {}

文件组织结构

目录划分建议

styles/
├── base/          # 基础样式
├── components/    # 组件样式
├── layouts/       # 布局样式
├── utils/         # 工具类
├── themes/        # 主题样式
└── variables.scss # 变量定义

模块化导入

主文件通过@import组织样式：

// main.scss
@import 'variables';
@import 'base/reset';
@import 'components/button';

样式编写规则

属性排序规范

推荐按功能分组排序：

.selector {
  /* 定位相关 */
  position: absolute;
  top: 0;
  
  /* 盒模型 */
  display: block;
  width: 100%;
  
  /* 文本样式 */
  font-size: 16px;
  
  /* 视觉效果 */
  background: #fff;
}

选择器嵌套限制

SCSS中嵌套不超过3层：

// 推荐
.card {
  &__header {
    .icon {...}
  }
}

// 避免
.card {
  &__header {
    .title {
      span {...}
    }
  }
}

变量管理

设计令牌定义

集中管理设计系统变量：

// variables.scss
$color-primary: #1890ff;
$spacing-unit: 8px;
$breakpoint-md: 768px;

主题变量方案

支持多主题切换：

[data-theme="dark"] {
  --bg-color: #333;
}
[data-theme="light"] {
  --bg-color: #fff;
}

代码审查要点

常见审查项

1. 避免使用ID选择器
2. 禁止!important滥用
3. 媒体查询位置统一
4. 重复样式提取为mixin

自动化检查

配置stylelint规则示例：

{
  "rules": {
    "selector-max-id": 0,
    "declaration-no-important": true,
    "max-nesting-depth": 3
  }
}

版本控制策略

分支管理规范

• feature分支：新组件开发
• style分支：纯样式修改
• fix分支：样式问题修复

提交信息格式

feat(button): 增加primary状态样式
fix(layout): 修复移动端间距问题

文档化实践

样式字典生成

使用注释自动生成文档：

/// 主品牌色
/// @group colors
$color-primary: #1890ff;

组件示例展示

结合Storybook创建可视化文档：

// Button.stories.jsx
export const Primary = () => (
  <Button variant="primary">提交</Button>
);

性能优化建议

关键CSS提取

构建工具配置示例：

// webpack.config.js
new MiniCssExtractPlugin({
  filename: '[name].[contenthash].css'
})

无用样式检测

定期执行PurgeCSS清理：

// postcss.config.js
require('@fullhuman/postcss-purgecss')({
  content: ['./src/**/*.html']
})

响应式处理原则

断点统一管理

$breakpoints: (
  sm: 576px,
  md: 768px
);

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

移动优先实现

.component {
  // 默认移动端样式
  
  @include respond-to(md) {
    // 平板样式
  }
}

浏览器兼容策略

前缀处理方案

使用Autoprefixer自动添加：

{
  "browserslist": [
    "last 2 versions",
    "> 1%"
  ]
}

渐进增强示例

.grid {
  display: flex;
  display: grid;
  @supports (display: grid) {
    display: grid;
  }
}

设计系统集成

Token转换工具

将设计稿变量转换为代码：

// tokens.js
module.exports = {
  color: {
    primary: '#1890ff'
  }
}

样式API设计

组件暴露可定制参数：

// _button.scss
@mixin button-variant($color) {
  background: $color;
  &:hover {
    background: darken($color, 10%);
  }
}

工具链配置

预处理器选择

Sass配置示例：

// sass.config.js
module.exports = {
  includePaths: [
    './src/styles'
  ]
}

构建优化配置

// vite.config.js
export default {
  css: {
    modules: {
      localsConvention: 'dashes'
    }
  }
}

代码复用模式

Mixin库建设

// _mixins.scss
@mixin text-ellipsis {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

工具类生成

通过循环生成工具类：

@each $size in (4, 8, 12) {
  .p-#{$size} {
    padding: #{$size}px;
  }
}

视觉回归测试

快照对比方案

配置Storybook测试：

// storybook.test.js
initStoryshots({
  suite: 'Visual Regression'
});

差异检测阈值

// config.js
const customDiffConfig = {
  threshold: 0.1
};

样式覆盖策略

组件作用域隔离

CSS Modules用法：

import styles from './Button.module.scss';

function Button() {
  return <button className={styles.primary} />;
}

全局样式注入点

定义明确覆盖入口：

// override.scss
.ant-btn {
  &-primary {
    @extend .my-btn-primary;
  }
}

动画实现规范

动画性能优化

优先使用transform：

.move {
  transition: transform 0.3s;
  &:hover {
    transform: translateX(10px);
  }
}

动画曲线管理

$easing: (
  standard: cubic-bezier(0.4, 0, 0.2, 1),
  decelerate: cubic-bezier(0, 0, 0.2, 1)
);

主题切换实现

CSS变量方案

:root {
  --text-color: #333;
}

.dark-mode {
  --text-color: #fff;
}

主题派生处理

.button {
  color: var(--text-color);
  
  &-primary {
    background: var(--primary-color);
  }
}

团队知识共享

样式模式库

建立内部UI模式文档：

## 间距系统
- 使用4px基准单位
- $spacing-unit * N 方式定义

代码评审案例

记录典型问题案例：

- .header > .nav > .item {}
+ .header__item {}