Tl;dr

Sparing you the lengthy but excellent case study, here's what matters:

Outcomes

"The palette system" Is a color system and framework for styling UI at scale, which is the foundation of the Saguaro Design System at Trainual.

• Semi-automated flexible component styling
• 4x reduction in time spent in iniative design process 🔥
• Drastic reduction of styling bugs and defects
• WCAG contrast compliant ✅
• Significant reduction of stylesheet variable tech debt

‍

Before / After

Phase 1

Phase 2

Phase 3

Architecture flows

Flows

‍

Background

So we left off with the Palette system architecture validated. Now heading into Q1 2021, we needed to figure out how to put our Ferarri engine in our sedan.

Tech stack migration

We were tangentially in the process of slowly migrating front-end frameworks and removing tech debt and building our own internal Design system and component library.The plan was to get rid of the generic bootstrap library and hodgepodge code and move to a React app using our own Storybook UI library.

The palette system was a keystone of our design system, but we didn’t have enough resources or bandwidth to work on it full time. It became a nights and weekends project between myself and Tech Lead Matt while we started to build a case to get more dedicated resources for the design system.

Building the data case

By this point we had plenty of data and customer feedback to validate the need for the architectural change, updating the custom brand styles feature, and fixing dark mode.

I made the case to leadership that this was an important architecture change that must happen, and then updated the greater org on what and why this was happening.

Process pains

The addition of dark mode added a ton of work to our day-to-day. For several months, we had to create designs for desktop, tablet, and mobile x2, and back into figuring out what the Hex colors in dark mode were because dark mode wasn't documented anywhere. No styles or design variables, just a quickly put together figma file.

On the Design side, we could start using the system in Figma to relieve some of our own pains, like staying ahead of our rapidly growing Engineer head-count.

Once we started to try and introduce some of the new variables in the design files, lots of questions on hex colors during QA became a large stress point for Matt and I. The issue was our tech debt.

No one knew how to navigate the maze except for a couple of engineers. Changes we thought we had made wouldn’t make it into staging, and then we would uncover the variables being overridden in another file.

Getting into the weeds

With Matt supporting, I got my environment set up and we started to wade through legacy code to figure out where to start.  As we got deeper into the code-base, it became clear how gnarly the front-end tech debt was, which had only worsened with the addition of dark mode.

Variables were scattered across dozens of different stylesheets in different folders, and we had to work backwards to find out what was being used where.

To make things even worse, there were several overriding !important classes spread across several different legacy stylesheets. cool.

The component variable names were more specific yet somehow less informative than I thought was possible, and the naming convention would swap depending on who wrote the code, and in some cases using off-the wall color names like $bunker???

Needless to say, this had become a complicated problem quickly. We were going to have to take a step back and figure out how to migrate our legacy setup to the Palette system.

Divide and conquer

I put together a diagram based on what we had talked through concerning how we would be able to implement the system so we could make sure we were all on the same page and start sharing the work load.

The part that was beyond my skillset was writing the logic for swapping color palettes based on the users choice, and then determining the logic for the display mode.

While my engineering colleagues spent their time trying to solve that tricky problem. I had the “exciting opportunity” to sift through the legacy variables and map them to the new Palette variables.

Seeing #red

The system architecture was engrained in my brain, so it made sense that I would be the one to tackle mapping old variables to new.

Because the variable names were often not organized, nor made any logical sense name-wise, we found the best way to determine how to map them was to change the variables to #red and check it visually in my local environment.

There were just over 1200 lines to check, and the compile time took between 30 seconds to upwards of a minute or two; Needless to say, it took a minute. I chipped away at it in chunks between initiatives and during slow weeks.

I found ways to entertain myself and the team:

Progress

We were chugging along and making good progress. I made a final push during an initiative transition week to finish the variable mapping; Poppi Li knows exactly how I felt..

Mapping checked off the list, we had made some minor changes to mappings and hex codes, as well as uncovering more legacy file changes we needed to make.

On the Engineering side, they had figured out the color switching logic. Besides the UI changes to the Brand styles feature, it seemed like we were approaching the finish line!

Then we had a startup moment that put everything on hold. A product strategy pivot.

Strategic shakeup

Historically, Trainual has been exclusively a training and documentation tool. Starting Q2 2021, leadership made the strategic decision to pivot the product to define the Business Playbook category; a single source of truth for everything company-related. This new functionality like:

• Company mission, vision, and values
• A people & team directory
• Interactive Org chart
• Roles and responsibilities

