Introducing UB Atoms theme structure

April 15, 2021 Update: UB Atoms v1.0.0 stable released!

Last week we introduced a sneak peek of the upcoming Magento 2 theme at Ubertheme -- UB Atoms. We promised you a brand new theme that will be fully revamped, unlike any other Magento 2 themes that Ubertheme has offered. Today, we are happy to introduce you to the structure of the UB Atoms theme that we’re working on.


When building the UB Atoms, we have been finding a uniform approach that makes the theme development and maintenance easier. The ultimate goal is to create a brand new M2 theme with good performance and extensive customization possibilities.

With that in mind, our team has thought about what we should change and how we should build a new M2 theme from scratch.

There are a number of points that UB Atoms will typically abide by:

  • Creating modular designs inspired by Atomic Design
  • Following the standard fallback mechanism proposed by Magento 2
  • Taking advantage of the Magento UI library to enrich the UB Atoms
  • Parent & child theme hierarchy where the child theme inherits the parent theme’s resources and extends the parent theme to meet your specific customization requirements.

Now that you understand the context of the UB Atoms theme, let’s take a closer at the theme’s structure.

The UB Atoms theme structure

The UB Atoms is a collection of files that define the presentation layer. You can also create one or more child themes on a parent theme.

The following diagram illustrates the current UB Atoms theme hierarchy:

Magento 2 theme - UB Atoms theme structure


This section refers to the base elements from the Magento UI library that the UB Atoms theme inherits.

The Magento UI library -- one of the most important Magento 2 resources for theme development -- is located in the directory /lib/web/css/source/lib. The Magento UI library provides the following elements and properties:

  • Actions-toolbar
  • Breadcrumbs
  • Buttons
  • Dropdown
  • Forms
  • Icons
  • Layout
  • Loaders
  • Messages
  • Pagination
  • Popups
  • Ratings
  • Sections
  • Tables
  • Tooltips
  • Typography
  • Global variables

You can take a closer look at the UI library which is available in the Magento 2 official repo (


This refers to the (UB Atoms) parent theme’s directory structure. The main idea behind the pattern is to organize the declaration of a standard Magento 2 theme that directly inherits the Magento UI Lib (the UB Atoms does not inherit the Luma/Blank theme).

As can be seen, the basic building blocks for pages are organized in accordance with the Atomic Design principle:



The elements of the Magento UI library are inserted into the UB Atoms theme using an import command, as illustrated in red in the diagram above:

@import ‘source/lib/_lib.less’;

Besides, the UB Atoms also takes advantage of overriding the Magento UI library, rather than extending it further. The overriding examples are highlighted in green in the diagram above.

Throughout the UB Atoms, we make use of mixins supported in the Magento UI Library to take advantage of reusable code through declared classes on the LESS preprocessor. For example, a LESS file performs a mixin (similar to a call function) so that an element of the Magento UI library can be used in the UB Atoms theme. In addition to using mixins with default variables values, UB Atoms also defines custom advanced mixins to enrich the theme (For example, we created the Grid for the Flexbox layout in the UB Atoms. We will share more details in a separate article about this case study).


This refers to the child theme that you define. A child theme will inherit all resources ( configuration, templates, layouts, static files, etc) from UB Atoms’s parent theme. You can use a child theme as a basis for customizations without modifying the parent UB Atoms theme’s files directly.


Now you know the UB Atoms theme hierarchy. Hopefully, with this overview, you’ve got a pretty good sense of the upcoming UB Atoms theme.

We’ll look forward to your feedback! Do not hesitate to contact us on email info (at)

Written By