If you are wondering what is Atomic Design and how to apply it with Sitecore JSS then this blog post is precisely what you need to read. This blog post is so far my longest drafted blog post and it took me precisely 23 months to sharpen it and release 🙂
We have started using Atomic Design to help us improve speed of creating new components and pages as we had good portion of repetitive design elements.
But first things first…
What is Atomic Design?
Atomic design is composed of five distinct stages working together to create interface design systems in a more deliberate and hierarchical manner. The five stages of atomic design are:
- Atoms
- Molecules
- Organisms
- Templates
- Pages
- Atoms serve as the foundational building blocks that comprise all our user interfaces. These atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional.
- Molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule.
- Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms. These organisms form distinct sections of an interface. For example, top navigation, footer are good example of organisms. Organisms can consist of similar or different molecule types. A header organism might consist of dissimilar elements such as a logo image, primary navigation list, and search form. We see these types of organisms on almost every website we visit.
- Templates are page-level objects that place components into a layout and articulate the design’s underlying content structure. For example, we can take the header organism and apply it to a homepage template. This homepage template displays all the necessary page components functioning together, which provides context for these relatively abstract molecules and organisms. Another important characteristic of templates is that they focus on the page’s underlying content structure rather than the page’s final content.
- Pages are specific instances of templates that show what a UI looks like with real representative content in place. Building on our previous example, we can take the homepage template and pour representative text, images, and media into the template to show real content in action. In addition to demonstrating the final interface as your users will see it, pages are essential for testing the effectiveness of the underlying design system. Pages also provide a place to articulate variations in templates, which is crucial for establishing robust and reliant design systems.
To sum up atomic design in a nutshell:
- Atoms are UI elements that can’t be broken down any further and serve as the elemental building blocks of an interface.
- Molecules are collections of atoms that form relatively simple UI components.
- Organisms are relatively complex components that form discrete sections of an interface.
- Templates place components within a layout and demonstrate the design’s underlying content structure.
- Pages apply real content to templates and articulate variations to demonstrate the final UI and test the resilience of the design system.
For more information, I highly encourage you to buy and read Atomic Design book written by Brad Frost He described it so well that I didn’t wanted to change anything he wrote. You can find more information in his book which !
How to apply Atomic Design to Sitecore JSS project?
When you create your JSS app by running jss create appname react command (or similar based on your UI library / framework choice), it will support only Templates and Pages from the previous list of 5 Atomic Design principles.
Pages are obviously Sitecore items that serve as pages or are rendered as pages when url is hit by browser.
Templates are obviously Sitecore templates that serve as blueprint for Sitecore items and hold information on default layout for pages. When you follow also Helix, you are placing these under Project level. We usually also have these in subitem called “Page templates” so we can quickly distinguish and see their purpose in oppose to Datasource, Rendering Parameters or other type of templates.
Pages and templates are outside of your FE project and you use Unicorn, TDS or Sitecore CLI to serialize them so you can use them in your deployment pipeline or exchange them with fellow developers.
With small modifications you can achieve support of all 5 principles of Atomic Design in your Sitecore JSS project.
Let’s start by looking at how Organisms, Templates and Pages are supported in JSS.
Organisms in Sitecore JSS
As per definition, organisms are relatively complex components that form discrete sections of an interface. Usually these are components / renderings in Sitecore that you are placing on pages into placeholders.
Due to how Sitecore JSS projects are structured, OOTB you have “components” folder under “src” folder. We had an agreement within the team that these components are organisms and therefore we were storing them there. It would take some effort to rename this folder to organisms as couple of scripts are using path src/components in JSS scripts.
Examples of Organisms:
Molecules in Sitecore JSS
From this point on, it has nothing to do with Sitecore JSS but it’s pure React or any other framework / library stuff. Of course if we don’t count that you need to use Sitecore Components if you want to have support of Experience Editor.
Molecules are not supported OOTB by Sitecore JSS. What we did then? Simple. Creating “molecules” folder under “src” and linked these molecules from organisms and components .
Examples of molecules:
Atoms in Sitecore JSS
We did practically the same what we have done for molecules also for atoms. So creating “atoms” folder under “src” and linking these tiniest building blocks in our molecules.
Examples of Atoms:
Rule of thumb
- Never ever link atoms from organisms
- Never ever link molecules or organisms from atoms
- Chain of linking components / code blocks is always atoms <- molecules <- organisms / components
Conclusion
From the names of atoms, molecules and organisms you can clearly see separation of concerns and also exact purpose of the code block.
We really wanted to have as much of reusability as possible. Of course this makes some atoms / molecules harder to use throughout the time. They start to have lot of props and conditions inside and it’s sometimes hard to link them. Golden rule here should be – when the reusability is causing trouble split the code into more atoms / molecules.
There are couple of design systems similar to Atomic Design. We have nowadays also lot of tools like Figma and so on.
All these can be applied with Sitecore JSS. Don’t be afraid! Think smart!