Menu Search
Jump to the content X X
Smashing Conf Barcelona

You know, we use ad-blockers as well. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf Barcelona, dedicated to smart front-end techniques and design patterns.

The “Other” Interface: Atomic Design With Sass

As front-end developers and designers, we’re constantly refining two interfaces simultaneously: one for visitors who load the website, the other for developers who have to tackle the code in the future, when adjustments or full-scale redesigns must be made. Yet we tend to assign the role of “user” to the first group, often forgetting that the code we write must work for developers in a similar way. We shouldn’t forget that developers are users, too.

If this is the case, then our convention for naming and organizing files is critical if we are to ensure active (and efficient) development in the future. But do we really design the partials, files and directories that make up this interface with a particular set of users in mind, with a set of clear goals, combined with precise, well-defined documentation? I don’t think we do.

Further Reading on SmashingMag: Link

Recently, I’ve been working on many different projects, each wildly different from each other. And the various problems I’ve faced while switching between the projects has made me wonder how we can drastically improve front-end accessibility.

We Need To Follow Atomic Design Principles In Our Style Sheets Link

Last month, in a post titled “Atomic Design5,” Brad Frost argued that Web development could be improved. He suggested to developers that, instead of coding a form as a component that is reused throughout a website, they could style small modules — such as a placeholder, input field and text field — and then create each form by combining these chunks together. This process could be duplicated for navigational items, text with icons, floated objects and pretty much any other sort of front-end module that needs to be reused regularly.

(Image: Brad Frost)

“Atomic design gives us the ability to traverse from abstract to concrete. Because of this, we can create systems that promote consistency and scalability while simultaneously showing things in their final context. And by assembling rather than deconstructing, we’re crafting a system right out of the gate instead of cherry picking patterns after the fact.”

The theory is that by employing these distinct elements, a developer can speed up their workflow and write code more efficiently because they’re not forced to repeat themselves. This much appears to be common sense. Essentially, what Brad calls for is object-oriented design7, which has been discussed in numerous articles and blog posts recently. That isn’t really what interested me about the idea, though — it was the naming convention that Brad chose.

He uses scientific terms to quickly describe what sections of a design should do; “atoms” are the discrete chunks (placeholders, labels, etc.), while “molecules” are combinations of these standard atoms. The simplicity here grabbed my attention, because ultimately what we’re discussing isn’t just a process for design, but also a distinction to be made in the user interface, as I mentioned earlier.

Problems With The Front-End Interface Link

Before we retroactively squeeze some of Brad’s ideas into our current workflow, we have to figure out precisely which problems need to be solved. So, as I switched between my projects, I started to take note of the flaws that appeared to be wasting much of my time. By the end, I counted three main problems that affect the developer’s workflow:

1. Finding Code Should Be Easy Link

Although I had written some components with Sass early on in a project, I found that towards the end, I was simply incapable of remembering where in the stack I needed to make adjustments. This forced me to try to memorize where each block of code was and had me scurrying around, completely lost, even with the advanced search features of a great text editor.

Developers are probably quite familiar with Sass8 files, which contain thousands of lines of code. The legacy Ultimate Package9, a tool that we used as a boilerplate for all of our front-end code at Erskine10, also contained that unfortunate mistake. The main problem with keeping all of this code in one place and not breaking the files into smaller parts is that you’re likely to forget where a particular section of code is. This eventually wastes the developer’s time and could slow down the project considerably.

Of course, these problems become infinitely worse when you must navigate someone else’s project or an entirely unfamiliar code base.

2. Figuring Out the Relationships Between Modules Should Be Straightforward Link

Whenever I try to add a component to an old website, I have to figure out the mental model of the relationships between elements. I have to wonder how removing a portion of the website would affect another totally unrelated thing elsewhere. This could be a background color or margins or padding or even the order of elements in a module (such as an image in a comments section combined with text from the same object).

