Naming Things in CSS

CSS Architecture — Part 4

5 min readAug 4, 2019

Deciding on a naming convention is one of the hardest things in any programming language, and CSS is no exception.

This year, after 13 years in the web development industry, I spent my time trying to change things all the time. As a result I've gained a lot of experience, and in this post, I would like to share with you my naming convention for CSS class names.

Note: I haven't invented the wheel, and some of the ideas are taken from other methodologies I’ve seen throughout the years in my career.

Naming Things

In my standard naming conventions, I use any given names I want for regular parts— elements / components / sequences.

For more about those types you can read in my previous post — “CSS Architecture — Folders & Files Structure”).

My basic naming class always uses lower case letters and a hyphen (the “-” sign) as a word separator . Example:

.main-nav{}

Chaining Class Names

For the inner parts of the same component, I chain class names. Example:

.main-nav-list{}

If we have an inner part in main-nav-list , let’s say a main nav list item, beware not to chain them both!

Bad Practice:

.main-nav-list-item{}

Good Practice:

.main-nav-item{}

Notice! You can only give one regular class name to the same HTML tag! Later on in this post, I will show you more types of classes you can add to the same HTML tag.

Additional Classes Types

Sometimes I run into situations where I need additional CSS class names to manipulate the styles. When that happens, I categorize those situations into typical types and I give every type of them a prefix class-name, which represents that type.

State Classes

Any component could sometimes need a state — a specific condition in which a certain style is applied to it.

If we take main-nav for example, sometimes we’ll have to define if it’s open or not. This is where CSS state classes come to the rescue.

<nav class="main-nav is-open"> </nav>

You can use those classes to describe types of messages, example:

<div class="common-message           "> <!-- Gray  Message --></div>
<div class="common-message is-approved"><!-- Green Message --></div>
<div class="common-message is-error  "> <!-- Red   Message --></div>
<div class="common-message is-alert  "> <!--Yellow Message --></div>

Or any other state situation, for example: is-wide, is-top, is-small, is-double-size, is-scrolled, is-full-width and etc…

In those cases you may use as many classes as you need.

Utility Classes

In other CSS methodologies, utility classes are everyday things. In my method, however, these types of classes work directly on the HTML element where they’re positioned, and they are allowed to make only one CSS change!

Another characteristic of my utility classes is that we always use it with an “!important” rule. Utility classes are the only good use case for !important in CSS. Why do we need it?! Simple, when we use those classes, we always want them to win the CSS Cascading war. If we don’t want them to override other styles, we should remove the class from the HTML element.

Example:

<style>
    .u-hide{display: none!important;}
</style><div class"common-message u-hide"></div>

I don’t use them often, only in situations like I showed here. Utility classes, the same as State Classes, can be used as many as you need.

Entity Classes and Page Classes

Many projects have components which the designer or project manager uses for an un-generic design. In those cases, I take one of two approaches:

Entities — when using a component whose styles have to change slightly, I add another class name to it, which starts with the ‘e-’ prefix, representing an entity, in addition to the component’s class name.

This class can add styles or override styles. My rule of thumb is that you can only add one entity per component. If there is another case of this component whose styles aren’t 100% the same, it is better to create another entity instead!

Example:

<section class="common-popup e-datepicker-popup"> </section>

Other than that, you can add as many CSS State classes / CSS utility classes as you want.

<section class="common-popup e-datepicker-popup u-hide"> </section>

Pages — every page in your website can be considered a big entity. The page class is used on the <body> element or on the main element that wraps everything, with this class names starting with “p-” .For example: “p-homepage” or “p-news”, etc.…

<body class="p-homepage"></body>

It’s better to avoid this method if you can, but sometimes in real life, you have cases where there’s no other choice.

This class can affect every element / component / sequence / entity on its page.

JavaScript Classes

There are situations in which we need CSS class names to target things in JS. But since it’s problematic to use the same classes for both designing and targeting data in JS, we use JS class names. These class names are used only for data manipulation, and not for adding additional styles!

If you need to add classes for styles, use additional classes following the methodology discussed above, for example, Utility Classes. Example:

<section class="common-popup js-common-popup u-hide"> </section>

To Summarize

In this post I showed you my CSS Architecture for Naming Convention in CSS class names, based on many things I’ve learned over the years.
This post is the fourth in a series of articles I have written about CSS Architecture. I will pause a little with new CSS posts, but I promise to be back soon with more CSS stories.

If it is interesting you , you are welcome to follow me on twitter or on medium.