Welcome Tech
Published in

Welcome Tech

How we implemented our open-source design system

In this article we are going to tell you the story of how we ended up creating our own design system at Welcome to the Jungle (WTTJ). It’s quite an interesting journey that began in 2019, at a time when we were about to create a new product called Welcome Home, a people and company map. Up until then, the company only had two products — our main website welcometothejungle.com, where job offers are displayed and candidates can apply, and Welcome Kit, our applicant tracking system (ATS) for recruiters. We were already sharing design components between the two projects but we were light years away from a design system at this point. And with the new product coming and the front-end team growing, we knew that it was the right time to mutualize our code, which would help us speed up development and provide the same user experience across all our products. Want to know how we did it? Buckle up and keep reading to discover the technical choices we made while creating our open-source design system Welcome UI (WUI)!

First things first: 3 months of focus

It’s important to emphasize that the WUI project could not have started if we had not made the decision to devote 3 months to it, away from any other projects we were working on. We were 3 front-end developers back then, and with the full support of our CTO, we spent 100% of our time on this project during this period because we knew that it was an important investment for the future.

Fortunately for us we had some help and we didn’t have to start our design system from scratch! Some people on the tech team had already made a proof of concept (POC) of a design system called Jungle UI using Storybook, basing it on Atomic Design Methodology. In addition, it turned out that Greg Bergé, the owner of the agency working with us on the Welcome Home product, had strong knowledge about design systems, being the creator of Smooth UI. He was a great help and inspiration for us!

From those solid foundations we started to iterate, to build piece by piece what would become WUI. Every time the agency asked us for designs for the Welcome Home product, we would add them to our newly homemade design system. It started with small, low-level components, such as Buttons, Links, and Inputs, moving on to larger components later. The product design team was of course involved from the beginning. We needed to make sure that we rationalized the way we were working together as much as possible, especially as they had a design system of their own.

But enough of the chitchat: let’s focus now on the technical choices we made along the way.

Version 1: Let’s go!

The very first technical choice that we made on the project during those 3 months of focus was to keep working with technologies that we were already using and were comfortable with. We wanted to be as efficient as possible, and utilizing the usual React and styled components libraries seemed the best option. We only added one new library to our tool kit — xstyled, a booster library for styled components — because it made the writing of styled components with themes easier and because Bergé, also the creator of this library, was available to help us with potential bugs.

Using this strong technical stack, we were able to get color directly from the theme, without calling `theme.colors.dark.900`, thanks to a simple Hint component.

And here is the associated theme:

Another important decision we made while working on version 1 was that we were not going to create a fully customizable design system. We wanted WUI to be able to answer our needs first! A lot of fully customizable design systems are already available for front-end developers, such as Chakra UI, Radix, and MUI, so we chose to be a bit self-centered for the sake of efficiency. We wanted to keep things simple and didn’t want to get sidetracked. Through the core theme, users will only be able to change basic colors, padding, and borders on components, for instance. If they want to go further with customization, they will still be able to overload CSS properties like `text-transform` directly on the components theme file.

So we started creating our core theme with our branding colors. From the outset we planned on giving it fully customizable entries (compatible with Styled System) to set the stage for 2 new themes corresponding to the 2 different styles we had at the time. One was based on the welcometothejungle.com website and Welcome Kit theme, and the other was based on the new Welcome Home product theme. Then the core theme was modified to have basic colors so that it would be more usable for people as it was not branded with our company’s colors and designs.

At the same time we moved from atomic components to packages. And as before we wanted to keep things as simple as possible, so we chose to create a unique package for WUI to ease the build and the process in general. But as you will see, this decision was reviewed when we worked on version 2 of our design system. Regarding components, we again went for the simplest. We wanted to work with components that managed accessibility aspects as none of the team were au fait with this, which meant it was out of the question to create components from scratch. And that’s how we found the amazing Reakit library, which provides tiny, fully customizable, and accessible components.

Then we thought about how we wanted to organize folders and files, and we ended up creating 3 main files:

  • Core: This is our main package and you need to have it to be able to install WUI. It allows you to get all the themes from the components (each component has a theme), which come with the theme provider from styled components.
  • System: This contains all the functions of Styled System.
  • Theme: It’s based on the Styled System and includes the core theme and the welcome theme

We also added a packages folder and utils for cross utilities.