Tying these features into the existing documentation and training was a perfect fit. This pivot and new functionality was going to be timed with the release of our CEO’s book, The Business Playbook, in Q4.

Beyond the book release, this pivot was also geared toward securing our Series B funding. Needless to say, it was a monumental effort by the entire business. You can read all about that in this case study.

The Palette System was going to have to be put to the side until we were on the other side of the pivot.

Growing pains

During the Playbook push, we were hiring a ton of talent to scale and build out a few new squads which would form immediately after the Playbook event.

Each squad would focus on a specific area of the product Our teams were being divvied up based on skillsets, desired career paths, and needs of the business.

We had a heap of new and shifting responsibilities, and collaborating on the Palette system would be a challenge. Matt went to the new Performance team and I went to the new Hybrid-growth squad.


Luckily, we had successfully made the business case to finally staff a dedicated Design System squad. I was an official member of the team, acting as the system architect and providing guidance as needed. My main responsibility was getting the team to run autonomously so I could get any of the IC work off my plate.

On the Engineering front, Matt was instrumental in helping me with the design system architecture and getting our component library set up. When we filled our dedicated front-end engineer role, Matt played the same role I did in helping getting to a state of autonomy.

Hardened documentation

With all the new hires recently onboarded, we had to make sure our documentation was as robust as possible and hopefully reduce the onslaught of slack DM’s.

Great minds think alike, and Matt and I ended up creating some stellar documentation for our respective departments at the same time. 🧠

Where were we

Most of the complicated architecture work was done and we started to turn our attention to the UI. Matt and I worked with the core ds1 team to ramp them up so they could pick up where we left off.

Unfortunately, the DS1 team was just as swamped as the rest of us. We only had 3 core team members, 2 designers, and 1 engineer. (Myself, Lex, and Dacey).

We didn’t have a dedicated PM or tech lead. The team was really strapped for resources. Dacey and Lex were swamped with the evolving component development process, and I was focused on Gs3 initiatives.

There was a lot of refactoring that needed to happen on the components we had this far, which just weren’t built properly. They were also creating a lot of Jira issues for squads to pick up during sprints. It was a struggle to resume the Palette system's work.

Product line red tape

We hadn’t been in product lines very long, and figuring out overlapping parts of the product and congruent initiatives was proving to be a challenge.

Gs2 was working on revamping the content experience, which was long overdue, and they were starting with the core WYSIWYG editor. The core of our content features were built on Froala. The UX of the content experience was terrible, and Froala was a major reason why.

This was also an opportunity to convert more of the application to React; The entire editing experience was in regular Javascript. This meant there was a lot more time needed for research and planning.

Why this mattered to Ds1 and the Palette System intiative is that you could use your custom brand styles on paragraphs styles in the content editor. The existing functionality allows you to set any color you want, for any paragraph style.

This meant that the content editor experience and palette system were interdependent. but figuring out how to render the correct variables from the palette system was an entirely different approach than the legacy system.

To make matters more difficult, the UI components in the editor needed to be built as a plugin to work with the content editor, and the gs2 team had yet to research what library they would move forward with.

The best course of action was to let Gs2 figure out what editor library we would use before attempting to connect the palette system to the paragraph styles.

Return to sender

After Ds1 encountered these unforeseen complications, the Palette System was put back into the hands of Matt and I to get through the roadblocks.


We needed to transition as fast as possible with the smallest amount of disturbance to the customer. For every account that has custom brand styles set, they would continue to experience odd interactions and accessibility issues in the platform, and we would have to continue to support that nasty code.

Taller weeds

We needed to ax the custom hex functionality and limit it to the new palettes palette colors. But we also needed to remove the user’s  ability to choose any palette color for any paragraph style.Every possible combination of heading colors is considered a different permutation in the database. Each permutation has to reference the palette files.

Between 10 palette colors and 7 paragraph styles, there are 604,800 possible permutations; that is a few thousand too many for our liking. It was a huge performance issue we needed to get around.

We decided we would allow paragraph styles to inherit the chosen accent color for the account. This would continue to add value to the feature while keeping performance optimal. It was also a good stepping stone to start decoupling excessive customizability over UI.

We decided that we would gently prompt customers with an Appcues modal on what’s changing and why, and then direct suggest that they take action.

This would hopefully cover a large percentage of active accounts. Email comms would also go out during each phase to make sure customers had the chance to see it. From there we would set a time frame by which customers would be forced over.

‍

Next steps

Poised to be migrated into production is where this project was once I handed it off. Im excited to hear and see it once it's in Production 🤞

‍