Architecting CSS Linting Strategies: From Baseline Rules to SCSS Governance
These packages provide shared configurations for Stylelint, a tool that analyzes CSS and SCSS code to enforce consistency and avoid errors. stylelint-config-recommended acts as the foundational safety net, enabling only rules that catch definite syntax errors. stylelint-config-standard builds on this by adding strict stylistic conventions for property ordering and formatting. stylelint-config-recommended-scss extends the baseline to understand SCSS-specific syntax like mixins and variables. stylelint-config-sass-guidelines enforces a rigorous, opinionated architecture for large-scale SCSS projects based on community best practices. Finally, stylelint-config-idiomatic-order focuses exclusively on sorting CSS properties within rule blocks to match a specific logical sequence.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Architecting CSS Linting Strategies: From Baseline Rules to SCSS Governance
In modern frontend architecture, maintaining a consistent stylesheet is just as critical as managing JavaScript logic. Stylelint serves as the guardian of CSS health, but its power lies in how you configure it. The packages stylelint-config-recommended, stylelint-config-standard, stylelint-config-recommended-scss, stylelint-config-sass-guidelines, and stylelint-config-idiomatic-order represent different layers of strictness and specificity. Let's break down how they function and where they fit in your build pipeline.
🛡️ The Foundation: Catching Errors vs. Enforcing Style
The most fundamental decision is whether you want a safety net or a style guide.
stylelint-config-recommended is the bare minimum. It turns on rules that catch syntax errors and problems that will break your code. It does not care about your formatting preferences.
// .stylelintrc.json
{
"extends": "stylelint-config-recommended",
"rules": {
"color-no-invalid-hex": true,
"unit-no-unknown": true
}
}
stylelint-config-standard takes the recommended set and adds strict stylistic rules. It enforces a specific way of writing CSS, such as requiring single quotes for strings or no empty blocks. It removes the need for team debates on formatting.
// .stylelintrc.json
{
"extends": "stylelint-config-standard",
"rules": {
"string-quotes": "single",
"block-no-empty": true,
"declaration-colon-space-after": "always"
}
}
🧩 Handling SCSS: Syntax Awareness vs. Architectural Governance
When you introduce preprocessors like SCSS, standard CSS linters often fail to understand syntax like mixins or nested selectors. You have two main paths here: enabling syntax support or enforcing architectural guidelines.
stylelint-config-recommended-scss extends the recommended config to include rules that understand SCSS. It ensures your SCSS syntax is valid but stays neutral on how you structure your architecture.
// .stylelintrc.json
{
"extends": "stylelint-config-recommended-scss",
"rules": {
"scss/at-import-no-partial-leading-underscore": true,
"scss/dollar-variable-colon-space-after": "always"
}
}
stylelint-config-sass-guidelines is much more opinionated. It enforces the official Sass Guidelines, which include strict limits on nesting depth, selector complexity, and naming conventions to prevent "stylesheet sprawl" in large projects.
// .stylelintrc.json
{
"extends": "stylelint-config-sass-guidelines",
"rules": {
"max-nesting-depth": 3,
"selector-max-compound-selectors": 3,
"scss/at-mixin-pattern": "^[a-z]+([a-z0-9-]+[a-z0-9]+)?$"
}
}
📋 Property Ordering: Standard vs. Idiomatic
One of the most common sources of visual noise in CSS is the order of properties within a rule block. Different configs handle this differently.
stylelint-config-standard includes a default property ordering rule that groups related properties (like positioning or box model) in a logical flow.
// .stylelintrc.json (Standard approach)
{
"extends": "stylelint-config-standard",
"rules": {
"order/properties-alphabetical-order": null,
"order/order": ["positioning", "box-model", "typography", "visual"]
}
}
stylelint-config-idiomatic-order enforces a specific, community-driven order known as "idiomatic-css". This is distinct from the standard config and is chosen when a team specifically prefers this sorting logic over the default standard.
// .stylelintrc.json (Idiomatic approach)
{
"extends": "stylelint-config-idiomatic-order",
"rules": {
"order/properties-order": [
"position",
"top", "right", "bottom", "left",
"display", "float",
"width", "height",
"margin", "padding"
]
}
}
⚠️ Critical Compatibility Notes
You cannot simply stack all these packages together. They often conflict.
- Do not use
stylelint-config-standardandstylelint-config-idiomatic-ordertogether. They both try to control property ordering and formatting, which will cause rule collisions. - Do not use
stylelint-config-recommendeddirectly withstylelint-config-sass-guidelineswithout checking overrides. The Sass guidelines config usually includes its own error-checking baseline. - Best Practice: Choose ONE primary config (Standard, Recommended-SCSS, or Sass-Guidelines) and extend it. If you need SCSS support with Standard, you may need to manually enable SCSS rules or look for a combined community config, as
stylelint-config-standardis CSS-focused by default.
// ✅ Correct: Extending SCSS recommended with specific custom rules
{
"extends": "stylelint-config-recommended-scss",
"rules": {
"indentation": 2
}
}
// ❌ Incorrect: Conflicting order configs
{
"extends": [
"stylelint-config-standard",
"stylelint-config-idiomatic-order"
]
}
🌐 Real-World Implementation Scenarios
Scenario 1: The Greenfield React Project
You are starting a new project with standard CSS modules. You want zero configuration hassle and immediate consistency.
- ✅ Best Choice:
stylelint-config-standard - Why? It provides immediate value by enforcing both correctness and style without extra setup.
{
"extends": "stylelint-config-standard"
}
Scenario 2: The Legacy SCSS Migration
You have a massive legacy codebase using SCSS. You want to stop syntax errors but cannot enforce strict architectural rules yet without breaking the build.
- ✅ Best Choice:
stylelint-config-recommended-scss - Why? It understands SCSS syntax and catches errors without failing on existing messy architecture.
{
"extends": "stylelint-config-recommended-scss"
}
Scenario 3: The Design System Governance
You are building a shared component library used by multiple teams. Strict adherence to naming and nesting is required to keep the bundle size down.
- ✅ Best Choice:
stylelint-config-sass-guidelines - Why? It enforces the strict rules needed for long-term maintainability of a design system.
{
"extends": "stylelint-config-sass-guidelines",
"rules": {
"max-nesting-depth": 2
}
}
📊 Summary: Configuration Matrix
| Package | Primary Focus | SCSS Aware | Strictness Level | Best For |
|---|---|---|---|---|
recommended | Error Prevention | ❌ No | Low | Baseline safety |
standard | Style + Errors | ❌ No (CSS only) | Medium | General CSS projects |
recommended-scss | SCSS Errors | ✅ Yes | Low | SCSS projects needing safety |
sass-guidelines | Architecture | ✅ Yes | High | Large SCSS systems |
idiomatic-order | Property Sorting | ❌ No | Medium | Teams preferring idiomatic order |
💡 The Big Picture
Choosing the right config is about balancing safety against opinion.
- Start with
stylelint-config-recommended(or its SCSS variant) if you want to build your own rules slowly. - Jump to
stylelint-config-standardif you want a polished, consistent CSS codebase immediately. - Adopt
stylelint-config-sass-guidelinesonly if your team is ready to commit to strict architectural constraints for SCSS. - Use
stylelint-config-idiomatic-orderonly as a specific replacement for the ordering rules instandardif your team prefers that specific style.
Final Thought: A linter config is a social contract for your code. Pick the one that matches your team's willingness to enforce rules today, knowing you can tighten the screws later.
How to Choose: stylelint-config-idiomatic-order vs stylelint-config-recommended vs stylelint-config-recommended-scss vs stylelint-config-sass-guidelines vs stylelint-config-standard
- stylelint-config-idiomatic-order:
Integrate this package specifically when your team adheres to the 'idiomatic-css' methodology for property sorting and you are not using
stylelint-config-standard. It is best used as a targeted add-on to enforce a specific logical order of properties within CSS blocks. - stylelint-config-recommended:
Choose this package as the absolute minimum baseline for any new project. It is ideal when you want to catch syntax errors and invalid code without forcing a specific coding style or property order on your team. Use it when you plan to build your own custom rules on top of a safe foundation.
- stylelint-config-recommended-scss:
Use this package when your project utilizes SCSS features like variables, mixins, or nesting, and you need the linter to understand this syntax without enforcing strict architectural rules. It is the go-to choice for adding SCSS support to the basic recommended safety net.
- stylelint-config-sass-guidelines:
Opt for this configuration if you are managing a large-scale SCSS codebase and need strict governance over architecture, such as limiting nesting depth and enforcing naming conventions. It is suitable for teams committed to following the official Sass community guidelines to prevent stylesheet sprawl.
- stylelint-config-standard:
Select this configuration when you need a 'batteries-included' solution that enforces both error prevention and consistent stylistic choices out of the box. It is best for teams that want to avoid debating minor formatting details and prefer a widely accepted standard for property ordering and whitespace.
Popular Comparisons
README for stylelint-config-idiomatic-order
stylelint + idiomatic-css = ❤️
Order your styles based on idiomatic-css.
Installation
npm install --save-dev stylelint-config-idiomatic-order
Usage
Set your stylelint config to:
{
"extends": "stylelint-config-idiomatic-order"
}
You can easily extend the config to your needs.