DEV Community

Cover image for How to Build a SubAtomic Frontend Architecture
Max Antonucci
Max Antonucci

Posted on • Updated on • Originally published at

How to Build a SubAtomic Frontend Architecture

My current job has me handling a few things:

  • Improve our site's accessibility standards
  • Help people debug CSS issues, mostly Flexbox ones
  • During a full moon, watch for movement from the headless mannequins our CEO bought

These all matter, but the most important one isn't here: making and managing a system for our front-end assets. When I arrived our current one was a scattered collection of assets mixed with Bootstrap. We wanted one with better style documentation, component organization, and less dependence on frameworks.

It took a few tries, but ultimately I landed on a system that meets most of our needs. It relies on what I call a SubAtomic Frontend Architecture or SAFA for managing styling. We've been slowly integrating it into old projects, and a new one uses it for the entire frontend.

I'm happy/relieved/tempting fate to say it's been mostly well-received and helped us avoid common front-end troubles like:

  • Accidental overrides
  • Style at scale
  • Back-end focused engineers not knowing what the hell to do
  • Quinoa

That's why I wrote this post to describe this SubAtomic approach. My hopes are you take inspiration, try it yourself, give me credit, and I can ultimately have a small web development book deal as I ride into the sunset.

So join me in my quest and read onward!

What is a SubAtomic Frontend Architecture?