Finally, we had to decide how we wanted to handle documentation. Regarding this, the only certainty we had was that we wanted our documentation website to display our company’s identity, so it needed to be customizable enough. We opted for Docz, a library that simplifies the writing of documentation for your code, based on MDX files.

At the end of the 3 months we had a small but functional design system. A lot of work still needed to be done, but we were able to build strong foundations in a short time-frame thanks to this focus period. We worked hard with the design team to get the best color scheme and names, and created some recomposable components that had been inspired by Atomic Design Methodology.

From this point we kept iterating on the library while dealing with our usual work.

Version 2: Hello, rebranding!

After a few months of new components and improvements on WUI, our progress was suddenly interrupted. The decision had been made to do a complete company-wide rebranding: new colors, new fonts, and new styles (new buttons, no border radius, etc.). We had a few weeks to integrate these design changes in our websites and products, and obviously this had knock-on effects for our design system!

Numerous changes needed to be made on WUI: new color entries, new button variants, a secondary font, among other things. This resulted in such important modifications of our design system that we decided to create version 2 of WUI. We ended up with just one theme for all of our products, called the welcome theme, and one theme for external users, called the core theme. Luckily the design system was not open source by that stage, and it was easier to manage those modifications as it was only impacting on the WTTJ team and not an entire community.

We also took advantage of the rebranding to upgrade Docz to the latest version, which was version 2, to keep our dependencies up to date. But this update presented some difficulties because it involved a breaking change of its own. We nevertheless took the necessary time to handle this update as we really needed the additional customization and the Gatsby implementation.

Then, because we had already been making several important changes with this second version of WUI, we decided to deep-dive with improving our design system by making structural changes. Through this we noted that not all our packages were being used on each project. So we decided to split the unique package we had into one package per component to allow the user to use only the packages they wanted and avoid them having to import all the libraries with tree-shaking.

This meant that

import { Button } from ‘@welcome-ui’


import { Button } from ‘@welcome-ui/button’

To help us manage this split, we chose to use Lerna, a tool for managing JavaScript projects with multiple packages, as well as Rollup, a module bundler for JavaScript that compiles small pieces of code into something larger and more complex, such as a library or application.

But how could we code locally now that we had multiple packages on only one project? We had a lot of dependencies between all our packages and we still needed to build each package that was modified. To address this complexity, we created a script to monitor the modifications of our components. Once a component was updated, the script launched a fast refresh of code in every component where the component is used.

We also started to add some testing with React’s Test Renderer to check if our components had been built bug-free, and we implemented more complicated tests for more complex code components like DateTimePicker or Select-Search, as in the past we have accidentally broken them in production.

Then, when the alpha version was stable, we were finally able to make WUI open source. This was definitely a big step for us! Open source had been a goal from the beginning as we wanted to contribute to the front-end community. We also knew that opening up our design system to more users would help us get more bug reports and improve the quality. Additionally, we were very proud to be able to showcase our work as WTTJ developers and help attract the best talent out there!

After this storm of changes we were ready to keep adding more beautiful components.

Version 3: Time to upgrade the core libraries!

It was now time to upgrade our main libraries, which now included React, xstyled, Reakit, and Downshift, among others. But nothing ever happens as expected, of course, and we encountered an issue when upgrading to version 2 of xstyled, which included theme file changes and props changes. As a result, we ended up having to rewrite some of the component properties and themes in version 3 of WUI.

We were also no longer happy with Docz and Gatsby: the build and load time took ages and we’d been having some issues with our components’ compatibility. It was time to test something else! So we took advantage of one of our Jungle Labs sessions (once a month we have the chance to explore technologies and projects we are interested in) to try to create some documentation using another technology, Next.js. After some research, we found a way to use Next.js with MDX files, which was what we needed to avoid rewriting everything. After that, there was no turning back on documentation: The build with Next.js was very fast and fully customizable.

While working on version 3, some new developers joined the team. We decided to take full advantage of these new hirings and asked them for feedback about our design system. Looking with fresh eyes, they were able to note issues and misunderstandings that we couldn’t see anymore. It was also a good onboarding experience for them as they were able to quickly get their hands dirty by fixing issues and working on new features. At the same time, we started coding a new product called Welcome Originals, a content streaming app to help people develop themselves at work.

Version 4: TypeScript, here we come!

