Atomic Design Coding Sanity: Naming Conventions for Easy Recognition

3 min readJan 3, 2017

I’ve coded a lot of websites over the last year using Brad Frost’s brilliant Atomic Design approach. I’m sold on the methodology and the clear approach to the building blocks that make up my code. The one area I found difficult, and without any clear documentation on, was naming conventions and easy recognition.

I had a chat with Brad Frost about different approaches towards naming and his wise words were:

At the end of the day, it’s about choosing conventions that make sense for your team. So if atomic design naming makes sense to apply to code structure, then by all means go for it!

I could code a client’s website today but not edit that code again for a year or 2, when the client needed some updates. By then what I name an element may be very different, or it might be someone else editing the code instead of me. So figuring out how to make code easy to understand for me, and anyone else working alongside me, is really important.

1. Unique: Make sure I know what is my code, and what’s not

Creating unique class names and IDs prevents any possible clash with plugins or other CSS components (like Bootstrap) that may be used in a project. So if someone installs a new plugin and it breaks something you will know it was not your code.

The most simple approach I use is to begin every class with hd (for Hidden Depth). Having all names begin with hd provides a really good overview when troubleshooting or editing code, so I know if it was my code or an external style. It makes searching (or doing find and replace) for a class a lot easier too.

This code could belong to anyone:

<div class="title"></div>

This is easily identifiable as my code:

<div class="hd-title"></div>

2. Group: An overview main stylesheet

The main SASS stylesheet imports everything for the project. Keeping this Atomic makes it easy to add new components or remove anything that is not needed for this project. I also follow a similar, but smaller, approach for Javascript files.

3. Prefix: with an Atomic Design designation

If I am styling the header for a website the style will be located within “scss/organisms/_header.scss”, so the class name I give the header will be hdo-header.

<header class="hdo-header">
   Content stuff here...
</header>

hda-name = atoms/name
hdm-name = molecules/name
hdo-name = organisms/name
hdt-name = templates/name
hdp-name = pages/name

This approach allows me to instantly know if any element is an atom, molecule, organism, etc.

4. Simplify: Atomic structure for internal elements and speed

A lot of components will contain a content area inside them. It is overkill to make something like:

<div class="hdo-hero">
   <div class="hdo-hero-content">Content goes here...</div>
</div>

Also the styles for this element will likely rely on it being inside hdo-hero. Any class names that contain hd- (without an Atomic Design prefix) means they are dependent on their parent container.

<div class="hdo-hero">
   <div class="hd-content">Content goes here...</div>
</div>

In my SASS file within scss/organisms/_hero.scss my styles for the content area will be inside the hdo-hero class:

.hdo-hero {
   my styles goes here...
   .hd-content {
      my styles goes here...
   }
}

5. Consistency: Follow the same naming for all file types, not just CSS

Let’s use a hero unit as an example. This hero unit contains a carousel of sliding images. The hero unit needs CSS to make it look nice and Javascript to making the images slide in and out.

Path to files:

PHP: /components/organisms/hero.php
Image: /img/organisms/hero/image-1.img
SASS: /scss/organisms/_hero.scss
Javascript: /js/organisms/hero.js

The SASS and JS will be compiled in with other files for the production version, but the original source files are located in the above locations for ease of use when coding.