Summary: Name something based on what it is, not how it looks or behaves.

Semantic HTML isn’t just about the elements we use. It’s quite obvious that we should use <a> for links, <table> for tabular data and <p> for paragraphs etc.

“There are only two hard things in Computer Science: cache invalidation and naming things.”
Phil Karlton

What’s less obvious is the names we use for classes. This is important because they enable us to enhance a web page with style (and behaviour).

Semantic versus non-semantic classes

Here are some non-semantic classes:

<div class="red pull-left">
<div class="grid row">
<div class="col-xs-4">

Non-semantic classes don’t tell us what the HTML represents. At best, they give us an idea of what elements look like. Atomic, visual, behavioural and utility classes are all forms of non-semantic classes.

Here are some semantic classes:

<div class="basket">
<div class="product">
<div class="searchResults">

Semantic classes don’t tell us what they look like, but that’s okay. That’s what CSS is for. Semantic classes mean something to HTML, CSS, Javascript and automated functional tests.

There are many reasons why semantic classes are advantageous:

1. Because they are readable

Here’s a real snippet of HTML using atomic classes:

<div class="pb3 pb4-ns pt4 pt5-ns mt4 black-70 fl-l w-50-l">
  <h1 class="f4 fw6 f1-ns lh-title measure mt0">Heading</h1>
  <p class="f5 f4-ns fw4 b measure dib-m lh-copy">Tagline</p>


Here’s the same thing using semantic classes:

<div class="hero">
  <h1 class="hero-title">Heading</h1>
  <p class="hero-tagline">Tagline</p>


2. Because it’s easier to build responsive sites

Imagine coding a two-column responsive grid whereby:

Here’s how this is typically done using visual and utility classes:

<div class="grid clearfix">
  <div class="col pd20 pd50 fs2 fs3">Column 1</div>
  <div class="col pd20 pd50 fs2 fs3">Column 2</div>


We’ve barely evaluated this simple component and yet there is significant pain already.

Here’s the same thing using semantic classes:

<div class="thing">
  <div class="thing-thingA"></div>
  <div class="thing-thingB"></div>


Think about how valuable a codified responsive grid system is. A visual layout should adapt to the content, not the other way around.

3. Because they are easier to find

Searching for HTML with a non-semantic classes will yield many results. Semantic class are unique, so a search will yield just one result making it easy to track down the HTML.

4. Because they reduce the risk of regression

Editing a visual class increases the chance of regression elsewhere. As semantic classes are unique, changes will only apply to the module in question reducing the risk of regression.

5. Because visual classes aren’t worth it

We may as well inline styles. It’s more explicit and reduces the CSS footprint to zero. But mixing concerns is impractical and removes our ability to cache.

Isn’t .red, for example, the exact same abstraction that CSS already gives us for free with color: red?

6. Because they provide hooks for automated tests

Automated functional tests work by searching for, and interacting with elements. This may include:

  1. clicking a link;
  2. finding a text box;
  3. typing in text;
  4. submitting a form; and then
  5. verifying some criteria.

Non-semantic classes don’t allow us to target specific elements. Adding hooks just for tests seems foolhardy.

7. Because they provide hooks for Javascript

Semantic class are useful for Javascript too. We can’t use visual classes as a reliable way to retrieve elements.

8. Because they don’t need maintaining

If we name something based on what it is, we won’t have to update the HTML again. A heading is always a heading, no matter what it looks like. The styling might change but this only requires a CSS update.

With visual classes, a change of style requires change to both HTML and CSS (assuming there aren’t any selectors available for use).

9. Because they are easier to debug

Inspecting an element with a multitude of atomic classes, means wading through many selectors. With a semantic class, there is just one, making it far easier to work with.

10. Because the standards recommend it

On using the class attribute, HTML5 specs say in

“[…] authors are encouraged to use values that describe the nature of the content, rather than values that describe the desired presentation of the content.”

11. Because styling state is easier

Consider the following HTML:

<a class="padding-left-20 red" href="#"></a>

Changing the padding and colour on hover is a difficult task. It’s better to avoid having to fix self-induced problems like this.

12. Because they encourage lean HTML

As we’ve seen above, atomic classes bloat HTML. Semantic classes result in smaller HTML. And whilst the CSS may increase in size, it’s cacheable.

Final thought

Semantic classes are a corner stone of MaintainableCSS. Without them, everything else makes little sense. So name something based on what it is and everything else falls into place.

Share on Twitter


  1. Introduction
  2. Semantics
  3. Reuse
  4. IDs
  5. Conventions
  6. Modules
  7. State
  8. Modifiers
  9. Versioning
  10. Javascript
  11. Organisation
  12. FAQs

Want updates?

Join my newsletter to get the latest MaintainableCSS updates and my usual articles about UX and front-end development.