Team collaboration guidelines

The Importance of Team Collaboration Standards

Code style consistency directly impacts project maintenance costs. In multi-person collaborative development, the absence of unified standards can lead to issues such as chaotic naming, arbitrary formatting, and significant structural differences. A unified CSS standard can reduce code conflicts, improve readability, and help new team members get up to speed quickly.

Naming Conventions

BEM Naming Methodology

BEM (Block Element Modifier) is the most commonly used CSS naming convention. It uses double underscores __ to connect blocks and elements and double hyphens -- to indicate modifiers.

/* Block component */
.search-form {}

/* Element */
.search-form__input {}
.search-form__button {}

/* Modifier */
.search-form__button--disabled {}
.search-form__input--focus {}

Semantic Naming

Avoid naming based on presentation; instead, name based on functionality or content:

/* Not recommended */
.red-text {}
.left-box {}

/* Recommended */
.error-message {}
.sidebar-navigation {}

Code Formatting Standards

Indentation and Line Breaks

Use 2 spaces for indentation and leave blank lines between rule declarations:

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

Property Order

Arrange properties in the following grouped order:

1. Layout properties (display, position, float, etc.)
2. Box model (width, margin, padding, etc.)
3. Text-related (font, color, text-align, etc.)
4. Visual styles (background, border, etc.)
5. Others (animation, transition, etc.)

.modal {
  /* Layout */
  position: fixed;
  top: 0;
  left: 0;
  
  /* Box model */
  width: 100%;
  padding: 20px;
  
  /* Text */
  font-size: 16px;
  color: #333;
  
  /* Visual */
  background: #fff;
  border: 1px solid #ddd;
  
  /* Others */
  transition: all 0.3s;
}

Preprocessor Standards

SCSS Nesting Limit

Limit nesting to no more than 3 levels to avoid overly complex selectors:

// Not recommended
.page {
  .content {
    .article {
      .title {
        // Excessive nesting
      }
    }
  }
}

// Recommended
.page-content {
  .article-title {
    // Reasonable nesting
  }
}

Variable Management

Define colors, spacing, etc., as variables for centralized management:

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

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

Commenting Standards

File Comments

Add a comment at the beginning of each CSS file to explain its purpose:

/**
 * Main navigation bar styles
 * Includes logo area, main navigation menu, and user control area
 * @author John Doe
 * @update 2023-05-20
 */

Section Comments

Use specific comment markers to distinguish style sections:

/* ========== Button Styles ========== */
.primary-btn {
  /* ... */
}

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

/* ========== Form Elements ========== */
.input-field {
  /* ... */
}

Performance Optimization Standards

Selector Efficiency

Avoid overly complex selectors:

/* Not recommended */
div#header ul.nav li a {}

/* Recommended */
.nav-link {}

Avoid Overusing Universal Selectors

Universal selectors * can cause performance issues:

/* Not recommended */
* {
  box-sizing: border-box;
}

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

Responsive Design Standards

Breakpoint Management

Use predefined breakpoint variables for consistency:

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

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

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

Mobile-First Principle

Base styles should target mobile devices, with progressive enhancement:

/* Base mobile styles */
.component {
  padding: 10px;
}

/* Tablet adaptation */
@media (min-width: 768px) {
  .component {
    padding: 20px;
  }
}

/* Desktop adaptation */
@media (min-width: 1024px) {
  .component {
    padding: 30px;
  }
}

Code Review Key Points

Common Review Items

1. Compliance with naming conventions
2. Correct property order
3. Presence of unused styles
4. Overly complex selectors
5. Appropriate use of preprocessor features

Automated Checks

Configure stylelint for automated checks:

// .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
  }
}

Version Control Strategy

Branch Management

1. main branch for stable releases
2. dev branch for daily development
3. Feature branches named in the format feature/xxx

Commit Message Standards

Use conventional commit format:

feat(button): Add primary button styles

- Added primary-btn styles
- Adjusted hover state effects

Design System Integration

Token Conversion

Map design tokens to CSS variables:

:root {
  /* Colors */
  --color-primary: #4285f4;
  --color-secondary: #34a853;
  
  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  
  /* Typography */
  --font-size-base: 16px;
}

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

Component Library Development

Establish foundational component standards:

// _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;
  }
}