March 2018 · Guide · 12 min readBuilding Design Systems with Atomic Design

Component-Based Systems

Since the first computers, software engineers have been looking for ways of how to increase their speed of work, to make applications faster and decrease the number of errors.

This is where component-based development was born. It’s a methodology that’s based on components or modules: re-usable chunks of code that are intended for multiple uses. In other words, you don’t need to code the same thing twice. It also allows you to modify a module once and see it updated in every instance; have a more clear app architecture and, generally, have a unified development process.

Such an approach is not unique for development. There are two common approaches when designing a website.

Frameworks

Bootstrap, Materialize, Foundation, you name it. They all have tons of re-usable components within, from smallest buttons and checkboxes to panels and accordions. Usually, developers are happy to use them, because it saves tons of time and effort. Instead of coding another-dropdown-menu, you can just take tested and ready-to-use component and put it on a website. However, this can have plenty of disadvantages.

Bootstrap and Materialize

1. Not for designers. There are a lot of frameworks allowing developers to quickly assemble a website. But how many of them have relevant .sketch, .psd or other source files allowing a designer to use frameworks components within their graphics editor? Front-end frameworks are not made for designers (hence the name).

2. Limited customization. Frameworks are allowing some level of customization. At the same time, if you need to build a product for a brand with a distinctive level of identity, a simple change of a button color may not be enough. Deep customization requires a large amount of additional development effort and it essentially negates the very essence of using a framework.

3. They are slow. Frameworks have many elements for you to use. But for every element there will be 5 that you don’t need. This means that there’s a great deal of unused code negatively affecting the overall performance.

These points may not be relevant on some projects, but when you’re trying to build a somewhat unique experience (in terms of visual design and functionality), using a framework may not be the best solution for you.

Style Guides

Style guides is the common approach to have a small component-based design system in a project. All of your projects, most likely, have some sort of a style guide. You build it from scratch and can quickly use components from it in your mock-ups. But a typical style guide also has its flaws.

Style guides are a great starting point for your design system. Desk Metrics style guide by Mateusz Dembek

1. It is difficult to trace the inheritance of components. It is not unusual for a large-scale project to have more than one style/size of a button, input field or some other component. And when a developer is reviewing your mock-up, they will have a hard time figuring out which exact button they should use. This is also relevant for design teams.

2. Many of the components are not documented in a typical style guide. Usually, it only contains some number of text styles, icons, buttons, dropdowns, etc. Small stuff. Without proper documentation for your designs, mockups often get implemented not in the intended way.

3. Poor documentation can also drastically decrease re-usability of your design components. If you have more than a dozen of pages in your project, it becomes a problem. You don’t always expect another designer or developer on your team to go through all screens in a project and see whether a popup “like this” has already been made before. A designer makes a new popup. A developer codes a new pop-up. Next thing you know, your product has 10 different popup styles for a simple yes/no question.

What is Atomic Design

What if you could use only the better parts of both front-end frameworks and style guides? One of the solutions has been proposed by Brad Frost, a web designer from Pittsburgh, USA. It’s called Atomic Design.

Atomic design is a methodology that allows (and requires) you to describe and organize every component of your design system.

This approach divides design components into 5 different categories.

1. Atoms

These are the smallest building blocks of your project. Individual legos. Text styles, buttons, icons, input fields, checkboxes, etc. All these elements cannot be divided into smaller parts without losing any use (for instance, why would you need a button with no label or icon?)

2. Molecules

Those are more complex entities consisting of several atoms. Things like notification toasts, data values (label: value), input fields with buttons, etc. Sometimes, molecules are already functional elements that could be put anywhere on the page and work on their own. Usually, though, they need to be a part of an organism, to truly have a value.

There are no very strict guidelines on atom/molecule level on how to divide your elements. What is more important is to make it clear for designers and developers how you divide elements in your system.

3. Organisms

Truly functional parts of a page, made from groups of atoms and molecules. Many organisms function on their own, without relying on other elements on the page. They are usually huge components, like navigation, sidebars, forms, popups with lots of data, etc.

Organisms can become quite sophisticated and have smaller organisms inside, just like in real life.

A cat organism with a mouse organism inside. Photo by Timothy Meinberg

4. Templates

Essentially, those are pages without real content. They combine organisms into a proper website layout.

5. Pages

Once you have a template, you can create pages from it by adding content. Let’s take, for example, a Wikipedia article. If you put it simply, a template of an article will consist of organisms like menu sidebar, header, footer and article body. Every real-content Wikipedia article will be a page that’s using the same template.

High-level organisms on a Wikipedia article page

How does the atomic design approach works in an actual workflow? Brad Frost and a team of developers created a tool called Pattern Lab. It allows you to generate a static website for documenting your atomic library. You can keep all your pre-coded elements there, as well as component descriptions. It’s a developer-focused solution.

Let’s talk about how to start using the atomic from a designer’s point of view.

Atomic in a Workflow

When our team decided to try the atomic approach on a new project, there was no practical guides available around the web. So I sat down with developers and during several meetings brainstormed the solutions on how to effectively adopt the methodology. This is the result of that discussions.

If you are a web/ui designer, in your day-to-day work you probably use tools like Sketch or (still?) Photoshop to produce your designs. You also use InVision/Zeplin/Avocode to pass your designs to a dev team, where they are able to review layers and measurements within your mockups. In addition, you have a style guide, where some of your design elements are described.

In this article, I’ll be using this combo to describe the atomic workflow.

Atomic workflow with familiar tools

