Storytelling CSS Class Names

4 min readNov 25, 2019

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.

How it looks in the CSS/Sass file:

.common-message{ 
    /*component styles*/ 
    &.is-approved { color:green; }    
    &.is-error    { color:red; }    
    &.is-alert    { color:yellow; }    
}

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 of CSS Utility Class:

.u-hide{ display:none!important;}

Example for Using Utility Class in the HTML:

<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>

CSS Usage:

.e-datepicker-popup{ 
     /*add or override styles*/
}

Note: In order to entity class to win in the cascading style war, entities class need to be written always after the regular component class names. Example:

.common-popup{       /*common popup styles*/ } 
.e-datepicker-popup{ /*add or override style of common-popup */ }

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.

Example of usage:

.p-homepage .common-popup{ /*do some styles manipulations*/ }

This class can affect every partial 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>

Final Words

That’s all,
I hope you’ve enjoyed this article and learned from my experience.
If you like this post, I would appreciate applause and sharing 🙂.

You can follow me via Twitter.

More of my CSS posts:
CSS Architecture — Folders & Files Structure
New CSS Logical Properties!
CSS Position Sticky — How It Really Works!

Who Am I?
I am Elad Shechter, a Web Developer specializing in CSS & HTML design and architecture. I work at Investing.com.

You Can find me in my Facebook groups:
CSS Masters
CSS Masters Israel