Building Beyond Today: Steps to Build a Sustainable Design System

Published in

partoo

11 min readMar 20, 2024

Over the past few months, I’ve faced some interesting challenges that have led me to create a design system.

At Partoo, we are working on several front-end projects. These include a web application tailored for our clients, an internal back-office tool designed to help our team members in their daily tasks, a chatbot and a mobile application. Convinced that it was necessary to establish a coherent visual identity across all our front-end applications, we decided to create a design system.

In this article, my aim is to share my firsthand experience in crafting a design system from scratch. I will discuss my explorations, insights, and strategies that contributed to building the design, ensuring its adoption, and facilitating ongoing enhancements.

So, what does the term “Design System” actually refer to ?

“ A design system is a centralized collection of guidelines and reusable components that ensure visual consistency and enhances user experience across multiple projects. It is a single point of contact that allow to the different stakeholders of a project to design, implement and make it evolve”

So if we have to summarize it. It is a set of deliverables, shared between different teams designers, developers and product owners, that will continually evolve within the life of Partoo.

Now that we know what a design system is, why is it so important to an organization ?

A design system is more than just a collection of assets. It’s a dynamic resource that evolves alongside our organization. It provides a single source of truth for designers, developers, and product owners that promotes collaboration and drives innovation.

Before diving into what we’ve included and how we’ve built it, let’s take a moment to analyze what we already have.

Understand why we need it : A Deep Dive

The first step was to analyze our current design system and its pain points. This deep dive helps us to see why having a polished and effective design system is so important for our organization.

“Code Duplication: The Silent Productivity Killer”

Upon my arrival, I discovered that a design system had already been created, but it was integrated directly within the repository itself. Most notable was the significant code duplication, especially present in the CSS styles. The font-size property was repeatedly reused instead of employing mixins or alternative methods to define various typography styles.

“Bridge to Confidence: Overcoming Doubt in the Design System”

Through discussions with the developers, I discovered that they had lost confidence in the design system. Rather than using components from the current design system, they preferred to rewrite some elements from scratch.

“The Pitfalls of Accessibility: Rethinking Component Governance”

The fact that these components were stored within the Partoo monolith made them excessively easy to access. Every team had the freedom to update them without coordinating with the design team or other developers, adding specific props for their intended purposes, rather than challenging the design and development teams to collaborate effectively.

As a consequence, the components quickly became too complicated, with too many props to manage.

Insights from Analysis : Architectural Reflection

The Design System is not just an evolution of brand guidelines. It has evolved to become an integral part of team workflows. Its core purpose is to enhance collaboration and productivity. Its main goal is to improve teamwork and productivity by making things easier.

Rather than asking:

What should we include?

we should start by asking

Who will use it and how?

So before starting to make things happen, it’s important to set clear goals. This ensures everyone involved in the project, including those focused on the brand, product, and Design System, look in the same direction. It’s normal for objectives to evolve over time, but transparent communication about these changes is key.

“A Standalone Module: Isolated from the Rest of our Stack”

The first decision was to extract the design system from the Partoo repository. We chose to put the design system in its own repository to keep it separate and ensure clearer governance rules. The Design team is now able to test easily changes made to the Design System. So this separation allows the design team to play a more active role in the development process, ensuring the quality and consistency of the design system at every stage. Additionally, we simplified component discovery by packaging them as dependencies and manage them using GitHub Packages Registry.

Herein lies the outcome of our architectural reflection.

Once the architecture was clear, it was necessary to think about what we would put inside.

Building the Foundation: What do we put inside ?

A robust Design System requires more elements of brand identity. The design team started a long process of thinking and worked hard to create mock-ups for all the elements of the new Design System.

With the help of designers we have structured our Design System into four distinct packages.

All the parts of the brand identity work together to make a consistent and memorable brand experience.

These parts help me establish a central theme for visual consistency in my components, including colors, typography, spacing, radius, and shadows.

The Partoo Color Palette is like the basic building blocks of our brand’s language, setting the foundation for clear and powerful visual communication.

@partoohub/ui is a complete set of important components, carefully made to improve how users interact with and navigate the site. From basic buttons to complex modal windows, our easy-to-use design parts help you make smooth and attractive interfaces, ensuring users have a great experience.

It is a flexible collection including icons, illustrations, and product icons. From basic symbols to detailed illustrations, this package gives you lots of visual elements to make your designs better.

These are advanced elements carefully made from our UI Components Library. These advanced components are very versatile, letting you easily create detailed interfaces that fit your needs. We can find for example Sidebar, Notifications System or other more functional components.

However, just having these elements isn’t enough to effectively communicate our brand identity. Just as words and sentences require grammar and structure, our identity elements need guidelines for consistency and coherence. These guidelines, along with dos and don’ts, act as the grammar and rules of our design system, guiding designers towards the “right combinations” that make our brand unique.

By documenting and guiding how these elements are used, we ensure that the brand stands out and stays consistent.

Together, these elements lay the groundwork for our design system, promoting consistency and innovation in all aspects of our product development.

Once we reached this stage and after implementing the various elements of the design system, the next step was to ensure everyone uses them. However, before anything else, we needed to choose how we would all collaborate together.

So, we asked ourselves several questions:

How many people will use this system?
How familiar are they with this topic?
How consistent do we want these products to be?

Communication : Establish a Governance Strategy

Design systems are dynamic, and they are always evolving. So, it’s crucial to have a clear process for approving these changes. This means creating a governance strategy that ensures your design system can adapt smoothly.

