Prologue: Before We Had a Style Guide
Years ago, our design, product, and engineering teams agreed that we wanted to achieve design consistency throughout our platform. But a big blocker was a lack of clear guidance for our engineers on how to keep the design consistent as they built new features. Within the design and engineering teams, we had a few specialists who knew everything about our guidelines, the codebase, and how to build these consistent experiences, but when growing as a company it’s difficult to distribute this knowledge. We wanted to have a way that would help, guide, and teach (new) HackerOne employees on how to build the platform by having a better overview of our components, style, and branding to increase consistency.
How We Started
In the beginning, everything was chaos where designers and engineers did not speak the same language. Each group used a different set of tools. To bridge the gap, our designers introduced an internal guide based upon a little gem called dress_code that would capture individual components and how to use them, and included code snippets that engineers could use (copy and paste) to quickly get started.
The idea was well executed and by designers providing friendly nudges, it was gaining traction amongst engineers. But the road ahead was still long and the goal far out of reach as we stumbled upon new problems.
Enter Storybook: Components in the Cloud
You see, designers and engineers had to run UI docs on their own machines if they wanted to use it. It shared dependencies with the main application, using a single package.json. This meant that it was relatively unstable, and it could break due to commits that essentially had nothing to do with the UI docs itself. In addition, it being self-hosted was a bit of a friction point. It was treated the same as any other service, meaning that if it crashed you had to fix whatever problem happened. This could be time-consuming and frustrating. To combat all of that, we decided it would be a good idea to have a hosted instance. This would lower the barrier to entry and make it a more enjoyable experience to use the internal style guide.
Eventually, we made the switch from UI docs to Storybook. They are both tools to solve much of the same problem but have slightly different nuances. There was not one singular reason, but rather a combination of multiple smaller reasons why we thought Storybook was a better fit for us. One reason was that we wanted to shift from hosting on local machines to having a shared hosted instance. There were definitely some other factors, too. For instance, many of the add-ons available with Storybook provided neat functionality that we could use. Info, Knobs, and Chapters are a few of the add-ons that seemed to provide guidance on how to make the most out of the style guide.
With Storybook set up, we achieved a new milestone in our mission. We now had an accessible and easy-to-use style guide to serve as a reference for both engineers and designers. But, like the best products, it remains open for change. As we implement our own new ideas and take inspiration from the ideas of others, the product continuously improves.
Getting the Big Picture: Example Pages
With Storybook powering our internal style guide, people gradually became more familiar with it and spent more time working with it. However, one of the things that we found lacking in the style guide was a “big picture view.” There were dozens of individual components to choose from, but no real guidance as to how they should fit together: As a developer, if I want to add a form for creating some record, which combination of components should I use, and how exactly should I combine them? If I’m not sure, I might start by copy/pasting the code from some existing feature, maybe a similar page I’ve worked on recently, and use that as a template. But this isn’t always ideal, as not all pages are implemented with consistent design.
To solve this problem we started building example pages. One such example is this “create foo” page. This page serves as a template of how individual components can be pieced together to establish a form. While it is by no means a complex page, it nevertheless has great value, primarily as an easy way to bootstrap pages.
We figured that it would be necessary to provide a path of least resistance that would promote the style that was considered preferred. It would also allow us to change or improve upon this preferred style without having to communicate with everyone individually – they would automatically receive the change the next time they use the example.
Enter Loki: Visual Regression Testing
All of the improvements we made to our Storybook had the desired effect: more people started to use it, and more often. Combined with the growth in the team, things were definitely trending in the right direction. The increased usage also had an unforeseen effect: people were updating components in Storybook itself. It was positive to see that developers were motivated to invest in the style guide, but the flip side was that sometimes they made changes that were unintended. It could be hard to see all the downstream effects of a CSS change. So we had the challenge of ensuring that updates to Storybook components did not cause any unintended changes.
Enter visual regression testing. After some experimentation, we hit upon the solution of using Loki, combined with reg-suit, which together provide visual regression testing for our Storybook components. When a developer made a change, Loki would test every page in Storybook against a reference image. A report generated by reg-suit would then provide a visual indication of the effect of a particular changeset. This serves to give people increased confidence that they know exactly what is going on, and avoid unintentional visual regressions.
What Is Next
The above sums up how we came to use Storybook at HackerOne, and the problems that we have run into. There are still several improvements that we would like to tackle in the future:
Google Analytics. Just like for external products, we need to gather data on where people spend their time, and the actions that they take. This would give us the data needed to prioritize improvements without relying solely on anecdotal evidence.
Multiple viewports, or mobile-friendly. The components in our style guide still only describe the main use case: users on a wide computer screen. A major initiative by the design team will be a push to make every component, every page, a pleasure to use on mobile as well.
Typography. Our text is not consistently styled throughout our application. There are no strict rules: when is something h2 and when is it h3? By providing guidance and example on typography, we hope to make the user experience more uniform.
It’s been rewarding to see the progress we’ve made so far on our internal style guide. It helps our designers and engineers stay in sync on how to build pages that follow consistent patterns, and empowers engineers to help maintain and grow the style guide without fear of breaking existing components.
Thanks for reading my blog post! I’m Siebe Jan, a Software Engineer at HackerOne on the Developer Enablement team. Tools that help other Engineers are near to my heart.Share