stylelint-selector-max-depth

A stylelint custom rule for limiting CSS selectors depth.

Installation and usage

npm install stylelint-selector-max-depth

In your stylelint config add "stylelint-selector-max-depth" to the plugins array, and "selector-max-depth": N to the rules, specifying a max selector depth as the primary option, like so:

{
  "plugins": [
    "stylelint-selector-max-depth"
  ],
  "rules": {
    // ...
    // Max selector depth of 2
    "selector-max-depth": 1,
    // ...
  },
};

Details

This rule allows you to limit depth for CSS selectors. To put it simply, selector depth is how many levels of HTML structure (not necesserily direct descendants) the selector is reflecting.

.foo .bar[data-val] > .baz + .boom .lorem {
/* ^        ^         \__________/    ^
   |        |              ^          |
  Lv1      Lv2            Lv3        Lv4  -- these are depth levels */

Only the child (h1 > a) and descendant (h1 a) combinators are considered to create a new depth level; adjacent combinators (p + p, .foo ~ bar) don't.

Why another rule?

At the moment stylelint - a great CSS linter - has no way to control selector depth without hurting something else. It has rules to control Sass nesting; to disallow certain simple selectors (type selectors, IDs) and even to limit a selector's specificity - but not the depth.

Consider the case when the requirements are: no more than 3 levels of simple selectors; and no limit to selector type.

.class1 .class2 .class3 { ... }      // 1. We want this to work.
.class1 article .class3 { ... }      // 2. And this.
#element h3 { ... }                  // 3. And even this.

.menu .item div a { ... }            // 4. But not this.
.menu li div a span span { ... }     // 5. And not this.
ul li ul li div a span span { ... }  // 6. No way we would want this!

We can't force it with selector-max-specificity: 0,3,0, which is necessary for selector 2 to comply, will cut selector 3. Selector 6, on the other hand, has specificity of just 8 for any classname selector not to comply and as much as 8 to allow eight (!) type selectors in a row.

Neither we can force this with max-nesting-depth, since it only controls Sass nesting and the selectors can be written without using nesting, e.g:

.foo {
  .bar { /* nesting level 1 */
    .buzz .lightyear #to .the .rescue { /* nesting level 2 */
      ...
    }
  }
}