Prettify Your CSS: Simple Linting Rules For Readable Code

Every web developer has come across CSS at one point or another. For most, it’s a necessary evil that’s easy to learn, but difficult to master. After some time, you start to get the hang of it and maybe even pick up something like SASS and/or flexbox. One thing you may not realize: your code is a bit ‘ugly’. I don’t mean that in a mean way, and it is something you won’t realize until you compare well-linted code with something you wrote months-years ago.

In this article, I will be going over common linting errors I encounter in the wild, but also some I struggled with for a while. There are many many more, but this article is meant to be a jumping off point. These examples will be following the stylelint spec. You can check it out here. If you haven’t heard of something like stylelint, introduce it once you get confident with CSS! You’ll start to pick up habits and be well on your way to writing beautiful code. With that said, let’s get to it!

NOTE: the below examples will be using a preprocessor called SCSS, but can be applied to anything else you may use(including just vanilla CSS of course).

Basics: Property Spacing

If you look through some of your older projects, you may see something like this:

/* Inconsistent spacing after each property name */
.article {
    background-color:rgba($bg-grey, 0.5);
    box-sizing: border-box;
    display:flex;
    flex-direction: column;
    justify-content:space-between;
    ...
}

/* Do it like this */
.article {
    background-color: rgba($bg-grey, 0.5);
    box-sizing: border-box;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
    ...
}

Notice anything? It’s pretty subtle for anyone who hasn’t picked up the habit yet. The spacing after the property name isn’t consistent. Stylelint requires each style rule to be followed by 1 space. Notice the background-color doesn’t have a space but box-sizing does, and so on.

Another rule is having a single space after each style selector.

.article {
    ...
}

Instead of

.article{
    ...
}

All in all: Have one and only one space after each property name and style selector.

Basics: Nesting

Most CSS linting rules involve proper spacing by a certain amount of characters. They take a bit of time to get used to, but are conceptually simple. If you’re following the stylelint spec, you should indent each line/deceleration with exactly 2 spaces. Here’s an example.

.article {
    /* the meta block is spaced twice */
    .meta {
        ...
        /* This inner deceleration is also spaced twice */
        property: value;
    }

     /* Dont do this(3 spaces) */
     .meta-two {
         property: value;
             /* Or this(4 spaces when above are 2) */
             property: value;
     }
}

You may already space things evenly, but sometimes a single file will be spaced with 4, and the other two. If you follow the 2 spaces rule, all of your files will look consistent project-wide. Simple rule, just make it a habit!

All in all: Nest each block and inner deceleration with exactly two spaces.

Double Quotes.

Something that took me a while to get the hang of was using double quotes for @imports, @includes, etc. This one is also simple, and I like to follow it for the consistency . I was used to single quotes for languages like PHP and JavaScript, so this one was a bit tricky!

/* You might do this, use doubles! */
@import 'my-file';

/* like this */
@import "my-file";

/* Also, for property values */
.my-img {
    background-image: url("my-img.png");
}

All in all: Use double quotes for wherever you’d potentially use single quotes, such as property values and imports.

Last One For Now: Trailing Lines

Your text editor may or may not take care of this one for you. Stylelint doesn’t like extra or lack of spacing before/after blocks and properties. Here’s a quick example using a SCSS @extend.

.container {
    /* Notice one space after the extend. */
    .post {
        @extend %my-cool-extend;

        .block {
            ...
        }
    }

    /* Two spaces here, use one space only */
    .post.alt {
        @extend %my-cool-extend;


        .block {
            ...
        }
    }

    /* Zero spaces. Make sure there is a space */
    .post.featured {
        @extend %my-cool-extend;
        .block {
            ...
        }
    }
}
/* end of file, put an empty space here, but not more than one */

Notice at the end of the file we put a space(normally you’d put a space instead of that example comment). Stylelint also likes one trailing space at the end of each file, and this error will often get me when creating new files. Try to look out for this too!

These spacing rules also apply for spacing between blocks.

/* ONE space, do this */
.post {
    ...
}

.post.alt {
    ...
}

/* Multiple spaces, don't do this */
.post {
    ...
}


.post.alt {
    ...
}

All in all: Make sure you have only one trailing space at the end of each file, and between extends, includes, style blocks, etc.

My Recommendation: Install Stylelint

You can try to enforce these rules yourself, but I found having them enforced for you is the best way to truly build good habits. Stylelint can be installed as a plugin for something like VS code, or installed as a whole build step. Some builds come with it, such as the WordPress starter theme Sage.io (what this site is built on!). Once you see the lint errors, you will feel compelled to fix them and be well on your way to writing prettier CSS.

Whatever you decide to do, I hope something in this post introduced you to new concepts that will ultimately help you! If these suggestions seemed ‘basic’, that’s because they are the fairly straightforward ones. Stylelint actually has plenty more rules, these are just some of the most common lint errors I run into. When you get the chance, check it out and give it a try!

Leave a Comment