Our journey from Rails to React, part 1: Atomic Design (ubiquitous language in the frontend)

I is doing Atomic Design

We’ve been using Ruby on Rails for our backend and frontend needs since our early days. However, Barkibu is growing and evolving quickly. Our pet health services are available in more and more countries and the dev team needs to deliver scalable solutions.

We’ve felt the need for a more modern approach so we are decoupling backend from frontend and migrating the latter to React (through Gatsby).

In a series of posts, we’ll explain how we are doing that and how we solved some challenges we found.

Designers and developers can be friends

One of the first departments that made our transition easier was, maybe surprisingly for you, design. For a couple of years, we had been applying Atomic Design, a design methodology and naming convention that, later, made it easy to move to a fully component-based library like React.

Let’s see some common frontend problems and how Atomic Design helps solve them:

The problem(s)

• Usually, developers and designers have difficulties communicating with each other. To build a website, we have 2 basic “worlds”: data and visuals. Data is the world of developers, visuals is the world of designers. They live in their respective worlds and name and organize their stuff to their liking. However, those 2 worlds are not fully separated, they mix like this:

Developers’ and designers’ worlds meet in HTML and CSS. We should search for a way for them to communicate well so that everybody knows why each line of code is like it is, and what effect will have if it is modified.

• Usually, developers have difficulties managing CSS cascade.
  The “C” in CSS stands for cascading: styles apply in a cascade to the DOM, following some specificity rules. If we just throw styles to our CSS, it is difficult to know which rules are going to win. So, a lot of people end up either forcing the cascade with “!important”, or not using it altogether (by never using child selectors).
• Bloat
  A poorly managed stylesheet can soon become huge and affect performance. This is especially true because of the (ab)use of Bootstrap and the tendency to override it instead of customizing it. In one of my previous jobs, I had to deal with a 35k+ lines CSS file for a simple shop site. 🤦
• Presentational classes harm code reuse
  Applying presentational classes to HTML (<button class=”text-big bg-red”>) makes it difficult to reuse HTML: we have to create several files to display the same data entity in different places, just because its looks change.

Atomic Design to the rescue

What is Atomic Design? It is a methodology proposed by Brad Frost. The core concept is that, when building a website, we must think from small to big: we first design the simplest parts (a paragraph, a title, a list) and then combine those components until we get a full page.

The names of those components follow a self-explanatory naming convention, inspired by chemistry. Simply by looking at the name of each component we can know its size:

• Atom: simple elements that don’t make sense on their own.
• Molecule: a group of atoms that make a coherent entity. [Note: usually, mapping 1:1 to a database entity]
• Organism: multiple atoms and molecules grouped in a higher context, that can live on their own. [Example: a list of database entity results]
• Template: re-usable patterns of organisms/molecules/atoms.
• Page: a group of organisms/molecules/atoms in a specific instance of a page.

NOTE: The names we choose are really not important. The important thing is that those names come from real-world categories that communicate their relationships: changes in an atom will affect molecules that include them, but not quarks.

If we join this naming convention with Domain-Driven Design, plus a couple of front end best practices, we can solve all the previous problems:

A unique name, from design to data:

Naming is agreed upon throughout the company. So, from a database entity to a CSS class, a pet is a “Pet” and an insurance quote is a “Quote”. Layouts (in Figma) include naming guides, so when a developer has to create the layout for a design, she can use the same name. Folders and files are also named accordingly.

Benefits: improved communication. Designers and developers can talk using the same terminology, and files are easier to locate.

Bye to Bootstrap:

Let’s face it, the only reason everyone uses Bootstrap is because of the grid system. However, with the current support of CSS Grid and Flexbox, which turn the management of grids into a game, there is no reason to keep using that framework, with all its included bloat.

Benefits: less bloat, more flexible grid.

Semantic HTML, to the extreme:

By removing Bootstrap, and managing the grid in our CSS, we can create purely semantic HTML. We can create the markup for data, not its styles. That allows for simpler code, easier to develop, reuse and maintain.

Example of a molecule:

<section class="ml-cart-summary">
  <header>
    <h2>Summary</h2>
  </header>
  <section class="cart-summary-names">
    <p data-js="summary-names"></p>
  </section>
  <section class="cart-summary-total-price">
    <h3 class="total-text">Total</h3>
    <p>
      <span class="currency"><span data-js="total-price">0,00</span> €</span>
      <span>/ año</span>
    </p>
  </section>
  <footer class="cart-summary-submit">
    <input name="health" type="hidden" data-js="health-uuid">
    <input name="gl" type="hidden" data-js="gl-uuid">
    <input type="submit" value="Continue" data-js="cart-submit" disabled="">
  </footer>
</section>

You can see the classes refer to data, not presentation. Someone can change the display of this into 2, 3 or 5 columns without altering the HTML.

Taming the CSS cascade:

The cascade is awesome, if we manage it properly:

• Keeping our specificity as low as possible
• Encapsulating components

Atoms are not namespaced, as they are global. The rest of the elements, (molecules, organisms, etc) encapsulate all their styles, like this:

//File: /molecule/_cart-summary.scss
.ml-cart-summary {
  display: grid;
  grid-template-rows: 1fr;
  grid-template-columns: 2fr 1fr;
  
  > * {
    padding-bottom: calc-rem(16);
  }
  .cart-summary-submit,
  .cart-summary-total-price {
    &,
    > * {
      margin-top: 0;
    }
  }
}

As you can see, this looks like a fake component framework, just with plain HTML and (S)CSS. Since the components are already divided, the transition to React has been easier. But that’s a topic we’ll explain in the next post!

In short

Atomic Design is a methodology that allows for better organization and internal communication. It can be the first step before diving into a component library.

It is a little weird at the start because it’s not easy to decide if something is an atom or a molecule… But the benefits outweigh the problems.

Do you like to help us with this or other challenges, while making pets healthier and happier? Come join us! We are hiring!