Nicole Sullivan mentions in her fantastic talk at Webstock11 that these elements can become so interwoven with one another that they pose hurdles down the road. This problem often forces me to move from the text editor to the Web inspector and manipulate elements by hand in order to get an idea of how things work together, and then move back to the editor to make the fix.

This is unnecessarily slow and cumbersome. With atomic design, we would know precisely how one element affects another; we wouldn’t have to worry about editing components, or even adding new ones.

3. Websites Need Tailor-Made Components Link

Sometimes a design requires a component that is never reused, a sort of one-of-a-kind12 embellishment that sparks interest or delight in the user in some way. If it were repeated, it would become boring or, worse, repellant. Ideally, a new organizational system would allow for the sort of design components that Allen Tan describes in his article “Made to Measure13”:

“Design is about establishing a set of relationships between elements. By codifying these relationships as a set of principles instead of a single, stand-alone template, we make it possible for other designers to extend our work (per article) while remaining faithful to its core ideas.”

Yet we know that these minute design variations can quickly turn into a royal pain. Having to maintain all of these various fluctuations of commonly used structures would turn most projects into very hostile coding environments.

Of course, if we used some of this atomic design thinking, we wouldn’t have to worry about unnecessary code bloat when we add a fancy banner or an alternative text style to a figure. Hopefully, it would encourage us to scope components of the code base so that another user could easily identify which objects are global and which are specific to a single template or module.

What we need to do here is group components according to the sort of effect they might have on the entire system. Atomic design to the rescue!

The System Link

Last month, I stumbled upon the wonderful Inuit.css14 framework, which is probably the best place to start learning if you’re unfamiliar with modular design in Sass. After a few moments of playing around, I saw that this is a phenomenal step forward for developers and designers alike. It employs BEM’s syntax15, object-oriented CSS16 (OOCSS) and many aspects of atomic design, which all might seem a little overwhelming at first but is definitely worth going through because you’ll likely see the advantages soon enough.

The problem I had with Inuit.css was with its naming conventions. What was contained in the base17, generic18 and object19 directories wasn’t entirely obvious. These relationships should be obvious and immediate; developers shouldn’t have to read hundreds of lines of code and tediously experiment in order to be able to fix a bug or add a feature.

So, I decided to fork my own version and combine these atomic design ideas with the principles of BEM and OOCSS from Inuit. I’ll describe this alternative convention here. Now that we’ve discussed some of the key problems, we can look at how atomic design can help us.

The Control Panel Link

First, it’s worth mentioning that we’ll have a style sheet that imports20 all of the Sass partials we’re about to make. Think of this as our control panel, because in the future we won’t want to write all of our code from scratch; for most projects, we’ll just want to set things up quickly and turn an object on or off. All of the partials will be compiled to this file before we convert it to plain old CSS and serve it up to our website. So far, so good.

Utilities Link

Atomic design encourages us to first think as vaguely as possible, and then to focus our energy on the smallest pieces later. This means that we need a set of system-wide styles to begin; this directory of Sass files will need to define the foundation; effectively, what’s required is a set of utilities that make up the basic plumbing of the website. This directory of partials is also important because we’ll need to define global classes, mixins and styles that can be used anywhere and at any time. Our utilities directory might look something like this:

Breakdown of the files within the utilities directory: base-spacing.scss, cleafix.scss, reset.scss21

The code in our reset, clearfix and base-spacing partials have a global impact, changing almost every page, template, element and module. By scoping our code in this way, we can easily find these partials later and hide them when our focus is needed elsewhere.

Quarks Link

Next up, we ought to define the basic building blocks of the website, including paragraphs, tables, images and links. Be careful here: We need to slowly build up to the complexity that is required so that we don’t step on our own toes later. At this stage, we should still be thinking globally and not styling for any particular section of the design.

Therefore, this next directory should focus only on default HTML elements. I’ve started to call these components quarks — classless objects that, within the files themselves, contain nothing more than a few elements:

