CSS Linting: Stylelint Configuration and Rules – Complete Developer Guide

What is CSS Linting and Why It Matters

CSS linting is the process of analyzing your CSS code to identify potential errors, inconsistencies, and style violations. Just as spell-check helps writers avoid typos, CSS linters help developers maintain clean, consistent, and error-free stylesheets. In modern web development, where CSS codebases can grow to thousands of lines across multiple files, automated linting becomes essential for maintaining code quality.

Stylelint stands out as the most powerful and flexible CSS linter available today. Unlike basic syntax checkers, Stylelint can enforce coding standards, catch subtle bugs, and ensure your CSS follows best practices. It supports modern CSS features, preprocessors like Sass and Less, and can be customized to match your team’s specific coding standards.

Installing and Setting Up Stylelint

Getting started with Stylelint is straightforward. You can install it via npm, yarn, or pnpm depending on your package manager preference.

Installation Options

# Using npm
npm install --save-dev stylelint stylelint-config-standard

# Using yarn
yarn add --dev stylelint stylelint-config-standard

# Using pnpm
pnpm add --save-dev stylelint stylelint-config-standard

The stylelint-config-standard package provides a sensible set of default rules that cover common CSS issues and best practices. This configuration serves as an excellent starting point for most projects.

Basic Configuration File

Create a .stylelintrc.json file in your project root to configure Stylelint:

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "indentation": 2,
    "string-quotes": "double",
    "no-duplicate-selectors": true,
    "color-hex-case": "lower",
    "color-hex-length": "short",
    "comment-empty-line-before": "always",
    "declaration-colon-space-after": "always",
    "declaration-colon-space-before": "never",
    "function-comma-space-after": "always",
    "function-url-quotes": "always",
    "media-feature-colon-space-after": "always",
    "media-feature-colon-space-before": "never",
    "media-feature-name-no-vendor-prefix": true,
    "property-no-vendor-prefix": true,
    "rule-empty-line-before": "always-multi-line",
    "selector-attribute-quotes": "always",
    "selector-list-comma-newline-after": "always",
    "selector-max-id": 0,
    "shorthand-property-no-redundant-values": true,
    "value-list-comma-space-after": "always"
  }
}

Essential Stylelint Rules Explained

Understanding Stylelint’s rule categories helps you configure the linter effectively for your project’s needs. Rules are organized into several categories, each addressing different aspects of CSS code quality.

Color Rules

Color-related rules ensure consistency in how colors are defined and used throughout your CSS:

/* Following color rules */
.header {
  background-color: #fff;
  border: 1px solid #e1e4e8;
  color: #24292e;
}

.button {
  background: linear-gradient(45deg, #ff6b6b, #ee5a24);
}

/* Violating color rules */
.header {
  background-color: #FFFFFF; /* Should be lowercase */
  border: 1px solid #E1E4E8; /* Should be lowercase */
  color: #24292E; /* Should be lowercase */
}

.button {
  background: linear-gradient(45deg, red, orange); /* Should use hex values */
}

Font Rules

Font rules help maintain typography consistency and prevent common font-related issues:

"font-family-no-duplicate-names": true,
"font-family-no-missing-generic-family-keyword": true,
"font-weight-notation": "numeric"

.text {
  font-family: "Helvetica Neue", Arial, sans-serif;
  font-weight: 600;
}

.heading {
  font-family: Georgia, "Times New Roman", serif;
  font-weight: 700;
}

Selector Rules

Selector rules promote maintainable CSS by controlling selector complexity and structure:

"selector-class-pattern": "^[a-z][a-z0-9\\-]+$",
"selector-id-pattern": "^[a-z][a-z0-9\\-]+$",
"selector-max-compound-selectors": 3,
"selector-max-specificity": "0,4,0",
"selector-no-qualifying-type": true

Advanced Configuration Strategies

Working with CSS Preprocessors

Stylelint works seamlessly with Sass, Less, and other CSS preprocessors. Here’s how to configure it for Sass:

# Install Sass support
npm install --save-dev stylelint-config-standard-scss

# .stylelintrc.json for Sass projects
{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "scss/at-rule-no-unknown": true,
    "scss/selector-no-redundant-nesting-selector": true,
    "scss/no-duplicate-dollar-variables": true,
    "scss/dollar-variable-pattern": "^[a-z][a-z0-9\\-]*$",
    "scss/percent-placeholder-pattern": "^[a-z][a-z0-9\\-]*$"
  }
}

Custom Rule Configuration

Create project-specific rules that align with your team’s coding standards:

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "max-nesting-depth": 3,
    "selector-max-class": 3,
    "selector-max-combinators": 2,
    "declaration-property-value-blacklist": {
      "border": ["none"],
      "border-top": ["none"],
      "border-right": ["none"],
      "border-bottom": ["none"],
      "border-left": ["none"]
    },
    "property-blacklist": ["float"],
    "unit-blacklist": ["pt", "cm", "mm", "in", "pc"]
  }
}

Integration with Development Workflow

Editor Integration

Most code editors support Stylelint through extensions. For Visual Studio Code, install the “Stylelint” extension to get real-time linting feedback as you write CSS.

Command Line Usage

Run Stylelint from the command line to check specific files or entire directories:

# Lint specific files
npx stylelint "src/**/*.css"

# Lint with auto-fix
npx stylelint "src/**/*.css" --fix

# Generate detailed report
npx stylelint "src/**/*.css" --formatter verbose

