Atomic Design: A practical interpretation from one developer

Before reading this blog post, it’s worth reading at least chapter 2 of Atomic Design by Brad Frost: https://atomicdesign.bradfrost.com/table-of-contents/
Don’t worry — it’s not that long.

Foreword
I am a Software Engineer in Partner Tooling, mostly focussing on Front End development. We use React and have followed Atomic Design principles when trying to organise our components. This blog post is my opinion on how to practically implement Atomic Design, suggesting some guidelines to follow in addition to the textbook definitions. By no means am I stating that the approach put forward in this post is correct.

What the book says about atomic design

Atomic Design puts forward a suggestion on how to organise components into 5 categories: Atoms, Molecules, Organisms, Pages, and Templates. Each category growing in complexity as you go up the list; except for Templates which are more like skeletons for Pages.

This is exemplified best in this image:

What the book doesn’t say
Atomic Design is an idea, not a concrete practical framework. It might actually apply more directly to design, rather than development. In order to remain implementation agnostic, it leaves lots of decisions up to the developer that might not be obvious on the surface. In attempting to follow Atomic Design, you may find yourself asking questions like:

“This component only consumes UI library components, does that make it an atom, or a molecule?”

“This component feels quite big, and is definitely a molecule. But at what point does it become an organism?”

“This component relies on an API call, does that effect its classification?”

In this blog post I am hoping to resolve lots of these questions within the context of how I approach React development, by adding onto the definitions and adding additional guidelines.

Atoms

• Atoms should be indivisible, hence the name. They form the “foundational building blocks” of your application.
• Should be generic: designed to be reusable in any context, not have opinionated implementation details.
• Should feel lightweight, performant, and accessible.
• Should consist of basic elements only, not other components.
• Should be tested via unit tests.
• Can contain stateful properties, if necessary, but consideration should be given if it is needed at this level. Consider putting stateful properties in the Molecule level.
• Should not make API calls or be otherwise tied to APIs.

Molecules

• Preferred to be reusable, however sometimes implementation specific Molecules are necessary. E.g. “Selector” and “HomepageSelector” are both valid Molecules, but consideration should be given to the necessity for the later.
• Should follow the Single Responsibility Principle, despite being a composition of Atoms, should produce one functioning element.
• May consist of multiple atoms and html elements.
• May contain stateful properties
• May contain API requests.
• Should be tested with unit tests, could have end to end/synthetic user tests.

Organisms

• May be reusable but may also be implementation specific. For example, a footer bar will be very reusable, however a TableFilters organism may also be equally valid, but specific to one table.
• Will consist of one or more Molecules and can have additional html elements. Possibly one Molecule repeated many times.
• Should be a standalone portion of the interface and avoid depending on other Organisms.
• Will likely contain API requests and stateful properties
• Might be tested with unit tests, might be tested with end to end/synthetic tests

Pages

• Specific instances of Templates (if they exist), orchestrating Organisms and other components into a fully functional webpage.
• Likely to make API requests and contain stateful properties.
• Should be tested with end to end/synthetic user tests.

Templates

• Not a “bigger organism”
• Page level objects that “place components into a layout and articulate the underlying content structure”.
• Personally, we rarely implement these in React, but a full-page design in figma could be considered a Template.

Practical examples of components classification
When trying to decide what to classify a component as, it is helpful to start “bottom up”, and settle on the lowest categorisation that fits. If the component doesn’t break any of the guidelines of what makes an atom, it is more than likely an atom. If it breaks one of the guidelines, it could still be an atom, but might not be. If it breaks many of the guidelines, move on to assess if it is a molecule, and so on, until you find the smallest classification that best fits the component.

Sometimes, the purpose or intention of the component is the most important factor in deciding its category. An organism component may be quite simple, but its intention, role, or purpose can place it solidly in the organism category, despite it perhaps not meeting many of the expected criteria. You may often hear developers referring to this in terms of a component “feeling” like an organism, or “feeling more like a molecule than an atom”. This blog post aims to disambiguate the classification of components as much as possible, but do not ignore this developer intuition, as its all 1s and 0s at the end of the day.

The following examples, using real components that have been simplified for the purpose of this post, should give you a good understanding of my thought process when categorising several different components.

An example of an Atom component

Here we see a component that is very simple. It is indivisible, containing only one element. It has a colour property, but it isn’t stateful. While it does contain a component, it is a very simple Chakra UI component. Sometimes Chakra UI components may make this component feel like a Molecule, in this case it is very simple so fits within the Atom category.

An example of how Atom components can sometimes appear “big”

Here we have a component that takes a few props in, has a non-stateful property, a little bit of logic, and returns one of two elements. It could be conceived that this component is a Molecule, but in my opinion, it is still an Atom. The result of executing this component is still one element, even though it is not always the same element. You could argue that due to the conditional rendering, the component is “divisible”, but in my opinion that isn’t a big enough justification to warrant upgrading it to a Molecule.

An example of how sometimes, Molecules can appear small.

Here, we see a component that is composed of one element, possibly indicating that it might be an Atom. However, the element it returns is itself an Atom — the first clue that it probably something larger. Combined with that, and the fact that this component makes a web request, it should be considered a molecule. This is a good example of where the book falls short of a real-world implementation: as this is indivisible, it could be considered atomic — but in my experience this component is “larger” than an atom, even if it only returns one element.

An example of a typical molecule

Here we see the simplest form of a molecule; there is very little going on beyond composition of multiple components. This immediately disqualifies it as an atom, and with a lack of further complexity it falls solidly into the molecule category.

An example of an organism component

This component appears to be quite simple. It has no state or properties, and simply organises a few elements into a particular layout. Due to its use of several elements it is clearly not an atom. It could be considered a molecule, then, if it were not for one key factor: the elements (ExportButton, PageSizeSelector, Search) are all molecules themselves. This places this component firmly in the organism category, despite it being otherwise simple.

An example of a Page component

This component highlights the importance of the purpose of a component being a key indicator for its category once you get to the organism/page level. Just looking at the code, it could be argued that this component is a molecule; the component only uses atoms or simple Chakra UI components, and places them in a logical layout. It doesn’t have any complicated state, hooks, api calls, etc, and so appears quite simple. However, the components’ purpose (perhaps given away by its name) is to function as a homepage or landing page for our website. In our case, this is a very simple page with nothing but a login button, essentially. This meets the criteria of the page category because the purpose of this component is to function as an entire… well, page. It just so happens that this is a relatively simple page, only containing some molecules.

Why isn’t it an organism? It probably would be an organism if it were orchestrating a section of the user interface, as opposed to a whole page.

An example of a typical Page component

This component is the largest example yet, which is probably a giveaway that it is a clear-cut example of a page. Firstly, there are tons of stateful properties, a couple useEffects, a couple API calls, and a few helper functions. This should be the first indication that it’s probably not an atom or a molecule. The distinguishing characteristic here is that the components that are being consumed within this component are already organisms. Add that to the fact that the purpose of this component is to be a whole page, as discussed previously, and it should be clear that this component is categorised as a page.

Hopefully these examples help with classifying your own components within Atomic Design. I would be interested to hear other people’s strategy for organising components, within Atomic Design or not.