After reading many articles on writing the perfect CSS, I found that there is no perfect way to write CSS. I mean CSS isn’t the prettiest ‘language,’ but it has successfully powered the styling of the web for over 20 years now. Not doing too bad, huh? As I have written more and more CSS I found it darn difficult to maintain my own CSS, poorly written CSS will quickly turn into a nightmare.

Therefore to make my life easier, I wrote my own CSS style guide, let me run you through it below.

/*
  Filename
  Description of the file and it's contents (sometimes followed by a table of contents)
*/

/* Section heading
-------------------------------------------------- */

/* Sub heading
------------------------- */

/* Short "why" messages */
.wrapper {
  width: 800px;
  margin: 0 auto; /* inline note */
}

To start, each file should include a repeated name and short description. While the name here can be the same as the filename (as I’ve indicated), combined with the description, it can help you add clarity for other designers.

Moving along, every major component is broken down into its own section. Not shown above is that each section has two to three lines after it to space things out. Subsections of that component have their own sub headings as well to further break things apart for readability and documentation.

Really though, the last two types of comments are the most important to me. The others are honestly more of a formality and sanity check as searching is just as fast in most cases.

/* Topbar inner */
.topbar-inner {
  ...
}

The comment adds no value to anyone because it doesn’t tell you why this code is there in the first place. Here’s what might work a bit better:

/* Required inner div to stack background effects */
.topbar-inner {
  ...
}

While not the greatest example in the world, it illustrates the point.

Property order

A consistent CSS property order makes debugging faster, allows other developers to easily read your code and expectations of what exactly a block of CSS does that much clearer.

High level overview

At a high level, here’s our breakdown:

• position
• display and box model
• font, leading, color, text
• background and border
• CSS3 properties like border-radius and box-shadow
• and a handful of other purely visual properties

It mixes the common structural and alphabetical approaches into one in an effort to ensure our property order is logical, scannable, and all-encompassing.

Show me!

Getting more specific, here are some blocks of CSS might look with this property order in mind.

.topbar {
  position: fixed;
  top: 0;
  right: 0;
  left: 0;
  height: 40px;
  padding: 0 20px;
  background-color: #333;
  border-bottom: 1px solid rgba(0,0,0,.1);
  box-shadow: 0 2px 3px rgba(0,0,0,.5);
}

Here you can see positioning, box model (height and padding), and visual (background-color, border-bottom and box-shadow) in their proper order. This flows in such a way that you can discern that this is a fixed dark gray bar with a drop shadow–you know exactly what it is you’re dealing with as you read line-by-line.

Naming Convention

We now have the comment structur, the property order now lets dig into the naming convention is use. This is called BEM. Generally, there are 3 problems that CSS naming conventions try to solve:

1. To know what a selector does, just by looking at its name
2. To have an idea of where a selector can be used, just by looking at it
3. To know the relationships between class names, just by looking at them

You may have already guessed that the B in BEM stands for ‘Block’ in the real world, this ‘block’ could represent a site navigation, header, footer, or any other block of design. Lets use one of the sections on my site to explain this, lets use one of the recommendation blocks. We’re going to look at the text underneath the image…

The block that holds the type, name and location has a class of .card-text which would look like this:

E for Elements

The E in ‘BEM’ stands for Elements. Overall blocks of design rarely live in isolation. For instance, the card-text block has a type, name, location. The type, name and location are all elements of the card-text block. They may be seen as child components, i.e. children of the overall parent component.

Using the BEM naming convention, element class names are derived by adding two underscores, followed by the element name. For example:

.card-text {
}

M for Modifiers

The M in ‘BEM’ stands for Modifiers. What if the card-text was modified and we could have a uppercase or a italic card-text block? Using BEM, modifier class names are derived by adding two hyphens followed by the element name.

For example:

.card-text__type {

}
.card-text__name {

}
.card-text__location {

}

Full example

Below is an example of the BEM naming convention, it’s super easy to implement and makes debugging and modifying your code a dream. Try refactoring your CSS file with the above methods and see how clean and easy your code is to read.

<p class="card-text">
  <h4 class="card-text__type">hotel</h4>
  <h4 class="card-text__name">the ludlow</h4>
  <h4 class="card-text__location">Lower East Side, New York</h4>
</p>
<!-- CSS -->
.card-text {

}
.card-text__type {

}
.card-text__name {

}
.card-text__location {

}

Why Use Naming Conventions?

Naming things is hard. We’re trying to make things easier, and save ourselves time in the future with more maintainable code.

Naming things correctly in CSS will make your code easier to read and maintain.

If you choose to use the BEM naming convention, it will become easier to see the relationship between your design components/blocks just by looking at the markup.