The Making of an MUI based design system

.

How we used react’s MUI framework to create a scalable and consistent design system at Sonara.
01
Background

Project background

.

In late 2022, I led the making of Sonara’s first official design system in close collaboration with our engineering team. The project was catalyzed by overall need to ensure operational efficiency, scalability, and quality control as our use base grew.

React’s MUI framework served as a foundation for our design system, which is currently used across both mobile and desktop web applications.
Company:
Sonara Health
Timeline:
2 months
Role:
Lead Product Designer
Team:
Head of product, Lead Software Engineer, Senior Software Engineer

The impact

.

Faster design  QA
Better Figma to code consistency meant fewer design bugs to resolve in new features.
In-line styles eliminated
We went from several hundred instances of inline styles to only 15.
A more intuitive experience
Creating cohesion in our design language resulted in a more intuitive experience for users.
02
The challenge

Infrastructure growing pains

.

By 2022 Sonara had a growing user base. We had built both our patient and clinician facing apps rapidly, from scratch, much faster than we had been able to build and scale our design system.
As a result, we had a half-baked design system with minimal governance that didn’t take advantage of MUI theming. We also had a lot of inconsistency among designs and between Figma and code. With an upcoming rebrand, we knew our design and technical debt would only increase further without a proper design system.
" With an upcoming rebrand, we knew our design and technical debt would only increase further without a proper design system."
Intact Sonara label

vs

.

Destroyed Sonara label

The end game

.

01
Scalability
As an early stage startup, we needed a design system that could grow with us. We couldn’t predict the future of our team or products, but we could create a system that would support any number of possible futures.
02
Flexibility & composability
By focusing on getting the infrastructure and fundamental building blocks of the system right, I hoped to foster creativity for designers and a consistent experience for end users.
03
Consistency via cohesion
Rather than aiming for consistency for consistency’s sake, I wanted to prioritize a system that felt intuitive to users, designers and engineers. I viewed consistency as a byproduct of composability and cohesion.
03
Discovery

Unpacking design & dev disconnects

.

I viewed our design system as an internal tool to support design and engineering collaboration and efficiency in our shared goal of providing the best possible experience to users.
To understand how our design system could better serve designers and engineers, I ran a discovery call with our engineering team. This helped us align on the gaps in our current design system workflows and documentation and how we could address them.

The gaps in our system

.

01
Figma  →  MUI API inconsistency
Our component naming and structure in our Figma library was inconsistent with MUI's API documentation, so engineers could not easily discern which MUI component they should be using and sometimes created new component unnecessarily.
02
No theme utilization
In code, most of our styling was done inline, which was a front-end nightmare, perpetuated inconsistency, and prevented scalability. Better utilizing MUI theme tokens for color and text styles was the antidote to many of our problems.
03
Inadequate governance
We didn’t have any agreed upon  practices for governing and documenting our design system, which made implementation and design reviews a guessing game. We needed to establish efficient and sustainable design system management practices that could evolve with the team.
04
System Foundations

A scalable structure for the system

.

We needed a way of organizing our design system that would evolve with our team structure and product offerings. We already had two web apps for different user types, intended to be used on different devices. Usability testing had already led to some research-informed  divergence between patterns and components used in each app.
We ultimately agreed on a "cascading" structure for our component libraries in Figma and analogous theme files in code. A shared library file would contain our theme tokens and shared, core MUI components, while contextual libraries would contain custom components and modified or combined core components used repeatedly in a specific context such as a product.
" A shared library file would contain our theme tokens and shared, core MUI components, while contextual libraries would contain components used repeatedly in a specific context such as a product."
Intact Sonara label

vs

.

Destroyed Sonara label
05
Core Components

Fast-tracking core components

.

As a solo designer building out our design system in parallel with other features, I needed to work efficiently. Rather than rebuilding our existing components to match MUI’s structure, I advocated for purchasing MUI’s comprehensive UI kit for Figma as a jumping off point for our shared library.
Using a prefabricated library allowed me to focus on customizing styles and components as needed while maintaining alignment with MUI's theming and props.
"Rather than rebuilding components to match MUI’s structure, I advocated for purchasing MUI’s comprehensive UI kit for Figma as a jumping off point for our shared library."
06
Theming

Color tokenization & style overrides in Figma

.

Aligning our use of color variables in Figma with MUI theming was one of the trickier parts of this project. One of our engineers taught me how to use code sandbox to test which color the theme applied to specific components by default. This helped me ensure consistency between Figma and code and communicate desired overrides as needed.
To indicate where I wanted to globally override the theme color on a  component, I created a group of "theme override" color variables in Figma. I used a component-level token naming structure to specify the component, variant, color, state, and surface on which the override should occur.
"One of our engineers taught me how to use code sandbox to test which color the theme applied to specific components by default"
07
Design System documentation

Documentation for designers & engineers

.

Due to resource constrains and the size of our team, we agreed that most of our design system documentation would live in Figma for the time being. In the future, we hoped to bring our core components into Story book and graduate to a more sophisticated solution.
For the sake of maintainability, and with guidance from our engineers, I focused our technical documentation on style overrides and other customizations on the theme. For designers, I focused on guidelines for using our components as intended.
Style overrides & other customization
In the configuration notes for each Figma component, I indicated the presence of style overrides on color (which were also linked to components as override variables) and other customizations developers should be aware of.
Usage guidelines and configuration
To help guide designers using our components, I formalized the basic usage guidelines we had established for each component and outlined the properties that designers could configure.
Usage guidlines & configuration
To help guide designers using our components, I formalized the basic usage guidelines we had established for each component and outlined the properties that designers could configure.
08
Excecution

The 4 phases of implementation

.

Once we had our improved design system up and running in Figma, we needed an implementation plan. This would be a significant front-end undertaking given that most styling was currently in-line and in some places we were not using the correct MUI components (eg. an MUI box component styled like a chip instead of the MUI chip component).
I worked closely with our engineers to scope and plan the implementation of our design system update, which we broke down into 4 phases with a design QA checkpoint after each one.
09
Implementation Documentation

Even more documentation

.

Although our updated design system was now well documented, implementing the changes inevitably required further documentation to communicate to engineers exactly what was changing and where.

The documentation I created required an audit of both of our apps and gave special attention to changes that wouldn’t automatically be addressed by moving color and typography styling responsibilities to MUI’s theme provider, including:
  • Which typography variant should be used where for body and header text outside of components
  • Where incorrect components were being used and needed to be swapped the correct MUI components
  • Style overrides on specific components that needed to be added to the theme
10
Results

A better experience for designers, engineers and users

.

Our updated design system created clarity for me, a designer, and our engineers, and it gave us a common language to speak when communicating about components and styles. It also created a more consistent experience for our users.
Although it can be difficult to quantify  the value of a strong design system, there were some quantifiable benefits:
  • Faster design QA’s - Our design QA’s before shipping features became significantly faster because there were fewer UI issues to address
  • More manageable code - Moving styling responsibilities to MUI’s theme provider eliminated almost all in-line styling.
  • A better experience for end users - Consistency within and across our products was byproduct of a more cohesive and composable design system.
11
Lessons Learned

Reciprocity in the learning process

.

This project was one of favorite design learning experiences because it took me outside of my comfort zone and provided an opportunity to better understand the nexus of design and code, in close partnership with our engineers. Because our in-house devs were not MUI experts we were able to learn from each other and grow together.
By the end of the project, I had learned how to interpret Sonara’s theme files in github and developed a deep understanding of the many possibilities MUI’s flexible theming offers. Going forward, my ability to communicate with our engineers dramatically improved as a result.