Creating a Maintainable UI Pattern Library

Visit our just-launched style guide at bitly.is/styleguide !

About a year ago, we committed to a major overhaul of Bitly’s platform to create the best possible experience for users of both our free and enterprise products. (You can read about the broader reasoning and implications behind the re-platform here).

Once we had charted the path ahead for a re-platform, the Bitly design team turned to the need for a common language across product, design and engineering that could produce a coherent, sleek UI. Our style guide is a reference we created to maintain modular code and visual consistency across the new platform.

To celebrate the fruits of our labor, today we are thrilled to release our style guide to the public. Our hope is that this central repository of our visual assets will help other design teams who are thinking about creating their own UI pattern libraries.

The new platform (above) meant a new set of product, design and engineering challenges.

Our style guide is organized around the principles of atomic design, which allows for multiple levels of organization. It is particularly suited to solving for the complex UI interactions and data visualizations that are core to our Link Management Platform.

Professor Chauncey
“The current Bitly platform was conceived and executed using the principles of atomic design, a highly methodical and flexible approach to interface development. Taking concepts from Chemistry, atoms represent the smallest visual components and act as building blocks for larger components, such as molecules and organisms.” — Bitly Style Guide

The benefits of having a codified set of patterns are numerous and applicable to almost any design team. It ensures greater efficiency in internal processes, allowing designers to be onboard quickly and engineers to re-use existing code. Ultimately, a style guide significantly decreases development time and streamlines processes.

Continue reading for a breakdown of the goals and challenges we faced in creating our style guide, our path to implementation and what we hope to accomplish in the near future.

Goals:

Briefly, our goals were to:

  • Create semantic naming conventions and relationships.
  • Maintain consistent design patterns.
  • Improve visual/smoke testing.
  • Establish descriptions and code samples.
  • Support cross-browser compatibility.
  • Support mobile devices.

Steps to Implementation:

  1. Engineering <> Design Sync.

We needed to make sure that engineering and design both understood how the components were rendered. We also needed to look at the current layout and figure out the best way to re-use aspects of the current site for our presentation layer.

2. Organization.

In order to identify style components and code base patterns, front end engineering and design started with a complete audit of all the style visualizations and components. Then we took those UI elements and started to categorize.

React.js is the main framework we use to write our components.

Component Audit:

This was the folder structure where all our 100+ React components lived.

/js
/components

Creating categorizations:

We named them accordingly to how we would relate each component name to specific categories. Then updated all the React import references within each component.

/js 
/components
/ui
/detail
/form
/graphs
/icons
/lists
/metadata
/navigation
/sheets
/states

It was a bit difficult to move multiple files at once because there was feature team work in progress at the same time, and each file would change immediately. We had to time these changes during a period where there was minimal feature work. We changed the single folder listing approach by grouping and semantically naming components in the code base. Then updated the UI to use these references. All our React components from the code base all the way to the visual representation will be categorized the same way.

3. Identical behavior.

We wanted to mimic our React component behavior on the app as much as possible. Here are a few ways we accomplished this:

  • By compiling the components the same way we do in the live product, we integrated existing app data type checking using Typescript.
  • We added practical mock data shapes, behaviors, animations and interactions to the guide. For example, our action sheets all have the same behavior to ease-in on the left side of the viewport. We created a CTA to trigger these sheets to behave exactly as they would when a sheet gets triggered on the web application (as opposed to just dropping the sheet component on the page).
Clicking on the blue ‘Bitlink Edit Sheet’ CTA link sends a trigger to open our action sheets with the same default animation as in our live product.

4. Creating descriptions and code samples.

We added annotations about branding, code usage and displayed live code samples to keep the code consistent. Now across all teams, everyone will know exactly what a specific component is named in the code base. We can view the usage, and look at the different ways a component can be rendered based on the data that gets passed in.

5. Optimizing for mobile and web.

Having so many components laid out on one page, it was difficult to create an experience where all the mobile elements are represented accurately.

We optimized the view for mobile while maintaining the live product component behavior and created a hamburger menu to navigate through each section.

Future Improvements:

“The design guide was never intended to be a finished document; as business strategy and product requirements change, so will our design guide. It is intended to be a living and growing resource, always changing depending on internal and external needs.” — Bitly Style Guide

There are at least a couple of enhancements we want to add to our style guide in the near future:

  • Integrating Visual Diff-ing Tools.

By integrating visual diff-ing tools we will be able to identify issues more easily when the layout is changed.

  • Integrating Style Guide Search Functionality.

Adding in search in the future will reduce the amount of time it takes to navigate to a specific component.

There’s still a lot more exploration and work to be done. We created an initial approach to creating our components, and how we want to re-use our components. We will continue to get more granular with our coding standards and usage, so that we can have more transparency between design, product and engineering.

Stay tuned for more! In the meantime, we’d love to hear your feedback, ideas and questions about our style guide.