What I call a SAFA is basically writing CSS with 80% Atomic CSS, and 20% BEM (mostly Atomic, so it's SubAtomic, get it?). Writing the front-end this way has a few key steps:

1. Get, or Build, an Atomic CSS Framework

For those who don't know, Atomic CSS is building styles entirely (or mostly so) with helper classes. I won't go into the details (or controversy) here, but I refer you to this presentation making the case for Atomic CSS. I will say I was skeptical at first, but I and everyone I recommended it to have come around to it.

Our system uses a custom collection of helper classes since we wanted to avoid past dependency issues. If you're not restricted by that, TailwindCSS and Tachyons are popular options. At least see how these frameworks handle variables, responsive classes, and what styles to cover. There are a few parts of our current one I'd change based on how I saw Tailwind handling them now.

2. Build Your Site Using Atomic CSS Whenever Possible

Once the atomic classes are in place, get started and use them wherever possible! I've found the markup for many components can be written entirely with Atomic CSS, and can partially style the rest. So proper atomic styling saves a lot of time in the long run.

Let's look at my personal site as an example, which uses Tailwind. Here's the old footer markup styled only with helper classes.

<footer class="w-full py-2 text-white bg-teal-darker shadow-lg">
  <div class="flex flex-wrap max-w-md px-4 md:px-6 my-4 mx-auto">
    <div class="w-full md:w-3/4 md:pr-8 lg:pr-12">
      <p class="text-sm">
        Iā€™m Max Antonucci, a front-end developer in New Haven, CT...

      <p class="text-sm">
        See all my (hopefully) useful notes on blah, blah, blah...

Enter fullscreen mode Exit fullscreen mode

It's a lot of classes to look through, but it works. I can get a picture of the footer's appearance from the markup alone, adjusting styles is as easy as changing classes around, and I made it without writing any new CSS.

3. Use BEM Wherever Atomic CSS Doesn't Cut It

As wonderful as Atomic CSS is, helper classes can't cover everything. There are too many potential CSS properties and values, and covering them all with helpers asks too much of them.

Common exceptions to what Atomic CSS covers I've found are:

  • Layouts, which have many potential widths or grid setups. There are tools like the Bootstrap Grid, but I prefer writing my own layout CSS to avoid unneeded dependencies.
  • Frequently used components, like buttons or input fields. The more an element is used, the harder it is to keep all possible helper classes in sync. Creating reusable components solves this, but unless I'm 100% sure that markup is only in one place, Atomic CSS brings too much risk for me here.
  • Obscure styles or positioning, since there can't be a helper for every percentage value in absolute positioning. Please, no.

For these cases and more, I fall back to adding extra styling with BEM. Check out this article to fully understand BEM if you don't already. In short, it's a methodology for writing specific component class names, basically the opposite of Atomic CSS.

Your first thought may be "So if my atomic classes aren't enough, I should replace them all with one BEM class?" To this, I reveal my mind-reading and say that's not the case at all! The SubAtomic Approach uses BEM as a supplement to Atomic CSS, not a replacement. Any extra classes I write are used alongside the helpers.

This is best shown with an example. Here's the simplified HTML from my personal site's navigation. If you check out the class names, you'll see both a set of subliminal instructions and some items different from my last example.

<div class="bg-teal-darker text-white shadow-lg z-10">
  <nav class="flex flex-col max-w-md mx-auto">
    <div class="hidden md:flex items-center py-2 px-2 md:px-4">
      <img class="nav__logo mr-4 rounded-full" src="/assets/images/global/profile.jpg" alt="Maxwell's profile picture" />

      <p class="my-0 text-sm italic">

    <ul class="nav__main-menu list-reset flex flex-wrap md:flex-col mb-0 md:my-4 text-xs">
      {% for menu_item in %}
        <li class="inline-block mb-0 text-center">
          <a class="block p-2 text-white" href="{{}}">
            {{ }}
      {% endfor %}

    <ul class="list-reset flex flex-wrap md:flex-col mt-auto mb-0 text-xs">
      {% for social in %}
        <li class="inline-block mb-0 p-2 text-center">
          <a class="text-white" href="{{ social.url }}" target="_blank" rel="noopener">
            {{ }}
      {% endfor %}

Enter fullscreen mode Exit fullscreen mode

There are different classes are on the img and ul tags! The Tailwind classes covered about 95% of the styles I needed, but there was still styling they couldn't give me. So I used BEM to sprinkle on the last bits of CSS: a specific max-width and a translucent background cover.

.nav__logo {
  max-width: 100px;

.nav__main-menu {
  background-color: rgba(#005661, 0.75);
Enter fullscreen mode Exit fullscreen mode

That's all the CSS I wrote for this navigation! As of now, my entire site's custom CSS only needs 10 Sass partials, most only 10-20 lines long.

With that, you have the basics of the SubAtomic approach!

SubAtomic Trade-offs

I won't claim this approach is best for all projects, although it's at least worth considering. But to help others make this decision, I will list the major trade-offs I've found in my experience with SAFA. Just know these are subjective opinions, and may vary with other coders using it.

Faster, but Riskier

Atomic CSS benefits from speedy development with fewer decisions. It's easy to build and restyle components by just adding and removing classes. It's faster than the alternative I've dealt with:

  • Deciding on a class name for a new element or pattern
  • Deciding whether to place this class in a new or existing partial (and naming it if it's new)
  • Writing out common styles, like padding and margin, which were repeated dozens of times already
  • Make sure the values use style variables whenever needed, not hardcoded or magic numbers
  • Scream

This perk is better when front-end code is also being worked on by back-end developers, which is the case for me. The CSS is written ahead of time, and they just need to pick the write pieces instead of writing their own.

But with greater choice comes a greater risk of making the wrong one. It's easy to screw up a few classes anywhere in the markup. This can cause inconsistencies across common components, which are hard to root out amid a crowd of component classes (alliteration!)

You can lower this risk by documenting common helper class component combinations. Our style guide documents small things, like badges and styled links, with the right collection of helpers to recreate them. It isn't foolproof, but reliable references also make them easier to spot the mistakes that slide through. Limited documentation is a red flag when considering SAFA.

More Flexibility, but More Project-Specific Code

Structuring CSS around helpers means it can be used for lots of sites and interfaces. We don't need to build out UI elements specific to a project's needs, like a shopping cart or preview card. We only build the ones needed in virtually any project ahead of time, like buttons and inputs. The rest is either pure or mostly helper classes.

This saves more time for minimally styled elements. We don't need new classes for components that only need padding and a border. Slap two or three helpers on it and you're done without any unneeded CSS inflation.

But this also means any BEM code must be managed on a project-by-project basis. Between only three projects using a SAFA, there could be dozens of CSS files specific to each. They could also be written by different developers. This flies in the face of one main reason to use a framework, which is enforcing consistency and style guidelines.

One way to manage this is, of course, good documentation. That, and enforcing consistent code standards early on. But I've found this is tough, even with good code linters, and depends a lot on your team's willingness to learn. So if you're making a framework used over a large number of projects and developers, consider other options.

Wrapping Up

SAFA has been my CSS architecture of choice since it has everything I love about Atomic CSS and works to improve some of its drawbacks. Where I work it's much improved how we organize, document, and scale our frontend code in new and existing projects.

I hope other developers find it worth trying, although I think a few may realize they've already been writing something similar. But since I wrote a blog post first and gave it a name, I'll get the credit since that's how the world works in my mind.

Regardless, next time you need to choose a frontend architecture, please give the SubAtomic approach a try!

Cover image courtesy of

Top comments (4)

felipperegazio profile image
Felippe Regazio

Nice article Max, thanks. I really dont know what to think about Atomic Css yet. I have no real background with atomic css but some small projects. Anyway, in order to try, i made a css atomic library which exposes a collection of css properties and values as atomic classes in a very simple way


Its useful to see the atomic css approach working in a nutshell

I called the lib "HelpmateCss", and i will leave the link just in case

tomhermans profile image
tom hermans

Thanks for this article. Been re-thinking my way of working and somehow landed too on a utility classes approach. Instead of re-inventing the wheel went with Tailwind too and I love it. The initial idea is indeed "what is this?" but it makes so much sense. Good to see that others tried and proved this approach to be useful indeed.

applicafroguy profile image
Sivuyile Magutywa

I need to visit my CSS-Styles, Atomic CSS is way more readable than BEM, though I don't like writing to many classes in HTML, So thank you for this Article. Naming CSS classes is very hard for me.

maxwell_dev profile image
Max Antonucci

I agree, it definitely helps make them more readable from a "what will it actually look like" perspective. BEM styles could have any number of CSS properties attached, while Atomic classes are more explicit about things like padding, coloring, even responsive styles.

CSS Tricks recently wrote an article about ways to group these classes to help readability even more, is worth a look -