Build an internal design system from scratch

Written by: Evan Knox and Nancy Xu

A design system is many things, but at its core it’s a set of codes, templates, and resources that can be used to make all of your products look the same. Our design system at Kinaxis is called Parcel, and here’s how it came to be. It’s still an ongoing story, with an incredible journey.

how it started

It all started with a bug. This was a UX bug related to button padding in our Typescript React app. We had seen many bugs like this but realized that this particular bug wouldn’t exist if we had had some consistency in our product to help us know where the bug was hiding so we could fix it more quickly. If we had done it right, we could have made a fix in one place and solved our problem everywhere.

However, we didn’t do it right. Not because we didn’t care, but because time is a luxury and we live in a world where everything is due yesterday.

The boat analogy

Imagine your product as a ship that your team sails on. Your ship has a few holes and needs some work. Every team struggles with this problem on some level. It’s a timeless question: are we plugging the holes in our ship or are we just spending more time bailing out the water? Plugging holes can be tricky, and if you’re pressed for time, it might not even be the right thing to do. The reality is that if you’re on a ship that can barely get from island to island, you’ll never cross the ocean.
It’s easy to categorize things as “one day we’ll fix it,” and it happens every day. It is inevitable that in your career you will hear or have heard someone say something along these lines…

“We can figure that out another time. Let’s focus on our current priorities.

If you hear these words, remember LeBlanc’s law (“Later === Never”), and do whatever you can not to listen if you think something needs to be done.

The point is: Plug those holes. Put in the time and effort and watch your ship transform from a janky sailboat into a seaworthy vessel. Whether your “ship” is an app, API, or website, the basics matter more than you might think.

In our effort to close the hole, we held a humble bug fix meeting. We talked about the bug, but also how to fix bugs like this in the future. We agreed that we needed a better way forward, so we could focus on the future and not continually fix the past. After the meeting and a lot of research, all the responses told us one thing: we needed to create a design system. A design system would ensure that our ship was built from well-designed building blocks, which could be easily modified or replaced, and would adapt to our needs as we sailed across the ocean.

Starting the design system!

Ottawa’s cold and wet spring weather makes even going out a dreary idea. With such gloomy weather and being locked indoors due to the pandemic, it was the perfect time to start our journey to grow Parcel in April 2020.

After more research and planning, including talking to Shopify engineers, watching design videos, and reading state-of-the-art design system libraries like AirBnb, Material, and Fabric, we were ready to take the plunge. We drew inspiration from different components of each system we studied. We particularly liked and are grateful for the “Base Variant Pattern”, which AirBnb talked about at React Conf (2019). With big plans in mind, we just started, knowing that if we could improve our design system by 1% every day, eventually we would have something.

The first commit we pushed to our design system contained a simple readme file that said “DESIGN-0, here we go! Initial Commitment. This would form the basis of our extensive design system that we use today.

Expectation vs reality

Around this time, Smashing Conference hosted a virtual event on “Creating and Sustaining Successful Design Systems” with Atomic Design creator Brad Frost (a living design legend). We jumped at this opportunity because it matched what we wanted to accomplish. At the conference, we learned how to sell and launch a design system, how to plan and document it as it grows, and how to keep it going.

As a starting point, we took the style guide already in circulation within the UX team and applied it. We were inspired by the Atomic Design model, in which you build larger components (molecules) from small isolated elements (atoms).

“It’s hard to launch a rocket when you have to stand under it.” — NASA, probably.

The tech industry has a lot of “invisible gold standards”. What you need to do, when the software/designs you create end up being used. This includes testing, automated builds, revisions, more testing, fluff… and the list goes on. These act as a huge barrier to entry for all new software projects because no company takes you seriously without them, and implementing them takes a lot of effort, knowledge, and time.

These standards seem to change every day and require continuous effort on your part just to stay up to date. For example, learning how Webpack can bundle code efficiently or how Lerna can manage multiple packages in a monorepo can be a daunting task. There are countless pitfalls and so much blood, sweat and tears – before you finally see a little green build tick appear in Jenkins.

It was 2am when the first build finally worked. If “the creation of our design system” ever showed up on a straight-to-DVD feature, it would be the late-night work montage piece. It was a huge upfront effort, but with our automated builds and testing, our quality never went down.

“What should we call it?” »

It was time to start the real work: creating the reusable components that we use extensively today.

We had to start small. We had to create the “atoms” of this style guide which translates into the building blocks of each component we planned to make. These included things like color, typography, and icons. It became more important every day to show what the design system was capable of at all times. We were being harassed by the team because what had already been done, what was in progress and what needed to be done was not obvious. We needed two things to achieve this: a good name and a website.

Names are tough. We tossed around a few ideas for our design system name like Emblem, Kargo, and Frontier. We ended up settling with Parcel because of their relationship with supply chain and packaging, essentials for a supply chain management company like Kinaxis.

Parcel is a name we can all rally behind and be proud of. After creating the website, we started our work. Bit by bit, or rather, atom by atom, we slowly but surely built Parcel into what it is today.

Design System Synchronization: The Best Recurring Meeting Ever

That summer, we finally met with management and our senior engineers to review Parcel and show our working demo.

This meeting was special, not because of what we demonstrated (we had been looking at the same button components for months now), but because it was the meeting where our management could see the value of our design and the toolset that was built around. Seeing Parcel’s components in our product, with the automated build framework running, testing, and publishing, convinced movers and shakers that Parcel was up to standard and we could start investing real time in it.

All the evenings, weekends, hours and hours of effort to get to this point had paid off. By seeing the real thing in all its glory, decisions could be made, questions could be asked, and more work could be done.

Of course, engaging with people throughout the creation of Parcel was key. By consulting with stakeholders and subject matter experts, we ensured that Parcel met the needs of our business and was always heading in the right direction.

Prioritize teaching over action

A few months after this meeting, Parcel had taken off. Our little readme file has grown into a full-fledged software project with daily pull requests. We were getting busier and busier dealing with this and over our heads. We quickly learned that strong communication and documentation has more impact than thousands of lines of code. As a result, we were no longer asked questions about how things were going to work, but rather when they would be finished.

Raising awareness of Parcel and its status was a challenge, so we held a tech conference and launched a Teams channel. Parcel is now used across multiple teams and has evolved into a suite of tools and assets used to create beautiful, cohesive designs. Package components are present in almost every part of our product. We have an internal website which features all documentation, release notes and we have plans for even better documentation on the horizon.

To be honest, most of our effort has been to make sure everything about Parcel is simple and clear for users. If we found a process complicated, we would give it a hard look and make sure it could be done in less than five steps. For example, connecting to our internal NPM registry could be done more easily by creating an “.npmrc” file instead of requiring our users to manually define it in our docs.

Conclusion: Offer something real to users

By far, the most valuable lesson we learned from this experience was to take the leap and put something real in people’s hands. Never wait for later, and never, ever give up when you hear the words “maybe later, or have”. At worst, you learn a lot, but most likely end up with something amazing. Creating Parcel has been an incredible journey and will undoubtedly be one of the highlights of our careers.


Evan Knox is a software engineer on the Front End team at Kinaxis. He has been with Kinaxis for about two years and is based in Ottawa, Ontario.

Nancy Xu is an Ottawa-based User Experience Designer at Kinaxis, specializing in UI design. She has been with Kinaxis for four years and has worked on several versions of RapidResponse.