Preprocessor specifications (SASS/LESS)

SASS and LESS, as CSS preprocessors, provide features such as variables, nesting, and mixins, significantly improving the maintainability and development efficiency of stylesheets. Proper use of preprocessor functionalities requires adherence to specific guidelines to ensure clear code structure and ease of collaboration.

Variable Naming and Scope

Variable names follow the kebab-case convention, aligning with CSS property naming styles. Global variables are defined in standalone files, while local variables are confined to their scope.

// _variables.scss
$primary-color: #3498db;
$font-size-base: 16px;

// Usage within a component
.button {
  $local-padding: 10px; // Local variable
  background: $primary-color;
  padding: $local-padding;
}

In LESS, variables are prefixed with @:

@border-radius: 4px;
.card {
  border-radius: @border-radius;
}

Nesting Depth Control

Nesting depth should not exceed three levels, as excessive nesting results in overly long selectors after compilation. Pseudo-classes and media queries should be nested directly under their parent selectors.

// Correct example
.article {
  &__header {
    &:hover {
      color: $primary-color;
    }
    
    @media (min-width: 768px) {
      font-size: $font-size-base * 1.2;
    }
  }
}

// Incorrect example (excessive nesting)
.nav {
  ul {
    li {
      a {
        span {
          // 5 levels deep
        }
      }
    }
  }
}

Mixin Guidelines

Reusable style fragments should use mixins. For parameters exceeding three, use a Map to pass configurations. Mixin names should follow a verb-noun format.

// Basic mixin
@mixin text-truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

// Mixin with parameters
@mixin box-shadow($x, $y, $blur, $color) {
  box-shadow: $x $y $blur $color;
}

// Complex parameters using Map
@mixin button-theme($config: ()) {
  $default: (
    bg-color: #eee,
    text-color: #333
  );
  $config: map-merge($default, $config);
  
  background: map-get($config, bg-color);
  color: map-get($config, text-color);
}

Functions and Operations

Always use parentheses to ensure operation precedence in numerical calculations. Use dedicated functions for color operations. Custom functions should document their purpose.

// Color operations in LESS
@base-color: #036;
.header {
  background-color: lighten(@base-color, 20%);
}

// SASS operation example
$gutter: 30px;
.container {
  padding: ($gutter / 2); // Explicit operation precedence
  width: calc(100% - #{$gutter});
}

Modular Organization

Split files by functionality and import them using @use (SASS) or @import (LESS). Base filenames should start with an underscore.

styles/
├── _variables.scss
├── _mixins.scss
├── components/
│   ├── _buttons.scss
│   └── _cards.scss
└── main.scss

SASS modular import:

// main.scss
@use 'variables' as vars;
@use 'components/buttons';

.button {
  color: vars.$primary-color;
}

Conditional and Loop Control

Add comments when generating styles with loops to avoid redundant code. Prefer ternary expressions for conditional statements.

// Grid system generation example
$columns: 12;
@for $i from 1 through $columns {
  .col-#{$i} {
    width: percentage($i / $columns);
  }
}

// Conditional styling
$theme: dark;
.page {
  @if $theme == dark {
    background: #333;
  } @else {
    background: #fff;
  }
}

Inheritance and Placeholders

Use placeholder selectors to avoid generating unused base classes. Inheritance chains should not exceed two levels.

%base-button {
  border-radius: 4px;
  padding: 8px 16px;
}

.primary-button {
  @extend %base-button;
  background: blue;
}

// The compiled output will not include a .base-button class

Error Handling and Debugging

Use @warn to flag deprecated variables and @debug to inspect computed values. Custom functions should validate parameter types.

@mixin deprecated-text {
  @warn "This mixin will be removed in v2.0";
  font-family: serif;
}

@function divide($a, $b) {
  @if $b == 0 {
    @error "Cannot divide by zero";
  }
  @return $a / $b;
}

Performance Optimization

Avoid nesting @import within loops. For large list queries, use map-get instead of iteration. Disable unused features.

// Inefficient approach
@each $name in $list {
  @import "components/#{$name}";
}

// Efficient solution
$component-map: (
  button: 'buttons',
  card: 'cards'
);

@each $key, $value in $component-map {
  .#{$key} {
    @import "components/#{$value}";
  }
}

Browser Prefix Handling

Use autoprefixer for compatibility instead of manually writing prefixes in the preprocessor. Configure a standard browser list.

// Not recommended
.selector {
  -webkit-border-radius: 5px;
  -moz-border-radius: 5px;
  border-radius: 5px;
}

// Recommended configuration
// .browserslistrc
last 2 versions
not IE 11

Comments and Documentation

Public interfaces should include explanatory comments. Use SassDoc format for documentation. Nested code blocks should mark their closing scope.

/// Calculates responsive font size
/// @param {Number} $min-size - Minimum font size
/// @param {Number} $max-size - Maximum font size
/// @return {String} calc() expression
@function responsive-font($min-size, $max-size) {
  @return calc(#{$min-size}px + (#{$max-size} - #{$min-size}) * var(--scale));
}

// Nested scope markers
.sidebar {
  // ...styles
  
  @media (min-width: 1024px) {
    // ...styles
  } // @media end
} // .sidebar end

Version Compatibility

Specify SASS/LESS version requirements and provide alternatives for incompatible syntax.

// SASS 3.4+ required for &:selector syntax
.tabs {
  &__item {
    // ...
  }
}

// Legacy version compatibility
.tabs__item {
  // ...
}

Team Collaboration Standards

Configure shared linting rules and standardize partial file prefixes. Use the stylelint-scss plugin for syntax checking.

// .stylelintrc
{
  "plugins": ["stylelint-scss"],
  "rules": {
    "scss/at-rule-no-unknown": true,
    "scss/selector-no-redundant-nesting-selector": true
  }
}