We decided to go with a Centralized model, where one team, the design guild oversees the system’s management. This team guides its changes, but we also accept input from other team members. To keep our designs consistent, only members of the Guild Design Team can approve changes.

Why do we do this ?

Well, it’s to ensure that everyone across the teams is speaking the same design language and using the system effectively.

The main goal of a design system is to simplify everyone’s work. That’s why it’s not just about creating one, but also ensuring that everyone uses it. It should smoothly fit into our teams’ way of working, becoming a useful tool for both designers and developers.

When it comes to sharing changes, we’ve found that being open is important. A design system isn’t static. It grows and changes as our organization does. So, it’s important to regularly tell everyone about updates. We do this by regularly releasing updates and providing a changelog that explains what’s different in each new version and how it affects our work. We used Conventional Commit to automate the standardization of our changelogs.

And we have a dedicated page to track our component progress. It’s like a detailed dashboard showing each component’s journey from idea to completion. We document every step carefully so everyone on the team can keep an eye on progress. This helps us make sure our design system grows consistently and works well.

Empowering Teams: Cultivating Design System Adoption

As a team member, one of the biggest hurdles I’ve faced is getting everyone to use our design system. We’ve done a lot of work to create, test, document, and update it, but getting everyone to adopt it is my ultimate goal.

In our journey to get everyone on board with our design system, we’ve found that taking a collaborative and gradual approach works best. We understand change can be scary, so instead of pushing it, we’re introducing our system gently.

We’re introducing new ideas and tools slowly, letting teams adjust and share their thoughts as we go. This method makes the switch smoother and gives teams a sense of ownership.

“Driving Adoption Through Learning Initiatives”

We organized several Tech Dojos and presentations to promote its adoption. These events were designed to provide team members with an interactive platform where they could learn and experiment with the design system.

Tech Dojos allowed teams to gain hands-on understanding of the system’s features and benefits while fostering a collaborative learning environment. Presentations also offered an opportunity to showcase recent successes and share best practices. This approach boosted team engagement and encouraged them to embrace the design system in their daily work.

But, this support can be further enhanced by implementing new tools that increase the adoption of the design system.

During the implementation of the design system, we made sure to gather feedback from our various users: designers, developers, and project managers.

Viewing the design system as a standalone product, we are dedicated to continuous improvement to ensure it best serves the needs of all users, thereby improving their overall experience.

It’s important to provide the right tools in place at the right time. We first tackled the accessibility of our documentation, ensuring that each member collaborating on the design system could access it.

“Storybook: Effective Change Communication”

To improve communication about changes and maintain a single source of truth, we set up a Components Showcase using Storybook. This tool centralizes the display of components, use cases and guidelines into one place. Even if contributions to this repository are open, a validation process involving designated designers and developers ensures the quality of changes. We host the static files of Storybook on Amazon S3, served through a CloudFront distribution.

“Figma : Creating Synergy with Design Team”

I’ve made sure to please everyone by adding Figma integration directly into Storybook. This lets us see Figma mockups right in Storybook. Similarly, Design team ensured integrating Storybook into their Figma. Don’t forget, this ensures perfect coordination with designers, including variable names, theme setup, or icon naming conventions for example.

“Chromatic: Visual Consistency Made Simple”

We quickly realized that it was difficult for designers to test components because it was not easy to detect changes, and regressions on third-party components emerged. We decided to add Chromatic to address these issues.

chromatic is a tool for visual regression testing and UI component review, helping developers and designers ensure consistent visual appearance across different states and environments of their web applications.

By adding ci action, we use Chromatic to show developers how their changes can affect specific components, making it easy for designers to approve or reject changes.

name: Chromatic
...
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      ...      
      - name: Publish to Chromatic
        uses: chromaui/action@v1
        id: chromatic
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: tools/storybook
          onlyChanged: true

“Yalc: Streamlining Local Package Management”

Another issue arose as the Design system began to be used. Devs wanted to be able to use the packages locally before to release it. So we started using Yalc.

yalc is a tool aiming to simplify working with local npm packages by providing a different workflow than npm/pnpm link, hence avoiding most of their issues with module resolving.

Below is a short tutoriel of how to setup and use it :

$ npm install --global yalc # Make sure to have the yalc binary

Here is an example for using @partoohub/ui as a local package:

$ # Go to you package you want to release
$ cd partoo-ui
$ pnpm build && cd packages/ui && yalc publish
$
$ # Now it's ready to install in your project
$ cd partoo/front
$ yalc add @partoohub/ui
$
$ # If you do some changes into your package
$ cd ../partoo-ui
$ pnpm build && yalc publish --push --sig 
$ # --push will automatically update the package on projects where it have been added, 
$ # --sig updates the signature hash to trigger webpack update

You can redo the same thing with all packages releases inside packages’s folder.

Conclusion

It hasn’t been easy. Building and maintaining our own design system has been quite the ride. But despite the challenges, it’s been totally worth it. We’ve moved almost 80% of our components from the old system, and both our design team and the entire organization are beginning to see the rewards. The application is much more responsive to changes in style and branding.

Looking ahead, we’re staying committed. Our aim is to keep improving and making our system even better for the long run. It’s an ongoing journey, but we’re confident we’ve made the right choice and excited about what’s to come and how we can keep pushing design boundaries within our company.

PS : If you are interested in joining Partoo or even better, eager to contribute to enhancing our design system, don’t hesitate to take a look at the available offers and apply 😀