Spyros Argalias

Posted on Feb 3, 2020 • Updated on Mar 1, 2020 • Originally published at sargalias.com

Why you should use semantic naming in CSS

#css #webdev #frontend #learning

This post (Why you should use semantic naming in CSS) was originally published on Sargalias.

Video version of this article: https://youtu.be/4Oo04kyM1Yg.

In this post I want to talk about why semantic naming is important. It's important in programming in general, but particularly I want to discuss its importance in CSS.

What semantic naming is

Basically, if you have a class .color-red, or even .color-primary, that is not semantically named.

It describes the style or look of the element, rather than its purpose.

A more semantic name may be .page-heading or main-sidebar. Something that describes the purpose of the element.

Why semantic naming is important

It brings two important benefits:

Maintainability
Labels / notes for the programmer

Problem - Maintainability

So with your .color-red class, obviously the h1 you apply it to is going to be red.

But the designer comes back tomorrow and tells you to make it blue.

Now you have to go to both your HTML and CSS to make the change.

In the HTML you need to change the class, because it's going to be the ultimate confusion if it has the class .color-red and it looks blue. You also need to add a new class in your CSS as well: .color-blue this time.

It works, but it's on cue to become a maintenance nightmare. Code should be optimised for maintainability.

Having to change two things (HTML and CSS) instead of one is more error-prone.

Solution - Maintainability

Instead, consider:

If it was just named .page-heading, then you only have to change the color in one place (in the CSS).

This has tons of benefits:

Changes are only done in one place, so the process is simpler (read: harder to make a mistake).
It opens up the path for white-labelling (having a website where you can change the styling purely from the CSS).
Maintenance is much easier. The element has the class .page-heading today, and it will probably have the same class a year from now.

Problem - Labels

Back to the HTML with the class .color-red...

Unless the HTML / JavaScript file has an amazing name, seeing <div class="color-red"> doesn't tell you anything about what that component is.

Is it the sidebar? The page heading? The comment box? It's extremely difficult to tell.

Compare this with <div class="page-heading"> or <div class="main-sidebar">.

You immediately know the purpose of the component. You can find it on the website (even with a simple search on the dev tools), and you can find it in the codebase.

And remember, you don't have 5 components, you have 100 components for a large website.

It's a programming standard

I'm sure you've heard the phrase "There are two difficult things in computer science: Naming and cache invalidation".

Yes naming is difficult, and it's not uncommon for programmers to spend a good amount of time thinking of a good name for something.

The reason this is necessary is because code must be optimised for maintainability. You will read code and modify it a huge number of times. Even if it takes 3x to write the code upfront, it will pay dividends in efficiency if the code is easily understandable. And it will not take 3x longer to write it, only 1.2x.

Conclusion

Use semantic naming that describes the purpose of an element, rather than its look.

It provides lots of benefits:

Maintainability
Changes only happen in one place, so less error-prone.
Changes only happen in CSS (+ opens up white labelling).
Labels for easily identifying elements.

And remember the project tomorrow will have 100s of components, so any problems you have today due to non-semantic names will greatly amplified tomorrow.

Top comments (7)

Nicholas Stimpson • Feb 4 '20

I'm not convinced about the semantic-ness of "sidebar". Still seems presentational to me, since on some devices you might not want it at the side. The problem is of course that the sidebar often contains a bag of bits, and while each bit may have a semantic name, the bag doesn't. It's impossible to suggest a better name without knowing what bits a given bag contains, but in many cases, referring to the element as an <aside> within the context of a given document element ancestry might work out better.

Spyros Argalias • Feb 4 '20 • Edited

Yeah perfectly good suggestion, thank you. You've got some good reasoning behind that.

At the end of the day you and your team will decide what makes the most sense to use.

There are two main motivations behind semantic class names:

The principle of least astonishment (the name is a useful, non-surprising label to the programmer).
Minimising future changes, because changing things is error-prone. A semantic name just happens to be the thing that is the least likely to change, compared to say color-red which could change all the time.