Git Hooks Integration

Prevent problematic CSS from being committed using Husky and lint-staged:

# Install dependencies
npm install --save-dev husky lint-staged

# package.json configuration
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{css,scss,sass}": [
      "stylelint --fix",
      "git add"
    ]
  }
}

Common Stylelint Rules and Their Benefits

Spacing and Formatting Rules

These rules ensure consistent visual formatting across your CSS files:

Error Prevention Rules

These rules catch common CSS mistakes before they cause issues in production:

"no-duplicate-at-import-rules": true,
"no-duplicate-selectors": true,
"no-empty-source": true,
"property-no-unknown": true,
"selector-pseudo-class-no-unknown": true,
"selector-pseudo-element-no-unknown": true,
"selector-type-no-unknown": true

Creating Custom Stylelint Rules

For advanced use cases, you can create custom Stylelint rules tailored to your project’s specific needs:

// custom-rule.js
const stylelint = require('stylelint');

const ruleName = 'my-project/no-hardcoded-colors';
const messages = stylelint.utils.ruleMessages(ruleName, {
  rejected: (color) => `Hardcoded color "${color}" is not allowed. Use CSS custom properties instead.`
});

module.exports = stylelint.createPlugin(ruleName, function(primaryOption) {
  return function(root, result) {
    const validOptions = stylelint.utils.validateOptions(result, ruleName, {
      actual: primaryOption,
      possible: [true, false]
    });

    if (!validOptions) return;

    root.walkDecls(function(decl) {
      const hardcodedColors = /#[0-9a-fA-F]{3,6}|rgb\(|rgba\(|hsl\(|hsla\(/;
      
      if (hardcodedColors.test(decl.value)) {
        stylelint.utils.report({
          message: messages.rejected(decl.value),
          node: decl,
          result,
          ruleName
        });
      }
    });
  };
});

Performance Optimization with Stylelint

Large projects may experience slower linting times. Here are optimization strategies:

Ignoring Files

Create a .stylelintignore file to exclude files that don’t need linting:

# .stylelintignore
node_modules/
dist/
build/
vendor/
*.min.css

Caching Results

Enable caching to speed up subsequent runs:

# Enable caching
npx stylelint "src/**/*.css" --cache --cache-location .stylelintcache

Interactive Demo: Stylelint in Action

Continuous Integration Integration

Integrate Stylelint into your CI/CD pipeline to maintain code quality across your team:

GitHub Actions Example

# .github/workflows/css-quality.yml
name: CSS Quality Check

on: [push, pull_request]

jobs:
  css-lint:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Run Stylelint
      run: npm run lint:css
      
    - name: Generate CSS quality report
      run: npx stylelint "src/**/*.css" --formatter json > css-report.json
      
    - name: Upload report
      uses: actions/upload-artifact@v3
      with:
        name: css-quality-report
        path: css-report.json

Best Practices for Team Adoption

Gradual Implementation

When introducing Stylelint to an existing project, start with basic rules and gradually increase strictness:

{
  "extends": ["stylelint-config-standard"],
  "rules": {
    // Start with error-level rules only
    "no-duplicate-selectors": true,
    "property-no-unknown": true,
    
    // Add warning-level rules for gradual adoption
    "color-hex-case": [true, { "severity": "warning" }],
    "indentation": [2, { "severity": "warning" }]
  }
}

Documentation and Training

Create team documentation explaining your Stylelint configuration and the reasoning behind specific rules. This helps team members understand why certain patterns are preferred and reduces resistance to the linting process.

Troubleshooting Common Issues

Rule Conflicts

When extending multiple configurations, rule conflicts may occur. Resolve them by explicitly setting rules in your configuration:

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-prettier"
  ],
  "rules": {
    // Override conflicting rules explicitly
    "indentation": 2,
    "string-quotes": "double"
  }
}

False Positives

Sometimes Stylelint may flag valid CSS as errors. Handle these cases with targeted rule disabling:

/* stylelint-disable-next-line property-no-unknown */
-webkit-overflow-scrolling: touch;

/* stylelint-disable property-no-vendor-prefix */
.legacy-support {
  -webkit-transform: rotate(45deg);
  -moz-transform: rotate(45deg);
  transform: rotate(45deg);
}
/* stylelint-enable property-no-vendor-prefix */

Future of CSS Linting

CSS linting continues to evolve with new CSS features and development practices. Stylelint regularly updates its rules to support modern CSS features like container queries, cascade layers, and CSS modules. Stay updated with the latest Stylelint releases to ensure your linting configuration remains current with CSS standards.

The integration of AI-powered code analysis and automated refactoring tools promises to make CSS linting even more powerful, potentially suggesting not just fixes but improvements to code structure and performance.

Conclusion

Implementing Stylelint in your development workflow is an investment in code quality that pays dividends over time. By catching errors early, enforcing consistent coding standards, and improving code maintainability, Stylelint helps teams deliver better CSS code faster.

Start with the standard configuration, customize rules to match your project’s needs, and integrate linting into your development workflow through editor extensions, pre-commit hooks, and CI/CD pipelines. The initial setup effort is minimal compared to the long-term benefits of cleaner, more maintainable CSS code.

Remember that linting is a tool to support your team, not to constrain creativity. Use it judiciously, document your configuration choices, and be prepared to adjust rules as your project and team evolve. With proper implementation, Stylelint becomes an invisible guardian of code quality that lets developers focus on creating great user experiences.