Stylelint Order: Ensure Logic Order of CSS

Code readability is crucial for effective teamwork. In this guide, I'll show you a Stylelint addon enhancing readability by ensuring a logical order of CSS properties, maintaining consistency across project.

Easy
2 min
2024-05-08
tl;drGitHub

Why bother about CSS order?

What is wrong with this code? At first glance, it seem fine, but a closer look shows that the CSS properties are put in a random order. If I need to modify positioning properties, I have to scan through all the styles to avoid duplications which can be frustrating. While this might be a quick task in a simple code snippet, real-world projects are usually far more complex and thus more challenging.

.selector {
  position: absolute;
  z-index: 10;
  width: 100px;
  height: 100px;
  right: 0;
  padding: 10px;
  border: 10px solid #333;
  margin: 10px;
  top: 0;
}

It's much easier to read and modify code when properties follow a logical sequence, especially when working in a team. By grouping properties, we avoid the readability issues mentioned earlier. If I need to adjust positioning rules, I can focus on a specific group without the need to search elsewhere, ensuring that changes are quick.

.selector {
  position: absolute;
  z-index: 10;
  top: 0;
  right: 0;

  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;

  border: 10px solid #333;
}

How to ensure order of CSS properties?

Thanks to Stylelint's extensive plugin ecosystem you can easily handle this. Start by installing the stylelint-order plugin, then choose and install one of the available ordering standards too and set its usage in the .stylelintrc.json configuration file.

npm install stylelint-order stylelint-config-clean-order --save-dev

{
  "extends": [
    "stylelint-config-standard-scss",
    "stylelint-config-clean-order"
  ]
}

Once the plugin is installed and your configuration is updated, running Stylelint will highlight any discrepancies from your defined property order, among other issues. If your IDE is integrated with Stylelint, you'll spot the problems right as you write 🎉

yarn stylelint resources/**/*.scss

resources/styles/styles.scss
   2:16  ✖  Unexpected quotes around "Montserrat"                            font-family-name-quotes
   4:3   ⚠  Expected "font-weight" to come before "font-style"               order/properties-order
  11:16  ✖  Unexpected quotes around "Montserrat"                            font-family-name-quotes
  13:3   ⚠  Expected "font-weight" to come before "font-style"               order/properties-order
  20:16  ✖  Unexpected quotes around "Montserrat"                            font-family-name-quotes
  22:3   ⚠  Expected "font-weight" to come before "font-style"               order/properties-order
  35:3   ⚠  Expected an empty line before property "font-family"             order/properties-order
  35:16  ✖  Unexpected quotes around "Montserrat"                            font-family-name-quotes
  35:16  ✖  Unexpected missing generic font family                           font-family-no-missing-generic-family-keyword
  (...)

✖ 19 problems (6 errors, 13 warnings)
  5 errors potentially fixable with the "--fix" option.

You don’t have to manually move each line to ensure a specific order. Stylelint Order supports automatic corrections with the --fix flag so just apply this and see how the code changes for you. Do you agree that the code looks much better now? Drop a comment here and let me know your thoughts!

.selector {
  position: absolute;
  z-index: 10;
  top: 0;
  right: 0;

  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;

  border: 10px solid #333;
}

.selector {
  position: absolute;
  z-index: 10;
  width: 100px;
  height: 100px;
  right: 0;
  padding: 10px;
  border: 10px solid #333;
  margin: 10px;
  top: 0;
}

What CSS order to choose?

I won’t tell what order to use, as it often comes down to personal preference. You can explore various ready-to-use configs to find one that suits your needs. I've opted for stylelint-config-clean-order, but I made a small tweak to better fit with my needs.

I like the way the properties are ordered, but I prefer not to have new lines between groups. This can easily be changed in the Stylelint config file.

import { propertyGroups } from 'stylelint-config-clean-order';

export default {
  extends: [
    'stylelint-config-standard-scss',
    'stylelint-config-clean-order',
  ],
  rules: {
    'no-empty-source': null,
    'selector-class-pattern': null,
    'order/properties-order': [
      propertyGroups.map((properties) => ({
        noEmptyLineBetween: true,
        emptyLineBefore: 'never',
        properties,
      })),
      {
        severity: 'warning',
        unspecified: 'bottomAlphabetical',
      },
    ],
  },
};

This is a continuation of the Stylelint tutorial. Feel free to check out the original article to gain more useful insights about this tool and let me know yout houghts! 👋

Feedback

How satisfied you are after reading this article?