Introducing Design System Into Mature Codebase

Hello everyone. Let me walk you through introducing design system into mature codebase loosely based on Clio. But before we'll go into the more details, let me introduce myself properly. I'm Kasia Strzymska, design tech lead at Clio. I'm based in Poland, Gdańsk, but Clio is pretty much based in London. So I'm a full remote Clio employee.

So mature codebase, what exactly it is based in Clio? So if we think about a project, when we're starting a project, we are thinking about something pretty much meeting requirements, meeting expectations. We are gathering these requirements and then we'll be building something which is good enough to meet all requirements, deliver all the features. So in an analogy of a house, it has windows, it has doors, walls, a roof, hopefully some rooms inside, a bed. And this is like a final product.

But over years, over many years, for example, eight years, this house starts to grow and sometimes it starts to grow in a very weird direction. So this is what can a mature codebase become if developed at a very, very fast pace, as was the Clio example, where we are a startup, we're considering ourselves as a very fast moving, fast paced startup. And we've been trying multiple different features with our users. And because of that, our codebase grew a lot over these years. And because of that, we've met loads of challenges on the way, one of them being the fact that we introduced loads of components, many of which looked differently, behave differently. Even though they were about to have the same function or similar function, they all looked not the same. And same with styling. So over these years, we introduced many different styling. There was a rebrand going on on the way. So we had a couple of different color palettes living in the codebase, token sets, some colors or spacing being used as magic values. And over the years, we introduced plenty of inconsistent design patterns as well.

Mostly, but probably not only because of that, we've been working in siloed squads, we still work in squads, product squads, which are very focused on the features and delivering features in the scope of their domain. They are very much prioritizing fast delivery of a feature over consistency. And because of that, we've had to face more than these, but also these challenges of difficult maintenance, slow onboarding and disjointed user experience, which is, you know, for a company as Clio's very, very user focused, user oriented, disjointed user experience is super painful to watch, to see. We realized as a design system squad that there is one thing we need. So coming back to our house analogy, we need a plan. We need architectural plan of this huge house. We need to understand where we are, how many windows we have, how many doors, what shapes, all of this information. We basically needed data to guide us, which is also very Clio connected because we use data all the time. So design system was not any different.

We basically need to have data to guide us. And in order to gather some data, obviously, we need to investigate what are our options. We could write all of the solution by ourselves. But luckily, there was a React scanner, which is a very great library enabling React engineers to crawl through the code base to understand what components are being used. I will show you a little bit of code later on. Besides that, I've used technologies from our portfolio, like Clio portfolio, alongside GitHub Actions, Redshift, to store data and Count platform to query the data.

So if you like to see visualization of this, it was a GitHub Actions triggering the script, the node script living in the repo next to the repo. Then the script was using Webhook provided us through Fivetran and the Webhook was just getting the data and sending them over to Redshift. And from Redshift, data was available on Count. So our analytics and our engineers could query the data to understand where we are. So a little bit about the code itself, the script. So it's pretty straightforward. There was a scanner. We had to run it and wait for the results. The config I will show you later on. Then the stringification of the data. There's a little bit of mapping going on and the mapping is very simple. It's just moving from HashMap towards Array and then the Webhook I've mentioned before. So sending all this data via Fivetran in our case to Redshift.

So the config, also pretty straightforward. There's a crawl from. So we pretty much want to inform ReaRscanner where it's supposed to start the crawling. The method. So what ReaRscanner should do with the data? Should it return the script directly or maybe should it save somewhere to the file? There's also an option to return. It gives us an option to just get the data and maybe do some mapping with the data and then do something else about it. Also, it's possible to just save the data directly into JSON file and maybe do something with this file as well. The next option processors is basically all of the mapping functions provided by ReaRscanner by default, but also a possibility to create some custom ones as I've created. So the count, components and props is pretty much a ReaRscanner processor to go through all of these components and instances of these components and count the instances and props used and return this information in a form of a map. And then the second one, the custom one, I will show you. So the instance import info processor is a very simple one.

It needs to follow the pattern ReaRscanner is providing. So there are some arguments ReaRscanner is already passing down to the processor, such as pre-results, so like results from the previous processor for each component, which is an iterator over component and then a very simple sorting function. So within the iterator, I basically checked if there are any instances and if there is at least one instance, I wanted to understand where the component was imported from because the default ReaRscanner processor was not gathering this data. And I really needed that to understand if component was imported from our library of components, shared library of components or not. And then the pre-result, I just needed to pretty much sort the data again after this iteration and return and return. So the data we've gathered and managed to have a really nice outcome.

Worth mentioning, we had a shared components library when we started working on the design system. And it was just not used in all the cases. So here is an example of what we are tracking right now. We're tracking like top usage of shared components and non-shared components to understand what are the trends, which components are used more or which are dropping. So we need to find the pain points. And then what we did with this data. So obviously we need to think about the challenges we were facing. So collaboration was one of them. We are a design system, a team of two engineers. So as you can imagine, we couldn't really do all of that by ourselves. We had to collaborate. We had to figure out how to engage everyone. So we've started running engagement surveys with our engineering and design teams. We started running office hours every second Friday. We have 30 minutes for everyone to ask any kind of questions to help everyone, to enable people to be there for them. And loads of documentation. We've really focused a couple of first months of our work on preparing documentation, maintaining documentation, preparing some how-to documentation on how to collaborate, how to update, how to deprecate. Because we really want to enable everyone not be bottlenecks or gatekeepers of design system. And we set the target. So, yes, we are ambitious. We want to get to even more than 60 percent of adoption of our design system. But we started somewhere. So based on data and how the adoption is growing, we wanted to set a little bit more ambitious target. And we also, as I mentioned before, really focus on documentation.

And alongside how-to documentation, we also worked a lot on keeping the single source of truth. Which for our Leonardo, which is our design system, is based in Zero Height. Zero Height is an amazing platform offering us a space where we can store all of the documentation of components, where you can integrate storybook, you can integrate Figma, and you can keep documentation of components, but also content, style guide, patterns, documentation, foundation, design tokens, brand information, anything you want. And this is our source of truth. So if anything is disconnected, disjointed in Figma or code, this is what we should look up to. And that's very important.

We also took loads of initiatives as a design system squad. But I really wanted to emphasize the fact that we really tried to do small initiatives, step-by-step, small wins, very iterative approach. We really tried to not do like a very big bang changes, because we are still moving very fast. We have loads of people working in this code base. So we really didn't want to interrupt anyone.

And yeah, to wrap up, I wanted to say that design system is not only about components and tokens. Obviously, we need to start somewhere. But what we realized over time is that design system is a shared language, is a creation of shared language and process that speeds up teamwork and keeps everyone aligned. Thank you very much.