Building an in-house design system from the ground up

Nathan Law

Written by: Evan Knox and Nancy Xu A design system is many things, but at its core, it is a collection of code, patterns and resources that can be used to give all your products the same look and feel. Our design system at Kinaxis is called Parcel, and this […]

Written by: Evan Knox and Nancy Xu

A design system is many things, but at its core, it is a collection of code, patterns and resources that can be used to give all your products the same look and feel. Our design system at Kinaxis is called Parcel, and this is the story about how it came to be. It is still an ongoing story, with an incredible journey.

How it began

Everything started with a bug. It was a UX bug related to the button padding in our Typescript React app. We’d seen many bugs like this, but we realized this particular bug wouldn’t exist if we’d had consistency in our product to help us know where the bug was hiding so we could have addressed it faster. If we had done things right, we could have made a fix in one spot and solve our problem everywhere. 

However, we didn’t do things 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 ship analogy

Imagine your product as a ship that your team is sailing on. Your ship has a few holes in it and needs some work. Every team struggles with this problem on some level. It’s a timeless question: Do we plug the holes in our ship or just dedicate more time to bailing out water? It can be complicated to plug holes, and if you’re in a time crunch maybe not even the right thing to do. The reality is that if you are on a ship that can barely get from one island to the next, then you will never make it across the ocean. 
It’s easy to push things into the “someday, we’ll address it” category, and it happens every day. It’s inevitable that in your career you’ll hear or have heard someone say something along these lines…

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

If you hear those words, remind yourself of LeBlanc’s law, and do everything you can to not listen if you believe that something needs to be done.
After all, “later === never,” according to Robert C. Martin in the book Clean Code. 

The point is: Plug those holes. Dedicate the time and effort and watch your ship transform from a janky sailboat to a seaworthy vessel. Whether your “ship” is an app, an api or a website, the building blocks matter more than you may realize.

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

Starting the design system!

 
Skyline of the Canadian city of Ottawa during winter

The cold and wet Ottawa spring weather makes even thinking of going outside a dismal idea. With such dreary weather, and being locked inside due to the pandemic, it was the perfect time to start our journey to develop Parcel in April 2020.

Following more research and planning including speaking with engineers at Shopify, watching design videos and reading up on the ultramodern design system libraries like AirBnb, Material and Fabric, we were ready to take a leap. We were inspired by different components from each system we studied. We especially loved and are grateful for the “Base Variant Pattern,” which AirBnb spoke about at React Conf (2019). With grand plans in mind, we just started, knowing that if we could make our design system 1% better each day, we would eventually have something.

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

Expectation vs. reality

Around this time, Smashing Conference hosted a virtual event on “Creating and Maintaining Successful Design Systems” with the creator of Atomic Design, Brad Frost (a living design legend). We jumped at this opportunity because it was aligned with what we aimed to achieve. From the conference, we learned how to sell and kickoff a design system, to plan and document it while it grows, as well as maintain it down the road.

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

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

The tech industry has a lot of “invisible gold standards.” Things you just must do, when the software/designs you create ends up being used. This includes tests, automated builds, reviews, more testing, linting … and the list goes on. These act as a massive barrier to entry of all new software projects because no firm takes you seriously without them, and they require a lot of effort, knowledge and time to implement.

These standards seem to change every day and require continuous effort on your part just to stay current. For instance, learning how webpack can efficiently bundle code, or how Lerna can manage multiple packages in a monorepo can be painful tasks. There are countless gotcha’s and so much blood, sweat and tears– before you finally see a tiny green build checkmark appear in Jenkins.

It was 2am when the first build finally worked. If “the making of our design system” ever showcased itself on a straight-to-DVD feature, this would be the late-night work montage bit. It was an immense initial effort, but with our automated builds and tests out of the way, our quality has never dipped.

 

“What should we call it?”

Parcel logo on a purple gradient background
It was time to start the real work: creating the reusable components that we make use of extensively today.

We had to start small. We needed to create the ‘atoms’ of this style guide which translates to the building blocks of every component we planned on making. These included things like color, typography and icons. It was becoming more important each day to showcase what the design system was capable of at any moment. We were getting hounded by the team because it wasn’t obvious what had already been done, what was in progress and what needed doing. We needed two things to accomplish this: a good name, and a website.

Names are hard. We floated some ideas for our design system name like Emblem, Kargo and Frontier. We ended up settling with Parcel because of its relationship to supply chain and packaging, core things for a supply chain management firm like Kinaxis.

Parcel is a name that we can all rally behind and be proud of. After setting up the website, we started our work. Piece by piece, or rather, atom by atom, we slowly but surely built out Parcel into what it is today. 

 

Design system sync up: the best recurring meeting ever

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

This meeting was special, not because of what we demoed, (we had been looking at the same button components for months now) but because this was the meeting where our leadership could see the value of our design system, and the toolset that was built around it. Seeing Parcel components in our product, with the automated build framework working, testing and publishing, convinced the movers and shakers that Parcel did meet the standard, and that we could start to invest real time into it.

All the evenings, weekends, hours upon hours of effort to get to this stage 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 critical. By consulting with stakeholders and subject matter experts, we ensured that Parcel met the needs of our firm and was always heading towards the right direction.
 

Prioritize teaching over doing

A computer monitor with a UX style guide on the screenA few months since that meeting, Parcel had taken off. Our small Readme file turned into a full-blown software project with pull requests every day. We were getting busier and busier managing this and in over our head We learned quickly that solid communication, and documentation is more impactful than thousands of lines of code. Suddenly, we were no longer being asked questions about how things would work, but rather when they would be finished.

Getting the word out about Parcel and its status was a challenge, so we hosted a tech talk and started a Teams channel. Parcel is now used in multiple teams and has evolved into a suite of tools and assets used to create beautiful, consistent designs. Parcel components are present in nearly all parts of our product. We have an internal website that showcases all the documentation, release notes and we have plans for even better documentation on the horizon.

To be honest,  the bulk of our effort went into making sure that everything to do with Parcel was simple and clear for users. If we found a process complicated, we would give it a critical look and make sure it could be done in less that five steps. For instance, connecting to our internal NPM registry could be done more easily by creating a `.npmrc` file instead of asking our users to set it manually in our docs.

 
Conclusion: give the users something real

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

 

AUTHORS: 

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

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

 

 

Next Post

Bridgit Launches Bigger and Better Integration With Procore to Help Contractors Plan Ahead

TORONTO–(BUSINESS WIRE)–Bridgit, the leading construction workforce intelligence solution, announced today the launch of an enhanced integration with Procore Technologies, a leading provider of construction management software. This new integration allows contractors to manage resource allocations, forecast project demands, and gain insight into workforce utilization without switching between project and resource […]