Beyond 1.0 - Lessons Learned and Things to Do After 1.0 Release of a Design System

Hi there, welcome to Beyond 1.0, lessons learned, things to do after the first release of a design system. By the end of this talk, I hope you can answer this one question. How can you scale and maintain your design system?

Hi there, my name is Amir Sami, I'm a senior software engineer at SNC Electric Company. In my free time, I like to bake delicious baked goods, I like to code, it's not just my profession, it's a hobby as well. I like to hike and explore nature. And I also like to lift heavy circles for some reason.

I'd also like to give a big shout out to my amazing team, without whom none of what I'm about to discuss with you would have been possible. My team and I work at SNC Electric Company, which is a global provider of equipment and services for electric power systems. We were founded in 1911 in Chicago where we design and manufacture switching and protection products. Today, our diverse global workforce develops innovative solutions for a more intelligent and resilient electrical grid. Building on this legacy of technological innovation and customer service, SNC empowers the transformation of the grid for an outage-free, sustainable electrical energy future.

Now what is a design system? A design system is a collection of reusable components, principles, constraints, and best practices governed by clear standards. There's many aspects to a design system, and one that you're most likely familiar with is a component library. There's many popular component libraries out there, such as MaterialUI, XDUI, ShadCN, and AntDesign. And basically, a component library is a set of reusable components you can use to construct an interface more effectively and efficiently. A design system expands upon a component library and includes information about what, when, and how to use color, iconography, and typography, as well as how to rate content for your application. It also includes support docs, and it also includes patterns for constructing interfaces with. This all comes together to form a design system. The role of a design system is not to constrain its users, but rather to make design and development easier, faster, and more consistent.

When we were working on our design system, we evaluated many libraries, ultimately selecting React. Hence, why I'm speaking at React Summit. We selected React due to its amazing support and community, its great performance for large and complex applications, as well as its multi-platform support through things such as React Native. We decided to use TypeScript in conjunction with React to make sure that our design system codebase was as type-safe as possible. We originally began working on our design system way back in 2018 when my manager and I realized that we were recreating the same components over and over again across multiple projects and we were answering the same design-related questions as well. After this realization, we began our research into design systems in early 2018, documenting requirements for our own design system, and we had an initial prototype ready by the end of 2018. Over the course of 2019, we continued to improve and iterate upon this prototype, eventually launching our version 1.0 at the end of 2019. In 2020, we continued to work on our version 1.0 and began planning for our version 2.0, which was a major revamp and overhaul of both the design system components and documentation. In 2021, we continued to iterate upon that, and in early 2022, we released our first version 2.0 of our design system. By then, we almost immediately began working on our mobile component development and figuring out how to incorporate that alongside our web components that we had already built. We continued to iterate upon our web components and release those, ultimately launching our mobile components beside them at the end of 2022 with the version 22.1, which was a major revamp and overhaul of our design system.

We continued to iterate upon our design system in the coming years, ultimately landing on the most recent version, which is 24.6. The initial version of our design system documentation site looked like this, including some basic information and guidelines on how to use color, typography, and iconography, among many other things, as well as a small set of React components that developers could use to construct interfaces. Our current version of our design system documentation site looks like this. As we expanded, it was more content and more components.

I'm proud to say that we've worked on our design system for over six and a half years. And over those six and a half years, we've expanded it to include over 70 components and supported over 50 developers internally, and we now support over four platforms, such as web and mobile, through React and React Native. It's important to understand who the users of your design system are as they're able to more accurately and specifically address their needs. For us, we've identified three user types, designers, developers, and testers. By identifying these three user types, we've been able to create user-specific documentation. For designers, we provide information such as tools and resources to more easily and quickly create designs. For developers, it's guidelines and guidance on how to set up your environment and how to use our components. And lastly, for testers, it's guidance on how to test applications built using our design system.

Needless to say, we have quite a bit of experience developing and maintaining our design system, and there's four areas I'd like to focus on and discuss with you today, the first being project architecture. When we began working on our design system, the scope of it was limited to just web components. But very quickly after the first version release, we began receiving questions about how we would incorporate other aspects such as mobile components, desktop components, utilities, and CSS variables, among many other things. And figuring out how to incorporate all these seamlessly while sharing as much code and styles across our design system was quite a task. Ultimately, we decided to refactor our entire design system codebase to a monorepo.

