This library isn't open sourced, I'll do my best to describe its architecture here!

A high level gist of packages we used:

  chakra-ui/react: v2
  ark-ui/react: v5
  storybook: v8
  testing-library/react: v16
  vite: v6
  vitest: v3
  lerna: v6
  turbo: v2
  lost-pixel: v3

Acceptance criteria for this design system included:

• Accessible by default
• Theming support (light/dark mode)
• Modular and scalable architecture
• Comprehensive documentation and examples
• Easy integration with existing projects
• Rigorous testing to ensure reliability

More on how we got buy-in in this post.

We structured the design system as a monorepo using Lerna and Turborepo for package management and build processes. Vite for development and Vitest for testing ensured a fast and reliable development experience. We also implemented Lost Pixel for visual regression, a great open sourced tool at the time.

Each component was built using Chakra UI, and we deployed a link to our Storybook for each branch before merging so we could allow for better collaboration with design.

Over all, I can confidently say that the theming of each of the components was fairly straight forward, thanks to our designer. I cannot emphasize enough how important it is for engineering and design to be aligned when choosing a third party library. With using a third party library, there is an unspoken agreement that you will also inherit their conventions and limitations, and our designer was very aware.

How We Decided on Components

For those of us who have had the privilege of working on a large SaAS platform, determining whether a component should be included in a design system component library can be quite the philosophical debate. How widly is the component used throughout several products? How many iterations of it are there? Does this component require another library (An excel-like data table functionality? Complex popover positioning? Timezone and language generation?)? How complex are we willing to make our design system components?

For the most part, we agreed that we should minimize complexity and prioritize composability. Common patterns were addressed in our docs in a "recipe" section. By definition, a recipe is a set of instructions for making something from various ingredients-- and our UI recipes did just that. A code block for the required imports, and the code block for the composed components. Some recipes were comment cards, video cards, and popovers with different elements. These components could then be customized in implementation to suit the specific product area without having to add rigidity or complexity to our core design system components.

What I Would Have Changed

Hindsight is always 20/20.

One problem we ran into was not having the correct styles to map to in the new design system (some variants and tokens were deprecated). So, when we needed to switch over to the new design system, there was a lot of confusion around what should be used, and how to apply styles only for the old theme vs the new one. We provided temporary hooks for this "in-between" stage, when styles needed to be applied only for the previous theme. It was known tech debt, a "we'll clean it up later". Tasks like these often go untouched for years. However, we planned for addressing these to-be-unused hooks in our backlog, and luckily, we had some extremely helpful summer interns to help us clean up this debt. If I had to do this over again, I would make sure we had concrete mappings of all and variants and tokens between the design systems before even kicking off.

What I Would Never Have Changed

I would never have been able to do this without my team. Shout out to Seth Rieder, Kenneth Duverge, Matt Cullen-Meyer, Tyler Grove, and Christian De Botton.