Breakdown of the quarks directory: lists.scss, paragraphs.scss etc.22

Note that these files contain only the default styles for these elements, not modified elements. For example, if we have a table that looks and works entirely differently from the default tables used throughout the website, it would not be a quark.

This system might look like overkill at this point. Why do we need a separate partial to style almost every default element individually? My argument is that if we were to combine all of these small pieces together, we would make the files less readable, especially on a large website. Having a substantial number of partials is fine, as long as they’re easy to find and organized properly.

Quarks are also helpful when we set up a style guide or an elements template page that lists the various default components of a project.

Atoms Link

Now we need to start thinking about the relationships between these quarks, and so we start to introduce aspects of BEM and OOCSS. In this system, I’ve called these modules “atoms” — universal abstractions, such as the media23 or flag24 object. For example, we might include a partial that sets the default style for buttons, so that we can plan for those styles to be extended and built upon:

Breakdown of the atoms directory: media.scss, buttons.scss etc.25

The styles in an atom should almost never be attached to an HTML element itself; we might not be able to guarantee what the markup will look like in the future. Specifying a class instead is always safer.

In this way, atoms will save us from writing hundreds of lines of code and keep things relatively abstract. Just as Brad suggests, this concept is powerful because atoms can be combined to form more complicated structures.

Molecules Link

As I mentioned earlier, sometimes we need one-off structures, such as a banner or navigation element or footer, that we don’t intend to replicate. This is where we can combine multiple quarks and atoms, without interfering with any of our global styles:

Examples of files from the molecule directory: banner.scss, footer-nav.scss26

A molecule can take advantage of an atom for layout (such as the heading-group molecule, which might manipulate the styles of the heading quark, which lists the styles for h1, h2 etc.). But then, within this molecule, we can extend, modify and combine other styles and modules.

So, while atoms and quarks define rigid and clear rules for the system overall, and utilities provide the outlining structural styles necessary to keep things tidy, the molecules are where the design can be more flexible and extend styles out from those central tenets of the system.

As you can see, quarks, atoms and molecules break up those monster Sass files that I mentioned earlier and make code faster to read and easier to maintain in the long run.

We Need To Revise Our Current Best Practices Link

Although the system outlined here is pretty rigid, these are not die-hard rules. This is not the only way to organize styles with Sass, and I’m not arguing that it’s a panacea for our front-end woes. I’m simply proposing that we take a good look at the developer interface and try to make things better for everyone.

This system could even be based on another kind of taxonomy or categorization, completely unrelated to biology or chemistry. But, as you can see, this is more than just a goofy way to name files and directories — rather, it suggests the kinds of relationships between these independent components. Thanks to this system, our code should be much faster to read and organize and, alongside detailed instructions and documentation27, enable another Web developer to be up and running in minutes.

In the past, directories and file names were often poorly designed navigational tools. But if we think long enough about the other interface (the one for developers) and about alternative frameworks and helpful tools to make our code base more human-readable, then we can finally put some of these problems to rest and worry about other more elusive issues.

Relevant Talks Link

(al) (ea)

Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
  18. 18
  19. 19
  20. 20
  21. 21
  22. 22
  23. 23
  24. 24
  25. 25
  26. 26
  27. 27
  28. 28
  29. 29
  30. 30

↑ Back to top Tweet itShare on Facebook

