Thoughts on writing cleaner CSS

Writing code that is easy to understand by someone else, and easier to maintain, make the top of the list of my priorities in my day-to-day work.

That is why I'd like to share some attitudes or principles I like to consider in the overall scope of writing and reviewing CSS.

I am using SCSS in my projects, so I will use it my examples as well.

1. Advocacy for conventions

There's a word I won't get bored of hearing, and that's the word convention. And maybe conventions are the first step to cleaner code.

From: What naming convention are we adopting? BEM? OOCSS? Atomic classes? Or a utility-first approach? And which of these are more suitable for our projects and ways of working? - to: What's our naming color system? What different units are we using to size things in our project? What best practices do we need to absolutely follow? - answers to these questions will not only lend a sense of order in your projects, but also potentially keep a window of conversation always open when it comes to best practices and practices that - when followed consistently, will benefit everyone in the team.

I had found that agreeing on conventions has driven the quality of our projects and, due to the nature of our projects, has made decision-making faster and even sped up development.

2. Pursuing flexibility over hard conventions

Conventions are great (I'm their biggest fan), but they might not all fit all your projects like a glove.

Take naming, for example. Naming is hard. But what if you can make it flexible instead?

A good example can be colors and naming them.

Some projects only have a short color scheme. So in that case, using a $brand-primary, $brand-secondary approach would do the trick.

What if a third, a fourth or even a fifth color might come up? Then something like this can be appropriate?

$brand-primary: #6200ee;
$brand-secondary: #03DAC6;
$brand-tertiary: #04d820;
$brand-quaternary: #044bd8;
$brand-quinary: #d80455;

But if we take maintainability and usage into account, this approach can become tricky as well if we are using them as part of a helper name.

Keeping an open mind and trying to find something that fits the needs of the project may be the way to go.

In my case, because I have lots and lots of base colors, I am switching to naming my color variables the same as the color name, trying to keep the color names very simple (blue, green, red - regardless of the shade of blue, green and red they really are).

It may be oversimplified, but it helps me be productive in this particular project. And it looks good used with helper classes as well:

// instead of `bg-tertiary`
.bg-blue {
  background-color: $brand-blue;
}

// instead of `bg-quaternary`
.bg-purple {
  background-color: $brand-purple;
}

In my other project, the color scheme is a bit alive.

It changes during development, and this isn't ideal at all. But it can happen. So putting on the flexibility hat once again is needed.

If we have lots of base colors and lots of shades associated with those, we can use a weight-based notation, similar to Google's Material Design:

$brand-red--100: #ce0125;
$brand-red--200: #e52d4c;
$brand-red--300: #a0182e;
$brand-grey--100: #e0e0e7;
$brand-grey--200: #b1b1bf;
$brand-grey--300: #f2f2f7;

In my case, for ease of usage, I assign a --100 modifier to the color that is used more often, and an increasingly higher value to a color used sparingly.

This approach is clean because it's easy to understand and allows me to accommodate a new color without a major refactoring.

3. Making helper classes predictable

Especially when it comes to helpers for font or background helpers, I like to keep things as predictable as possible.

Pursuing consistency between the variable name and the actual helper class - may decrease some of the mental load needed when using it. When using either the helper or the variable name, I need to remember just one thing:

.bg-primary {
  background-color: $brand-primary;
}
.bg-secondary {
  background-color: $brand-secondary;
}

.type-primary {
  font-family: $brand-primary;
}
.type-secondary {
  font-family: $type-secondary;
}

.type-16 {
  font-size: 16px;
}
.type-32 {
  font-size: 32px;
}

4. Keeping things simple

I try to keep a close eye on two things: HTML structure and the way I apply BEM-notation to my components.

For the former, the rule is quite easy. Trying not to use unnecessary div tags or containers - unless they are really required. Otherwise, leveraging the innate properties of the available elements, block and inline elements alike feels like the right thing to do.

If you are using BEM-notation, you might have been a witness to over-nesting and very big components - to the point where readability is affected and one can no longer know where the component starts or begins. The opposite of clean!

If I have a very large component, I try to break it up in a way so that components are better delimited:

// From this...
.header {
    &__title {
    ...
    }
    &__subtitle {
        &--blue {
        ...
        }
        &--red {
        ...    
        }
    }
}

// ...to this.
.header__title {
  ...
}

.header__subtitle {
    &--blue {
     ...
    }
    &--red {
     ...
    }
}

Again, for components with lots of elements, this can ease nesting and make them a little easier to read, debug and refactor.

Finally...

Asking questions, always keeping an open mind and being flexible, as well as pursuing flexibility can be the key opening the door to better collaboration, creativity and, ultimately - making our CSS (and our HTML) cleaner and more enjoyable to maintain and enrich.