Chapter 2


Semantic HTML isn't only 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. What's less obvious is the names we use for classes.

As Phil Karton says, “there are only two hard things in Computer Science: cache invalidation and naming things.” So spending a whole chapter talking about naming is essential.

Naming is the most important aspect of writing maintainable CSS. There are two main approaches: the semantic approach and the non-semantic approach.

Semantic vs non-semantic

<!-- non semantic -->
<div class="red pull-left pb3">
<div class="grid row">
<div class="col-xs-4">

<!-- semantic -->
<div class="basket">
<div class="product">
<div class="searchResults">

Non-semantic classes don't convey what an element represents. At most they give you an idea of what an element looks like. Atomic, visual, behavioural and utility classes are all forms of non-semantic classes.

Semantic classes don't convey their styles, but that's fine—that's what CSS is for. Semantic classes mean something to HTML, CSS, Javascript and automated functional tests.

Let's look at why semantic classes usually work best.

1. Because they're 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 HTML with semantic classes:

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

2. Because they make it easier to build responsive sites

Imagine coding a two-column responsive grid whereby:

With non-semantic classes it may look like this:

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

With semantic classes it looks like this:

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

Question: how valuable is a codified responsive grid system? A layout should adapt to the content, not the other way around.

3. Because they're easier to find

Searching HTML with non-semantic classes yields many results. Searching HTML with semantic classes should yield one result which makes it quick to track down.

4. Because they reduce the chance of regression

Updating a non-semantic class could cause regression across multiple elements. Updating a semantic class only applies to the specific module, eliminating the risk of regression.

5. Because visual classes aren't necessarily valuable

Atomic CSS and inline CSS aren't totally equivalent. For example, inline CSS can't use media queries and styling in HTML stops us from being able to cache it.

But, in some ways we may as well use inline styles—at least it's explicit and reduces the CSS footprint to zero.

Question: isn't .red 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. For example, a test might involve:

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

We can't use non-semantic classes to target specific elements. And adding hooks specifically for tests is wasteful as the user now has to download extra code.

7. Because they provide hooks for JavaScript

We can't use non-semantic classes to target specific elements in order to enhance them with JavaScript.

8. Because they need less maintaining

When you name an element based on what it is, you don't have to update the HTML. That's because, a heading, for example, is always a heading, no matter what it looks like.

With visual classes, both the HTML and the CSS need updating—assuming there aren't any selectors available for use.

9. Because they're easier to debug

Inspecting an element with multiple atomic classes, means having to wade through many selectors. With a semantic class, there's only one which is much 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 this HTML:

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

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

12. Because they produce a small HTML footprint

Atomic classes create extra code in HTML. Semantic classes result in less code. And while the CSS may increase in size, it can be cached.

Final thought

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


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