For version 4, we took the big decision to migrate our design system to TypeScript (TS). This was motivated by different reasons. Firstly, we were getting more and more requests on GitHub from the community to be able to use WUI with TS for their projects. Secondly, we wanted WTTJ developers to start new projects with TS to get types on our files, work more efficiently on editors, and spot errors more speedily. And finally, as we were about to manage TS compatibility, we needed to integrate TS in WUI for future WTTJ projects.

Our older folder structure:

  • index.js: where our components were
  • index.test.js: a test file containing React’s Test Renderer
  • styles.js: styles for the components (import entries from the theme)
  • theme.js: a theme file for the core package
  • rollup.config.js

Which became:

  • index.tsx: where our TS components are
  • index.test.tsx: a TS test file
  • styles.ts: TS styles
  • theme.ts: we moved the theme to the core package to get correct typing on the global theme
  • rollup.config.js
  • tsconfig.json: TS configuration for the components

As we also needed to work on bug fixes and improvements, we decided to create a version 4 branch and created pull requests on this new branch on GitHub to keep two versions running in parallel. We needed some time to rebase version 4 from the branch master, which turned out to be quite complicated because of conflicts and rework components that had already been typescripted.

We started to migrate the themes and core files that are the base of our design system. We followed this up with small components like Button, Hint, and Label, which are used on more complex components like Input, Search, and Modal. Respecting this order was key to avoiding errors because the smaller components that are used on bigger components need to be typed beforehand. We also removed the PropTypes from components as they are replaced by TS. And each time we migrated components, we carried out a pre-release to test them on our WTTJ projects.

During this migration we fixed a lot of small bugs thanks to types. We also took advantage of this version release to upgrade xstyled to version 3 and improve components like text on mobile, add missing icons, and change some colors. We also produced a marketing homepage to explain what WUI is and encourage people to use it, as well as give a better understanding of the documentation component page. But we kept version 3 of the website available to help people who haven’t migrated yet.

It took 6 months to migrate to TS because the majority of the team wasn’t familiar with it and also because we didn’t have a specific schedule for the migration, we had to find time slots to work on it. But we finally completed it and version 4 was recently released. So now we have a version 3 branch (in case of a security update) and a master branch on TS.

What’s next?

So we have now shared our journey from the very start of WUI to the release of version 4 with the TypeScript migration. Looking back at what we’ve achieved, we can definitely say that building a design system was a good experience for everyone in the WTTJ front-end team. Despite the difficulties, we forged on and can now see the benefits of our work. New developers in the team are happy to use it and contribute, we are able to provide a similar design experience across all our products, and most importantly, our new projects develop much faster than before.

But how can we make WUI even better in the next version? What are the next steps? First, we would like to improve our documentation by adding more examples of forms, as well as more information about our theme. We also plan to rework the components based on old big libraries like DatePicker or Downshift (Select) so that they’re smaller, homemade, bug-free, and more maintainable. And finally we want to try to add some visual testing so that things are more stable with new releases, and — the icing on the cake — provide a dark theme for users.

All that being said, we also need to work on building a strong community around WUI and this article is definitely a big step in communicating and sharing information about our design system with the world. We hope you enjoyed reading it — and if you like WUI, don’t hesitate to contribute as much as you can on GitHub and spread the WUI love!

Written by Théo Mesnil, Front-end developer @ WTTJ

Edited by Anne-Laure Civeyrac

Illustration by Clara Dupré

Join our team!




This is the Welcome to the Jungle tech blog, where you’ll find articles about the machinery behind our Elixir/React applications and how we come up with our most creative designs, details of the latest releases of our open-source libraries, and much more!

Recommended from Medium

Top 3 Immediate Benefits Of Using Flutter For Your Startup

2 screens with blurred-out programming code

One-Stop Xcode Coziness

Van Build Subfloor Installation | How To Install Subfloor | Subfloor Ram Promaster Van Build

How to Identify Up and Coming Cryptocurrency Coins with Python/Pandas

BitCanna $BCNA Presentation & Invitational Tesnet tips — Imperator.co

Learn to build Ride-Sharing Uber Lyft App | MindOrks Weekly Newsletter

Road FC combines Mixed Martial Arts with the blockchain

Learning Pandas in Minutes (Part 3 — Apply Function to Columns)

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


More from Medium

8 Principles for Building a Great Design System in 2022

Structuring your Storybook

NativeBase Meets Figma