Building a Design system using atomic design methodology in Flutter

Daniel Herrera Sánchez
Bancolombia Tech
Published in
6 min readApr 29, 2022


In 2019 we faced a significant challenge because we had to solve the following questions; How can we structure the implementation of our front-end components to be reused in all digital experiences? How can we join development and design teams forces to make elements look the way we want?
We answered these questions. Here we will tell you about how our journey was

Design system, is it important?

When we began our analysis, the organization worked with different teams on the same digital elements. For example, a couple was developing a button, and at the same time, another team should also do the same button on their website; to top it off, the design team verified both elements. We couldn’t go on like this! So, the answer that we found was Design System.
But What is a design system?
It is a set of elements that can be reused in different combinations, allowing a standardized digital interface to be implemented.
Every single day people use design systems without even realizing it. For example, imagine that we are going to prepare a sandwich.

Although we use the same bread and some similar ingredients, we can make different appetizers using the same elements. However, the bread will still be even if used for other things.

Atomic Design

The solution to our problems was to use a design system to make your digital elements reusable and standard.
We decided to use the Atomic Design methodology to implement our design system. Brad Frost, its creator, explained that we must divide our digital experiences into the following elements:


Atoms are components that cannot be divided into smaller elements. An example is <button>, <input>, <h1>, or in Flutter the basic elements (like the IconButton).


Molecules are functional units of several atoms, but they do not have multiple responsibilities. For instance, an icon, a text, and a button inside a card are modal, and it is a molecule because it retains responsibility.


Organisms are elements composed of the union of several molecules and atoms. These can have different responsibilities and generate multiple events. An example would be the header, navbar, sliders, etc.


Templates define the order and configure the arrangement of elements.


They are different screens exposed to the end-user.


We still had a problem, how could we make the colors, shadows, animations, fonts, and iconographies used along with the whole project standard?

We decided to have all these elements in a layer that we call tokens. These are the basis of atoms.

The advantage is changing some color of mark, font, shadow, or animation; All elements are updated automatically with the new values.


No component should directly depend on tokens; remember that its definition should not be tied to any. Therefore, we establish a bridge between the token and the widget definition in the Foundation layer.

Delve into Flutter

Now that you know what atomic design is, it’s time to apply your new knowledge in Flutter. We first need to create a package with our design system.

You can use this command:

flutter create --template=package orgname_design_system

Tokens layer

Now you need to fill your tokens. Remember that the only team that can define your organization’s tokens is your design team. The developer only consolidates the token information.
You can define your colors, typography, spacings, shadows, and sizes in the Tokens layer. So let’s create a folder with this content:

Let’s see into colors.dart :

Tokens are definitions. In the Foundation layer, you can associate these definitions with tokens. That is very important because it is a common mistake to define the tokens by thinking about the component’s name. As you can see, the names are not related to any element’s name.

You can see the entire Tokens layer at this link.

Foundation layer

In the Foundation layer, we will associate the definitions with the components. In this case, it is customary to use the component’s name and associate the corresponding token.

Let’s go to foundation_colors.dart :

As can be seen, names like colorButtonSecondary, and bodyTextColor strongly correlate with the component.
In the Foundation layer, you can define an inner layer called Themes. In this layer, you can illustrate your themes using the definitions inside the Foundation Layer.

Now we can check theme.dart :

Check out this link if you want to see the entire Foundation layer.

Atoms layer

We are now ready to start implementing our atoms. Remember that you cannot use any Token. You must always use the Foundation layer. Also, remember that you can’t use hard-coded values. If you feel like you need another matter, that’s a sign you need another Foundation value.

Now that we can build our atoms, let’s look at an example:

For this article, we created three atoms for the example, but if you want to add items to our repository, you can (link to view atoms).

Molecules layer

You can add the component created by joining atoms on the molecule layer, but only if this molecule holds only one responsibility. You can use the layers Foundation and Atoms to build your component.
In the following code file, as you can see, the molecule only depends on the inner layers:

Organisms layer

We can find widgets created by joining molecules and atoms in the organisms’ layer. Then in this layer, you can use your Foundation, Atoms, and Molecules layers.

Templates layer

I forgot to tell you, but you need to define visual models correlated with the component in some situations. It’s not a bad practice. In the package Material Design, you are using in your projects a template widget it’s called Scaffold. Our proposal, in this case, it’s very similar. We need to define a template widget that is easy to use and uses the inner layers. The model must be located near the widget that needs this definition.
It’s is a template created for this example:

Pages layer

Finally, you can define your standard pages that don’t allow changes; they are used as defined by the design team. In many applications, there are repeated pages so that you can centralize them in this layer. For example, the page that notifies the user that their transaction was completed successfully:

The importance of having a good showcase

When you build a package, you need developers to fall in love with your solution. And in this case, they want to contribute to doing your project. So, it would help if you created a showcase with all your widgets. For this example, we build a small one:

If you want to check the source code it’s here.

In large companies like Bancolombia, we have a robust solution to show our developers the component and the code they need to implement the widget in an application. This showcase has its website:


I hope you have enjoyed this article. Atomic design is an excellent methodology for building our design systems. Using our design system, we have reduced our TTM by 80%, so I know it will benefit all of you to implement this strategy. If you want to see the complete sample project, visit this link. We would be pleased if you gave us 👏 here and stars ✪ on our GitHub project.



Daniel Herrera Sánchez
Bancolombia Tech

Flutter,Dart@GoogleDevExpert💙 • 🔴Youtube Channel Weincode •👨🏻‍💻FlutterMedellin Community Lead • 🙅🏻‍♂️Angular Content creator • Speaker •GitHub: weincoder