Style Guide

First of all, you should prepare in advance that your style guide will be really big. After all, every gear in your mechanism will be documented.

Use a separate style guide prototype project in your InVision environment: a) lots of style guide pages won’t create a mess in your main project; b) you are building a design system that can be potentially scaled on multiple projects, so it should be accessible by various teams in your company.

Add a title page, where you will be listing all types of your atoms, molecules, and organisms. Every element type will have a separate page, so make this table of contents interactive.

Start the usual workflow, by adding essential building blocks for your project. Font styles, colors, icons, buttons, dropdowns, input fields, etc. All these things that you need to have before creating the first page of your new project.

Basic style guide. You may notice that atom links also hint the actual naming of elements within

An important addition to your style guide will be a change log. For a version number, use an update date. Once you’ve added or edited an element within your design system, make a note in your change log with a date, your name and description of changes. It will allow other people on your team to quickly spot the updated elements. Developers will definitely thank you for that.

Naming Convention

Now let’s talk about naming convention. For a better communication within design and developer teams, it should be consistent and clear.

Written in lowercase words separated by hyphens. Easy to use for a designer. Easy to use for a developer in a source code and for file naming. Such special naming also allows to quickly spot a “documented” layer or group in your mock-up. You will still have layers like bg, divider, etc.

The first letter stands for an item category: atom, molecule, organism. The second word is an element type. The rest is used to describe variations of an element.

Every atom-, molecule- and organism-layer or group within your design mockups should be named accordingly.

To make this process easy and stress-free I recommend Sketch plugin Rename It. Use hotkeys and it will make batch renaming of layers much faster.

Naming convention can have a huge part in the success of a design system. Let’s say a developer reviews a mockup and sees an organism called o-popup-alert-exit. They proceed to a project source code folder, easily find a file o-popup-alert-exit.html and quickly add it to a needed place in a project.

Here are some more naming tips:

• Make names distinctive and clear, avoid using indexes. I.e. a-dropdown-main, a-dropdown-secondary instead of a-dropdown-1, a-dropdown-2. Names that make sense are a key to avoiding confusion and mistakes.

• Focus on the element’s role in the system, but not its form. Don’t name your primary action button a-button-blue, just because it’s blue. It’s a primary button in your system, so name it a-button-primary. Then, if a color of a primary button suddenly changes, you won’t need to rename every instance of a button in your mockups. And just by looking at the element’s name, you can get a feel of what role it plays in a system.

• While naming, try to focus on the element’s role in the system, but not its form.

Sketch Libraries

Libraries are a great part of the Sketch functionality. This feature allows you to connect a usual .sketch file within app preferences and use that file’s symbols in all of your design mockups. Use your style guide file as a Library. You can read more about how to use Libraries in Sketch Documentation.

Side note: be sure to organize your artboards within Symbols page. When your style guide grows, it can really become an unusable mess. You don’t need to do it manually, just use a plug-in like Symbol and Artboard Organizer. If you named your layers properly, it will do magic just with one click.

Design Mock-ups

You’ve created a basic style guide, now it’s time to start building pages. Organize your workflow in the following way:

1. Create a mockup of a page. Some of the elements on the page will probably be from your style guide, but some are brand new. That’s ok. Structure your layers in appropriate groups, as you normally do.

2. Iterate. Once your page is assembled, it usually goes through a few iterations and discussions with your client, before it’s ready for development. So it doesn’t make sense to make documentation just yet.

3. Atomize it. Your design is approved, so it’s time to atomize it. Make sure that your layers/groups are structured and named in accordance with the atomic approach. Add new elements to your style guide.

Here’s an example of a table organism documentation. Under a table organism name, you can see a list sub-elements from which the organism is made. They all are clickable, so it’s very easy to navigate through this organism’s structure and read about all its building blocks.

4. Handoff. Finally, your page is ready for development. Every element is documented; this means fewer questions from a dev team and more productive workflow.

In a perfect case, developer’s code will look just like your layer structure:

Developers can use InVision Inspect to review a mock-up structure

What Atomic Can Solve

There are a lot of noticeable advantages of the atomic methodology. I would like to point out some of the main improvements that we have achieved within our team’s projects by using the atomic approach.

Decreased time and effort for design and development

When every element in the design system is documented, it substantially decreases the amount of re-work. You don’t need to reinvent the wheel, when you can see all of the wheels in your project at a glance. In addition, once your component library is big enough, you can very quickly assemble and implement new pages. Therefore, you have extra resources for doing more valuable things.

Better communication and implementation

Success of any project vastly depends on good cooperation between designers and developers. With the approach described in this article, a team will have a shared language of communication. Having a naming convention and a detailed style guide plays a huge part in this. Any member of the team has a complete documentation of design mock-ups at their fingertips. This means less misunderstandings and much better implementation of designs.

Designer discipline

Huge and dispersed design teams with various backgrounds rarely have an aligned vision of how to structure mock-up layers and files. Moreover, while working on large-scale projects, it’s easy to forget to describe different states and edge cases for various components. This negatively affects cooperation process within design and development teams.

The atomic methodology with an addition of the practical usage guidelines requires: a) documentation of every new component in the mock-ups; b) structuring layers in the unified way. This naturally helps to resolve the above issues.

Conclusion

At the start, the atomic design approach will require plenty of extra effort to implement. But in the long run, it will all pay off. You don’t just create a bunch of buttons and pages. You create a system. A system that is fully documented and can be scaled for dozens of your client’s projects.