From my own experience, this was not a fun task, and I highly suggest that you start off as a monorepo as opposed to migrating over to one in the future. Having a monorepo from day one provides you the flexibility to grow as the needs of your design system grow as well. As you can see, our design system is quite large and complex with multiple moving parts. And as you most likely know, in any software, application, or software project, bugs will pop up. We've done our best to mitigate and prevent bugs by writing as many unit tests as we can, ultimately achieving over 80% code coverage, but that simply was not enough for us. To prevent even more bugs, we decided to expand the scope of our design system and our monorepo to include two additional internally facing packages, an example mobile app and an example web app. Like the name suggests, these are example applications that provide examples of our components in use with one another. Through the power of auto-linking packages in a monorepo, we were able to deploy these applications locally and test out the changes we've made and look for regressions or new defects. We've taken that a step further by implementing and integrating automation testing tools such as Cypress to automatically test these applications for those regressions and defects. We additionally have those automation testing tools run as part of our CI and CD pipeline to automatically check for those items and fail builds if any defects or regressions are found, notifying the team, and we can catch those before a release is completed and conducted. Now, when you initially begin working on your design system code base, it's very easy to haphazardly locate files all over the code base. But as it grows in complexity and in size, managing these different files and folders becomes very complex unnecessarily. I suggest you move this complexity to the side and instead co-locate as much of the code as possible.

Now, what does this look like in practice? Let's take a look. For example, with a button component, you have your directory for the component file or component. And in this directory, you should include the end to end tests, the unit test, the markdown file or documentation for the component. In our case, we use markdown as it improves the authoring and editing process, especially as we begin to involve non-technical roles such as designers and technical writers. We also include the styles, whether that's CSS or CSS and JS. We also include the scenes which are very similar to storybook stories. And lastly, the component file. Although this may just look beautiful, it provides a more easy way to work on components either as an existing maintainer or contributor of the project and as you onboard new developers. Instead of telling developers to look in multiple locations for files related to a component, you can instead direct them to a single directory such as this.

Now, speaking of onboarding new developers, every developer that you onboard, they bring their own code style. And although this may be okay in certain cases, when you're working on a design system, the ultimate goal is to make a maintainable code base. And that's simply not possible with multiple code styles. Instead I suggest that you enforce a singular code style across your entire code base through something such as a linter. You should have your linter run in two specific phases. The first being as a pre-commit hook to prevent developers from committing code that doesn't adhere to your code styles, and the second being as part of your CI and CD pipeline to prevent code from being merged in that doesn't adhere to your code styles. Now, this may seem annoying at first, and trust me, it is, but ultimately it improves the maintainability of your code base and the developers that are working and contributing to your design system code base will learn the code styles of your project very quickly.

Next, let's discuss documentation, which is arguably a very important part of your design system. When we were working on the most recent revamp of our documentation site, we were evaluating many frameworks such as Docusaurus, Box, and Styleguides, which are more purpose-built frameworks. We also decided to evaluate more general or generic frameworks such as Next.js. Ultimately, we decided to select Next.js as the designers behind the design system wanted to build a very comprehensive and custom design system documentation site that provided as much value as possible to our users. If we take a look at an example of a documentation page of a component, specifically the Button component, we can see that there's a lot of information here. I'd like to remind you that all of the documentation pages on our design system documentation site are built using Markdown. Now at the very top, we can see that we have the name of the component, a description, and right below that, we can see that this Button component has a Sister Mobile component. As such, we allow our users to toggle between the different platforms that are supported by this component. If we take a gander down this documentation page, we'll see additional information such as a live preview that provides an interactive GUI-like experience to play around and configure your component. Below that, we have a content section which outlines what sort of content to use with this component and what not to use with this component. And below this, we also have usage examples listed out which show common usages of the component, a brief description, and a code snippet. And lastly, a props details table which lists out all the props, their types, any default values, and a brief description of all the props available for the component. In early versions of our design system, the props table was something that we hardcoded and then obviously is not maintainable. Anytime we made a change to a component, we had to remember and make sure to go back to the documentation file and make changes there as well.

As you can probably assume, in some cases, we missed that and it caused frustration for both us as maintainers of the design system and our users of the design system. Luckily, in more recent versions of the design system, we've been able to solve this problem through this amazing library called react.gen typescript, which is able to dynamically parse out props for a component given the path to a component file. This ultimately allows us to simplify our documentation and allows us to build more interactive aspects of our documentation as well. If we take a look at an example code snippet from the markdown file for the button component page we were just looking at, we can see for both the component preview as well as for the props table, the props are no longer hardcoded, but rather under the hood, the props are parsed out from the component file and then are injected into both these components, ultimately allowing us to build more interactive aspects and more maintainable aspects of our design system, such as a component preview, which was previously not possible.