You've got the right idea to challenge the name. If you can find one that you think is most appropriate then by all means go for it :).

EDIT: Clarified about label being non-surprising.

Cody Pearce • Feb 3 '20

Semantic CSS is definitely important. I'm curious what you think of Tailwind CSS, isn't it doing the exact opposite?

Spyros Argalias • Feb 4 '20 • Edited

Yes exactly, Tailwind CSS is doing the opposite. Personally I would never use it in a serious project for the reasons outlined in this article and more:

It's basically a step above inline styles.
Almost all of the styling concern moves to HTML rather than CSS, so now HTML is tightly coupled with content and presentation. In programming we generally want clear separation of concerns. That way as we're changing one of them, we won't accidentally break the other and we can also re-use things easier.
One of the big reasons: It doesn't really scale with global style changes. E.g. the main page gives the example of .text-indigo-600. If you suddenly want to change to font-weight: 700 for all headings on your website, or a different color, you'll have to go to a ton of HTML elements to make the change. However with normal CSS you can have a variable called color-primary and just change that and affect everything with a single change. You could technically change the value of the indigo class to say yellow, but then the class name shows a different color so that will be confusing.
Another important reason: Can't do white labelling without semantic classes (where you can give a client the same HTML) but different styling purely through CSS.
If you want to reuse styles in multiple places, you'll have a lot to copy, in multiple places. If you want to modify styles you use in multiple places, you'll have to go to multiple places to change the HTML. Anything repetitive is very error-prone.

Say for example you have an element representing the "page-heading" in multiple templates. With semantic class names, they all have a single class of page-heading. With Tailwind CSS, they probably have multiple classes you'll need to re-copy every time. Then if you want to modify the styles, with a single class, you only modify the CSS in one place. With Tailwind CSS, you have to change classes in every single place.

More to write than a single class name, which means more to manage. E.g. if you want a modifier class like the classic button button-primary, that's a single class. However with tailwind that's going to be an entire if statement with multiple different classes:

  // Pseudo-React code

  // Tailwind CSS
  render() {
    if (isPrimary) {
      return <div className="a b c d f" />
    } else {
      return <div className="a b g e h" />
    }
  }

  // Semantic CSS
  render() {
    return <div className={`a ${isPrimary ? 'a-primary' : ''}`}>
  }

Everything you do is always going to be global, never specifically apply to one class. Perhaps Tailwind CSS makes this work but from experience in programming we know that most global things can present problems if not dealt with diligently. My personal preference is to not touch anything global if I don't have to. The exceptions in CSS are base styles, which have the lowest specificity possible, and variables driven by design systems, not developers.
The classes don't tell you anything about what the component is, breaking the principle of least astonishment and making it harder to know how to find the thing you're looking for in the codebase.
You cannot see all the styling at once for the relevant component unless you know what all the classes do off by heart. Otherwise you have to check documentation for every class. Whereas with a single class you can immediately open up the CSS file it's in and see it all in one place.
If you want a new custom style for your component, you now have to add it in two places: Create a new CSS class for it, and add it in HTML.
And so on.

... Damn I went all out on this one. Sorry my thoughts just grew as I was writing the thing.

But all of that is just my opinion of course.

There is one use case I see Tailwind CSS or other OOCSS frameworks being useful, and that's if non-technical people may need to change styles. E.g. if you have a CMS or something where a non-technical person can select things like "margin-large", or "border-radius-large". You would effectively be presenting OOCSS or atomic CSS options (like Tailwind CSS) to them, and then applying those classes to the resulting HTML.

I mean you could technically do it while staying semantic, but then you would basically be re-implementing Tailwind CSS for all those options in your own code. It's probably easier to just use Tailwind CSS in this case.

Also something like Tailiwind CSS is great for quickly trying out different styles in prototyping.

EDIT: Clarified about CMS use case.

Cody Pearce • Feb 4 '20

Lot of good points, I've never really explored utility CSS libraries since I've always done semantic, but an article talking about the two approaches: utility and semantic would be very interesting to read.