Robin is a writer and designer. You can follow him on twitter.

  1. 1

    Good to read… thanks for introducing the methods.

  2. 2

    Travis Miller

    August 2, 2013 5:48 am

    “This problem often forces me to move from the text editor to the Web inspector and manipulate elements by hand in order to get an idea of how things work together, and then move back to the editor to make the fix.”

    Regarding this … I don’t know if you looked into it yet, but you Combine DevTools Autosaving with Sass Source Mapping, You can skip the back and forth and do your edits in the browser. Speeds up workflow and helps with the sanity haha

    • 3

      Yep, I’m familiar with Source mapping but the problem isn’t solved in any meaningful way with that tool. If we were to think about this like constructing a building then we need new ways to create the blueprints, instead of making better drills.

  3. 4

    Excellent article. I’ve been working my way towards this kind of organization over the last few projects but haven’t been splitting things down quite that far, yet.

    I generally have a Reset.scss and Base.scss which i guess is like your utilities files, then I have a middle layer which is close to your “atoms”, like typography.scss, gradients.scss, mediaQueries.scss etc. Then I have a generic.scss where I put shared modules, then finally a pages.scss for page specific styles.

    What I haven’t done is split it down further to have a “quarks” layer, but that’s just personal preference.

  4. 5

    John Slegers

    August 2, 2013 9:22 am

    If you like the benefits of combining OOCSS with SASS, keep an eye out on Cascade Framework ( ).

    Cascade Framework is a relatively new responsive modular OOCSS framework that shares many design principles with Inuit. While Cascade Framework 1 is written in plain CSS, Cascade Framework 2 is currently under development and will be reimplementation of version 1 into a Sass 3.3 metaframework.

    By making clever use of new features added in 3.3, the Cascade Framework 2 metaframework will have a very powerful architecture that allows you an unprecedented combination of optimal code readability and control with optimal CSS output and flexibility.

  5. 6

    Absolutely beautiful.

    I personally love the naming convention (especially breaking Atoms down into Quarks ;) ).

    As a developer who often crosses the line between front-end web development and spending much time in object oriented Python projects, this approach makes perfect sense.

    As much as it may seem like overkill, I can retrospectively see where this type of set up would have saved me hours of searching/editing/restructuring existing CSS in the past.

    Smashing Magazine, thank you again for being awesome.

  6. 8

    Sooo do you mean something like this? A decouple of sorts?

    .padding-left($var) { padding-left: $var; }

    Instead of

    .push-button-padding-left{ padding-left: 0.2em}

    OR a thematic method:

    .give-it-the-push{ Button style code

    Trying to see a real world example rather then trying to dig through someones new hot framework and mental methodology to reach

    .button { padding-left: 0.2em; background-color: green;}
    • 9

      Your question is more of a generic ‘using mixins rather than loads of classes’ question than an Atomic Sass structure one I think.

      If ALL of your buttons on your site are going to have the same padding and background colour, then you may as well define them as you said:

      .button { padding-left: 0.2em; background-color: green; }

      However if actually they all need to be green but the padding differs dependant on context, you’d define

      .button { background-color: green; }

      as an atom and add the correct padding in the molecule definition later on in your code.

      .article .button { padding-left: 0.2em; }

  7. 10

    @smashingmag @robinrendle Lovely article! FYI “object-oriented design” link gives 404. Please fix? Should likely be:

  8. 11

    Brett Jankord

    August 3, 2013 3:54 am

    It’s always interesting to hear how others are architecting their CSS. I like Brad Frost’s atomic design concept.

    Have you heard of SMACSS by Jonathan Snook. I find it to be very useful for how I architect my own CSS and it seems like it shares similarities to the approach you describe here.

    Jakob Hilden has written up a really nice article on combining SMACSS with Sass that may be of interest to you.

    • 12

      I totally agree, SMACSS is a must read for any developer that’s looking to improve this sort of system-wide thinking.

  9. 13

    Random, but what are you using to display your folders like that? Looks cool.

  10. 15

    Adrian Zumbrunnen

    August 3, 2013 10:14 pm

    Very nice post! Definitely going to try this in my next bigger project. I usually go with a less rigid structure.

    I usually have a Helpers.scss or Globals.scss where I have stuff is used globally. Other than that I just have modules like…


    In then assign a class like mod__sidebar to the element and start the SASS with this as the highest instance. Like this I get a highly encapsulated CSS and it’s really easy to manage. It depends on the size of the project though I guess!

  11. 16

    Jakob Løkke Madsen

    August 4, 2013 12:13 am

    Really good post!

    I think I like the chemistry naming convention – although it’s still a bit abstract. :)
    I’ve actually just recently written a post on how I think such abstraction names should be grown:
    It touches on many of the same problems outlined in this article.

    • 17

      I really like your approach, and it looks like we’re trying to solve the same problem. Hopefully more devs start contributing to this idea, because there are plenty of pressure points and questions left to be answered.

  12. 18

    I’m glad you found inuit.css. I stumbled across it when it was in its infancy. Because he made the switch to SASS, I too made the switch. It is by far the best grid system I have ever used.

    Anyways, I love how you combined the atomic and bem/inuit organization. BEM makes the most sense out of everything I read. It is so easy to hop back on a project later on and do exactly what you need to do. I too did not like how inuit broke out everything, but I work primarily on WordPress projects and there is a lot more css that has to be included. May start using your Quarks/Atoms naming!

  13. 20

    Mason Thornberg

    August 5, 2013 6:14 am

    Can you add some examples of some quark and atom classes that build up to a molecule element?

  14. 21

    Justin Wilson

    August 4, 2013 10:14 pm

    Hey, Robin. You said you forked your own version of Inuit to include these principles? Where can I find that repository? I’d like to check that out.

  15. 23

    Great article!
    I have had the same concerns about “Problems With The Front-End Interface” and I am currently working on a CMS which is quite different from any other CMS I have seen. It is actually built to those problems you mentioned: Finding code is foolproof, the relations between html, css, js and php are well-organized and using tailor-made components is dead easy .

    Its structure is pretty unconventional and significantly less complicated than most popular CMS (e.g. WordPress, Joomla, Drupal, …) hence it lets you manage your contents, scripts and design(s) in a very simple way.
    Frameworks such as Inuit.css or 960 Grid System are also very easy to integrate.

    Drop me a mail if you’re interested in a sneak peak!

  16. 24

    Very nice article.

    if you’re working with SASS + Compass, Sassaparilla appears to have been built with some of this ideology in mind, separating _extends, _mixins, _typography, etc., for you. It’s just enough to get you started, but one could easily continue to expand on this.

    I did for the next version of LiveNinja, so now I’ve got partials for buttons, modals, triggers. It’s a very intuitive way of finding what you need.

  17. 25

    Maybe I haven’t messed with a website big enough to need this, but it seems a little unnecessary to have so many _atom.scss files for mixins that can be placed at the top of a main stylesheet or even just an imported _funcs.scss.

    One thing that I’ve noticed is that everyone has their “methodology” but when it comes to working with a team of developers, some hipster front-end dev tries out “Atomic whatever” css architecture just so the next dev is throwing chairs.

    You want to be an ace front end developer. control your code, don’t nest more than 4 times within an id (and for god sakes don’t nest more than one id), and make reuseable mixins that actually do real work. not make a button.

  18. 26

    I’m really surprised I don’t see any notion of SMACSS in this article (see Brett Jankord’s comment above). Because while Brad Frost’s ideas are interesting and this really is a great way to develop, Jonathan Snook already has developed a tried method of working like this. And to me SMACSS looks more complete than the ‘Atomic’ method.

  19. 28

    adolf witzeling

    August 6, 2013 12:22 pm

    Great article and very interesting and informative read.
    Being “only” a designer, even to me this system or naming convention makes perfectly sense. I do a lot 3d stuff (Maya etc.) and I really like the “Node Based” structure or modules as it is called in the webbers universe.
    In Maya it’s pretty straight forward to pinpoint problems should they arise and to add in (or remove/replace) as many nodes as you want, just plug in the nodes.

    Wonder why that’s not possible in web front end design, a visual module system with packages containing all the atoms, molecules and so on?
    Sorry if that’s a stupid question but I’m very interested in this part of front end web design and a system and naming convention as described in this article would make work easier for everyone involved, even just designers. Go atom!

  20. 29

    If you have two widely-used presentations of the same element (say an unordered list, which 50/50 is either shown as a bulleted list, or presented as a different thing while semantically being one), is one an atom and the other a quark?

  21. 30

    Cary Hartline

    August 10, 2013 11:43 am

    This is a neat idea, but I think it should only be used during the development process. The large amount HTTP requests to gather each style sheet would slow down a website by a lot.

  22. 32

    How do you handle stateful markup? For example, if I have a style for textareas and inputs when their parents are set to aria-invalid="true", what’s the appropriate place for those styles? I could see it going into the quark, since every textarea should behave that way, but I’m not sure if that’s too much information for a single quark.

  23. 33

    In as the author hasn’t replied yet I thought I’d try to find out if his new spin on atomic design might have a repo anywhere. I found an earlier version of this article on his blog,

    and from there I was able to track down his GitHub repo which has the utilities, quarks, atoms, and molecules sass directories he was describing.

  24. 34

    I’ve found that ZURB’s Foundation 4 framework, coupled with SASS and Mixture, provides something very similar to what’s described in this article. You’re instantly provided with a project that has all the different .scss files set out – things like tables, labels, forms, tooltips, the grid, etc are all kept in different files, but then they’re all imported into a single CSS file which is automatically minified when Mixture compiles your project – so it’s a great solution both for development and production stages of a project.

  25. 35

    I am sceptical that this is an over simplified idea, and an old idea repacked. Its a business plan for creating a “website builder tool”, not a unifying theory.

    I outlined my feedback in a comment on Brad Frost’s blog… but two weeks later he hasn’t accepted the comment. I wonder how much other negative comments are dropped?

    Roll on the next reuse idea that flattens all technology before it. And may they all have “navigation” as their only example.

  26. 36

    Check out for several navigation elements implementing an atomic CSS design pattern.

    You can also check out for an entire CSS framework based on Atomic CSS design patterns.

  27. 37

    Bernard Skibinski

    December 14, 2013 8:57 am

    Love this article, and especially the physics naming convention! it makes good sense.
    Also happy to see i was on the right path with my own base template, breaking down elements into smaller and smaller parts, and using one main stylesheet to include all the partials. Making it easier to manage partials, the order of output, and the ability to easily enable/disable partials.

    little bit offtopic:
    I’m a drupal front-ender myself, and while I love all these techniques, it’s still a shame no CMS (as far as i know off) is aware off the classes you are using, or gives you a list of classes/ID’s that are being outputted by the CMS.
    Let me explain: It would be awesome, if the CMS was aware what classes you are using in your (SASS)stylesheets, and would also be able to tell you what classes it is outputting, like a styleguide.
    It would make it possible to see which styles might not be used anymore (at the end of a project) and make cleanup more safe. Also the CMS would be able to remove all the classes and ID’s that aren’t defined in your stylesheets.
    And lastly you could do cool stuff with it like converting easily readable classnames (e.g. .float-right, .font-size-small, etc) to short classes (.a, .b, .ab, .xgd), for saving filesize. You could then easily switch from development mode to production. And maybe you could do even cooler stuff, I haven’t thought about yet.

    This is unrelated to the article itself, but i keep having the feeling, this is the last step we need in making CMS output and CSS styling “smart”, and thus taking away many hurdles we have to take now (naming convention could become more verbose and readable, without making filesize larger).
    Best would be a system that’s universal for every CMS, but that’s just utopian thinking I guess ;-)

    Until that time, i’m going to refine my template with lessons learned from this article!

    PS. I know there is HAML, but that is not making the CMS “aware” of your stylesheets. Although looking at Google’s stylesheets, they might have a system like i’m proposing?


↑ Back to top