Tips for Engineering a Company Rebrand

April 16, 2020

Reproduced from the Gusto Engineering Blog

I’m a bit lazy right now and haven’t spent the time to import over the pictures yet, but I will in the future! Feel free to click on the original posting in the link above, or just read the text of the post below.

During Gusto’s most recent brand refresh, a massive amount of engineering work was required to bring the warm and sophisticated vision our designers came up with to life. The road to our rebrand wasn’t easy: it wasn’t as simple as changing the logo and a few CSS styles. While we were ultimately able to bring this new vision of our app to life, there were many lessons we learned from our whole reskinning process. We want to share these learnings in hopes that it will help you approach your own brand reskin both smartly and safely.

Invest time into maintaining your style stack. Anyone involved in frontend engineering knows how dramatically the technologies can change over time. Tools are constantly updated and added, and new frameworks are always popping up for engineers to clamor over. A growing organization, once out of the explore phase, needs to have a discussion about what technologies to double down on and use daily to prevent distractions.

In this regard, fine-tuning and maintaining a great “style stack” is no different. Just like in JavaScript land, how people write and manipulate CSS is an ever-changing landscape. Making sure your company is up-to-date with the most robust tools for what you need is extremely important, especially if you’re planning on reskinning your product.

One problem we had before going into the reskin was that while we had a consistent style stack, it wasn’t the most up to date. This forced us to pull a few hacky tricks, like using a webpack-level feature flag to switch between our two different versions of CSS. We were also forced to use older technologies like Legacy Context, since we were still on React 15 at the time.

Having such limitations is just part of owning a system that grows more and more every day. But a direct result of us not properly maintaining our style stack was that our velocity in reskinning the product went much slower. We constantly got distracted because we were fighting with the older technologies that governed the product.

Since finishing our reskinning efforts, we now have a dedicated team that makes sure the application infrastructure within our monolith is always up to date, for both our backend and frontend technologies. Making sure you get engineers that both really care about your style stack and maintaining it will pay dividends down the road and make reskinning more effortless in the future.

Create and maintain a great component library, and make sure it gets lots of love. Similar to maintaining a great style stack, maintaining a robust component library is also very important. A component library, generally speaking, is a library of UI components that share and reinforce a similar theme or design. Component libraries are the bread and butter of making great looking interfaces in an efficient manner, while still being consistent with the company brand.

One issue we had was that before this project, there wasn’t a clear team that owned Gusto’s component library. It was just a combination of frontend engineers who cared about our components, but whose jobs weren’t directly related to maintaining and adding new things to this library. Not having a clear maintainer for our CL affected our main codebase because everyone was just adding things that would work for their own specific situations. It made reskinning the codebase a million times harder, since everyone was using the component library in unorthodox ways.

Since starting our own reskin, we’ve started a new Design Systems team, whose job is to not only maintain the component library, but also come up with clear instructions for how to interact with the components in them. These instructions come in the form of clear APIs, concise documentation, newsletters, and office hours. Having this team is easily one of the best decisions our company has ever made.

Add comprehensive visual regression tests to every part of the application. Visual regression testing is a new kind of test that essentially takes a screenshot of a base build and a screenshot of a new build, and diffs the resulting pictures pixel by pixel. Visual regression testing is important because it is both framework and language agnostic: it allows you to quickly identify and locate UI bugs without having to look at the HTML, CSS, or JS that was used to build it.

For example, we used visual regression snapshots below to verify if we’ve fixed a missing set of icons in our development branch. These icons went missing while we were messing with a few things under the hood. Using a visual regression tool called Percy, we were able to quickly identify if our fix worked, without having to comb through our more complicated unit tests.

Visual regression testing can catch UI errors that might be imperceptible to the human eye. While doing our own brand reskin, we just started to add visual regression testing to Gusto using Percy, but we did not nearly add enough screenshots to fully cover our application. Because of this, a few critical UI bugs like the one above slipped through the cracks and landed in production. It was only after a human noticed it did we add a new visual regression test for this page. Now, any future regressions would be caught, but we still let one bug slip out. Many times during the reskin, adding such tests for us were much like a reactive response after something slipped, rather than proactive effort to ensure future changes wouldn’t affect our app’s UI.

If you are planning on changing the brand of your company without disrupting the current experience for your users, you will absolutely benefit from adding a visual regression test suite to your app, and making sure it’s covering as much of your app as possible before starting your reskin. You will be able to have much more confidence that your changes are having the intended effect that you want them to have.

Spend a lot of time and effort into making feature specs really good. Feature specs (also called “request specs” in Ruby-on-Rails land) are end-to-end tests that spin up both the frontend and backend of an application and simulate user input on the application. It’s basically mimicking what a user would do and tests the result. Feature specs are usually justified because they’re the only way to ensure all of the moving cogs actually fit and work together.

However, they also have a hidden benefit: they allow a developer to quickly navigate through complicated business logic, and get to a specific view through running a simple test. For us, all we had to do was to put a binding.pry in our feature spec code, and the test would stop executing while we played around with the view we wanted to reskin.

Traversing complex business logic is handled by a feature spec. No human intervention needed! While Gusto as a whole understands the complicated laws that make up the Payroll, HR and Benefits industries, understanding the business logic that makes the application tick sometimes isn’t the most straightforward thing in the world, even for the most experienced engineers at our company. Writing a feature spec that can help guide you through the app is a low cost way to help developers render a specific page without having a human help them get to it.

At Gusto, we use Capybara to write our feature specs. Similar tools in the industry right now include Selenium and Cypress. Take our word for it: making sure feature specs are added regularly will make the reskinning process that much easier for your company.

Finally, delegate things accordingly One thing we should’ve coordinated better on was involving other teams earlier in the process. It was easy to convince ourselves in the beginning that we should minimize the impact the rebrand would have on other OKRs by assigning a small team to take care of everything.

However, in a complex application like ours that serves hundreds of thousands of small businesses every day, this proved to be much easier said than done. Even with great feature specs and Percy coverage, some things are just inaccessible without the context a real person can provide.

A rebrand at this scale takes much longer when such people aren’t available. Making sure you can reach out to at least one person in each team for the duration of the reskin will not only speed up the process, but make everything land a little safer as well.

Never forget a rebrand is a company-wide effort While the engineering team was busy reskinning the product, there were of course many other non-engineering processes that were going on at the same time all of this was going on. Illustrators, designers, writers, marketers, you name it – all of us were involved in not only rebranding the company, but getting the company to where it is today.

While reskinning your entire web application can be incredibly complex and will have its rough moments, it is truly an all-hands-on-deck moment that can bring a company together closer than before, especially if it’s done right.

Thank you to Matt Blake, Quan Nguyen, and Robin Rendle for reviewing drafts of this post.