Constructive Group Created with Sketch.

Atomic Docs: Awesome or Awful?

Atomic Design is the concept that we aren’t designing pages anymore. Rather, we’re designing systems of components. In short, we can start with atoms, such as a title, a byline, or a link. From those atoms you can create molecules and organisms, i.e. a blog post preview or site header. Our page templates are then made up of different combinations of our organisms. Atomic Docs is a new tool that manages your components (and their underlying code) and automatically generates a frontend style guide. I recently came across it in an article and wanted to put it to the test to see how it would impact my workflow. Here are my takeaways.

Easy Setup

Atomic Docs was very easy to get started with. I set up a WordPress site with our distro and starter theme. Then, I downloaded the source files from github and moved them into the root of my theme. That’s pretty much it. I simply needed to change the destination CSS file path in our gulpfile.

Naming Things

One of the hardest and most important tasks of a frontend developer is naming things such as classes, ids, field names, filenames, etc. The names we choose must convey meaning to other developers, designers, and site admins and the choices are endless. Atomic Docs makes this task much simpler. The user interface is intuitive and easy to use and you can easily rename your components and categories, saving you from needing to go into many different places in your project to manually change names. The best part is, it generates all the SCSS and PHP partials you need for development, and puts them in organized folders and in the proper order. The extra head space Atomic Docs provides allows you to focus on what your components will be called, rather than where they will live and if they’re in the right place in your folder structure.

Design Driven Development

As the name suggests, Atomic Docs is a great tool for the Atomic Design process or Style Guide Driven Development. Atomic Docs isn’t limited to these processes though. The practice of developing and designing your user interface separate from backend technology can benefit any team. You can also deliver a living style guide to your client and design team for future use.


BEMr’s Beware

When using Atomic Docs, it’s important to remember to name categories and components the same way you would manually. Most importantly, do not use spaces, as filenames with spaces are obviously invalid. This is not a major fault, however, it wasn’t clear initially that there was a one-to-one correlation between the generated filename and the name you assign it in the tool. This is also worth noting if you use BEM naming conventions. Filenames have the potential to get a little confusing when you get down to the Modifier level as you can see in the screenshot above.


Atomic Docs is awesome! It delivers a great developer experience for creating and managing SCSS partials and makes it easy to create a living style guide. I’m looking forward to utilizing it on my next project.

If you’d like to learn more, get in touch!

Copied to clipboard http://...