DEV Community

Why you should use semantic naming in CSS

Spyros Argalias on February 03, 2020

This post (Why you should use semantic naming in CSS) was originally published on Sargalias. Video version of this article: https://youtu.be/4Oo04...

Read full post

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.

Bugsy Sailor • Feb 3 '20

I've long been a fan of Adam Silver's Maintainable CSS for all these reasons.

Spyros Argalias • Feb 3 '20

That's a nice article, thanks for linking it :). Some great points in there.