A modern UI component library with Storybook
The User eXperience (UX) has always been a core differentiator of Akeneo and its products since the very beginning.
Today, our team is proud to unveil its next improvement in the area by communicating about the development of Akeneo’s very own Design System.
A simple way to describe a design system is to look at it as a collection of UI components and UI patterns that define the ground rules for conceiving a consistent, productive, and harmonious user experience (UX).
In this article, we want to lay out the path we’ve been through and summarize the advantages of having a design system for software products, engineering teams, and UX designer teams.
One recurring problem across multiple technological changes
Over the last 5 to 10 years, the front-end ecosystem has been known for its competitive environment regarding framework libraries: the Ember VS Angular VS React match is one example and we, software engineers, have been trying to do our best to choose and use the best libraries for our software.
Akeneo is no exception to this story and before talking about the design system, we need to take a little stroll into our history to understand where we come from and why the unveiling of a design system is a game-changer for our software teams working on different products.
Let’s start by making a chronological list of the techniques we used to develop front-end components:
- Starting in 2013, coming from a back-end-oriented know-how, we used html templates and jQuery library combined with css files with styles scattered across all parts of our software to build our UI.
- Then, we used backbone.js and less files following the BEM methodology. With BEM we were able to reuse components styling across the application pages which was a huge win. At this point, we needed to be extra rigorous and closely collaborate with the UX team to produce mockups that were consistent with what implemented BEM modules would allow. Sometimes, we had to accept trade-offs and make exceptions in the styling of some components which would make the software more complex and harder to maintain.
- In 2019, we found a way to mitigate this issue once we moved to React and styled components. With styled components, we were able to encapsulate the styling of each component directly in a single file. When using that component, we could directly use its associated styling as it was already embedded!
- Soon enough, we found ourselves re-implementing the same UI components in different parts of our software. We decided to start gathering them in a shared space to ease the component reuse process. This shared space acted as a collection of components. The only drawback became, once again, the exceptions we had to make when mockups became inconsistent with the components implemented in the shared space.
- There we were, at the starting line, with modern technology but in the end the same problem:
There is an increasing gap between the UX world and the technical realities that’s too hard to close for engineering teams.
Thankfully, our salvation came from our beloved Product design team who told us about something we had never heard about, something called a Design System.
UX team initiative, the design system project is born!
The idea was for the designers to decompose all the UI/UX elements of our products into components and patterns. This collection would act as the single source of truth for the UX of all our products at Akeneo.
As UI screens would only be composed of components defined in the design system, building them would become as easy as attaching legos to one another, at least that’s the promise 😊 .
At the end of this study, a thorough description of each component styling through their dedicated abstract pages, the different UX rules, and different styles for each states of the components was centralized in a single notion page.
This was all the more important since all Akeneo products have the same visual identity and therefore rely on the same components library.
Our front-end engineers became very quickly excited with the design system initiative. Once this whole work was done, the next step for this project was to find a way to bring to life a front-end library of react components that feature teams would be able to reuse effortlessly in their work and maintain in the long run.
You might hear from the Panda’s team thinking process in a dedicated article in the future on our Akeneo Labs blog 😉
Technical team on deck!
When we talk about a transversal project that will possibly impact the way 8 teams working on 3 different products build software, communication is not only key, it is essential.
To our team working on the front-end library, it was clear from the start that we had to lay out a plan for the project to be:
- Understood by everyone: Why do we create a design system now? what problem does it solve?
- Easy to contribute for technical teams: any engineer should feel comfortable adding new react components and the Developper eXperience (DX) should be as smooth as possible for them.
- Easy to use: the design system should accelerate teams development process!
In order to reach those goals, we went through 4 different phases that we are going to talk about in the next sections.
- Learn: Talk to the UX team! Get to know more about the design system and the tools available in the industry and try them out!
- Build: Lay out the ground work to build the Design System, run the tests in the components, build and publish the generated documentation.
- Structure: Together with the UX team, define a detailed process for teams and UX designers to add new components.
- Empower: Find ways to evangelize about the design system initiative! Have people understand how to use the design system, how to contribute to it, and embrace it.
Learn
The first step for the UX team was to give the technical team a crash course on what a design system actually is. Once that was off the list, we started to explore on our own.
Our squad started to dedicate 1 hour every week to explore tools, read articles and find out what existed in the industry.
We looked at how some other design systems were built:
- IBM’s carbon: carbondesignsystem.com
- Shopify’s Polaris: polaris.shopify.com
- Salesforce’s lightning design system: lightningdesignsystem.com
We also stumbled upon a video series on “Storybook” you can find here:
Watching these introduction videos quickly gave us a sense of what tools existed in the industry (like Storybook), and how it would help us in our quest to build a design system.
Storybook describes itself as “an open source tool for building UI components and pages in isolation”
One of the greatest feature of storybook is to showcase your components by generating a comprehensive and dynamic documentation for each of them.
You can show:
- Static information like component’s usage information and some guidance.
- Dynamic playground that let people actually use and play with the components properties and showing how it changes the component display on-the-fly!
You can have a look at the “button” component and try to play with each properties (disabled status, size) and see the changes happen directly in the playground.
Using Storybook as the library of components felt quickly like a no-brainer for the team and we decided to move onto the next step!
Build the technical platform
The first mission for our team was to have our continuous integration platform build the components, run all the tests, and publish the components as an external dependency that would be published on NPM.
Therefore, the next step for us was to have a first very simple but working example of a component living in the storybook used in our software.
Once we had this working, we explored how we would like to test all the components. What kind of tests were relevant to execute and fin a way to publish the components.
During this time, we decided to work exclusively in remote mob programming so that nobody was left behind since this topic was new to every members of the team. This strategy has proven to be useful and also helped team mates improve on their front-end skills.
Structure
Once the storybook platform was available to all and used in our software (even though it was quite empty at the time), the next step was for the team and the UX team to define a process to contribute to the Storybook.
From a technical point of view, one important part of this process is for the technical team to review each component mockups with a UX designer. Giving the opportunity to each members to ask questions, point out potential issues, iterate on the components so they become future-proof technically and UX wise.
Since the goal is to have many teams contributing to the storybook, we also had to make sure not two teams were working on the same component simultaneously by communicating regularly on this topic in the front-end guild meetings.
Empower
As said earlier, communication was essential for this project to succeed.
At each step of this project we reached out to developers as much as possible by leveraging our front-end guild to gather feedback and incorporate different perspectives in what would be a homogeneous way to implement React components in the storybook. It helped us agree early-on on conventions and ground rules and later make sure every engineer was onboard.
First, we put in place a 1 hour weekly meeting with the UX team to talk about the progress and the first few components we would implement in the storybook. We also agreed on a communication plan to make the design system adoption a success.
We also organized department-wide presentations and trainings:
- Introduction of the Design System & storybook to all engineers during our biweekly tech review
- Create an internal workshop “Akeneo design system in practice” in which each engineer would go through the process of contributing a front-end component in the storybook in a mob programming environment
- Train each team one after the other and spread the knowledge!
Conclusion
In total, this project has taken around 8 months to complete. As of today, every engineering team is trained on the design system and components contribution keep coming in!
We’ve managed to add ~70% of Akeneo components of the Design system in the storybook, we’ve also added colors, iconography and illustration.
What we’ve seen is that when teams work on a new feature or on a new screen, they immediately think about adding their new design system components to the storybook (for everyone to enjoy in the future).
The implementation of the design system has been up to our expectations:
- UX designers and technical teams don’t have to discuss mockups as much since they are conceived with the design system in mind.
- Engineers can develop the screens effortlessly by building the UI with components that are already available in the front-end library!
- It becomes easy to maintain a homogeneous UX across all the screens of all our products since they are built with a central unique collection of UI components.
More importantly, the design system enables to lay out a path to modernizing our products’ UI in the future. Our challenge is now to organize our teams to use the design system everywhere possible in our products to ensure a consistent, best-in-class, User eXperience for our customers.
Thanks everybody involved in the review of this article Camille Bourjade, Steven Vaidie, Adrien Wiesbron.
You can also have a last look at our design system: https://dsm.akeneo.com
