How we delivered our design system with detailed documentation and comprehensive communication

Darren Wong
Dec 3, 2018 · 9 min read

This is the third and final article outlining how we delivered our design system, Connect. Previously, I discussed how we started the design system by selling the idea and building a small team. Then we went through our process building the design system through phases and validation. In this article, we will cover how we delivered our design system internally and most importantly, externally.

Why Connect?

Early on we did a brand exploration to discuss guiding principles and a vision for the product. The word connect continued to appear in our discussions, how we connect the “why” to a user’s actions and eventually how we would connect the product experience with one unifying design system.

Roadshow

Communication is one of the strongest tools in a designer’s toolkit. Great designers and thinkers can effectively communicate, educate, and advocate for their ideas. Early on in our process, we missed a crucial piece of communication which caused a bit of user pain and internal frustration. Since then we adopted a very clear communication plan developed internally by Chris Abad (VP, Product) and Mark Towfiq (SVP, Product & Engineering). There are a few phases to this release communication plan and we focused on train, slipstream, and announce. This meant we would release the improvement as ready, with a heads up to customer-facing teams, and that was announced externally as part of regular cadence. We were aligned with internal teams and communicating with our external customers in a timely manner.

Our fearless leader, Scott Johnsen, the design manager of the design system team was crucial to this process. He led a mini-roadshow presenting and communicating with the various squads as new structural updates were being shipped. It was important to show the small piece we were working on as well as the final product we were building toward. This helped our team members calibrate and get aligned with the goals and final outcome of the work.

We have a department-wide standup every morning for squad announcements and such. In the months leading up to the launch of Connect, we used this stand up to remind our engineering teams that Connect was coming down the pike. This gave the project more visibility and gave developers a face to a name when asking about styling questions. As more questions arose there was a need for a resource for common elements and patterns.

Kits
We have diverged into two kits for Connect: Design Kit and Developer Kit

Design Kit
This is the artifact our designers will interact with most. It will have our principles and guidelines, our brand expression, our illustration system, and the all-encompassing Sketch UI kit.

Developer Kit
Emily built the first version of our toolkit (toolkit.usertesting.com), a website containing every component in our product along with code snippets. This also contained style guide direction, our use of BEM, and the architecture of Sass files in our product. This is something we are working on today. We do not want to provide just the code snippets for our elements but the values it provides our customers. We want to provide the why behind the decisions we’ve made.

In both kits, we are focusing on the ‘why’ behind each component. Why it exists, why our customers should care, and why our internal teams should care.

Building a Sketch Design Kit
We have a Sketch Library that contains each element, component, and page necessary to build the UserTesting of today and plan for the UserTesting of tomorrow. Here are some things I learned while building out this sketch kit.

1. Focus on value
As a designer working on a design system I have a unique opportunity to build the thing that I will use. However, it’s easy to get lost in the symbols, nesting, and plug-ins and forget that you aren’t building the worlds most scaleable text input. You are allowing your designers to move rapidly to get ideas into prototypes and prototypes to code. This static mock they build is a short-lived artifact and your design system must accommodate this feeting moment.

2. Break to build
One fear I had while building the system was: what if I spent all this time building out these perfect symbols only to find the designers detaching from them thus rendering the linking of all components useless?! I had to remind myself of the value this Design Kit is providing. This scenario is what happens today and I encourage designers to detach when they need to and follow up with them afterward. Is it because the override panel on the right is too confusing? Is it because it was faster to make a change by detaching? Your system shouldn’t change workflow, it should enhance it.

3. Talk to your users (designers)
At UserTesting we care a lot about… erm, user testing. I used this as an opportunity to talk to the designers while building out the system. I watched how they used Sketch and the library today. I listened to what they felt was missing from the system. Keeping this close line of communication also built trust with the team.

4. Get organized
A good Sketch Library is organized. A great Sketch Library is organized based on the people that use it. Too much organization and things are heavily nested and challenging to find. Too little organization and your components become unruly, thus becoming challenging to find. There’s a sweet spot and it comes by talking with your designers to figure out what works for your team.

An example of this was gathering feedback on symbol organization in Sketch. I asked teams externally in the Design System Slack group what they preferred and compared that to my teams’ preference. Based on both pieces of feedback we are moving toward option B: a collection that does not rely on nesting and one that maps to the organization of components in our Developer Kit.

5. Communicate changes
We have one central Sketch Library in a shared folder in Dropbox. The designers have read access to this file and the design system team has to write access to this file. The great thing about Sketch Libraries is a change to the root file will cascade across all files. We have a review every Tuesday and Friday where I announce the change-log to the team and they provide feedback on symbol issues or suggestions on new components.

6. Instructions and On-boarding
We’ve also created a Connect Readme for anyone who uses Sketch to create digital designs of our products. Showing them how to link to our library, what plug-ins to use, and what components exist. Eventually, we will be folding this into our new documentation website.

SnapUT
Another crucial part of delivering this new design system was a dedicated QA member on our team (shoutout Zack!). They helped maintain an internal visual regression product called SnapUT (we forked this tool https://github.com/wearefriday/spectre) to help catch visual changes before they went out. There will be times you’ll need to remove unused code and the acceptance criteria is “No visual regressions.” Having a tool like this enabled us to release with a higher level of confidence.

This workflow was specifically important to Connect because we were having to manage two UIs against five browsers. This not only sped up his workflow but ensured a high level of quality was met when launching Connect.

Launch

Early on in developing Connect we thought it would be a good idea to have an internal switch that would allow an employee to see what was happening under the hood. Our expectation of this switch was that it would give our internal stakeholders some ownership in offering suggestions and it felt like they had a pulse on the product.

We were wrong.

This project failed for a number of reasons but the major reason was a lack of communication. It was not accurately communicated to our customer-facing teams that there was a difference between the current UI and the in-flight UI. This lead to customer interactions where they were referencing the in-flight UI. It was a bad experience on all sides. We turned off the switch and continued to tinker with it on our separate staging site.

About two weeks until launch we were ready to try this again. We took our learnings from the last time and were a lot further along in the build phase which gave us the confidence to launch this out to the company. We turned it on Wednesday afternoon… and heard the thing you want to hear when launching a new visual design system: nothing. No complaints and a few excited customers.

It went off without a hitch. We also started a Slack channel focused towards our customer-facing teams to ask questions #ConnectAMA. To make sure we not only told our co-workers this was coming but that they had support from our team as they transitioned to Connect.

The internal launch was a good sign. We got our most active internal stakeholders on board and successfully using the product. Our internal launch happened on Wednesday and we carved out time for Friday to launch this out to all our customers. After a lot of meetings and internal conversation, we decided to turn Connect on for everyone with some messaging and no way to turn back to the old UI. We did this for a few reasons:

1. Calculated
We adopted the structural, visual, experience phased approach when launching Connect. This meant that the big pieces of the UI would be moved and validated before adding the new visuals (colors, type, spacing). The feedback from this phase would lean on the subjective side and we would depend on our customer-facing teams to work with customers to transition customers (if any) to the new design.

2. Confidence
We put a stake in the ground that this was an improved experience based on internal vision and external validation.

3. Communication
This might not have worked for another company but we had a consistent line of communication with internal and external customers and executive buy-in which gave us a lot of confidence to move forward. Continually saying you’ll do something then delivering on that promise was a great way for us to build up credibility amongst the department.

What’s next?

Through developing a strong concept, building validated components, and communicating internally and externally we were able to deliver a successful design system. This was just the beginning, now we are shifting our focus to introducing a contribution model to the system and adapting the system to meet new challenges.

Shoutouts

Huge thank you to Danielle, Manjia, and Amy for the illustrations. Check out their amazing work on our Dribbble page: https://dribbble.com/usertesting

Thank you to Stephanie Kong and Jennifer DeRome for proof reading and editing these articles.

To the whole design team: Dwiti, Yao, Maura, Kien, Jorge, and Ankit for their continued support and incorporating Connect into their workflows.

And to Scott and Emily for the long days and nights to get Connect out, this wouldn’t of been possible without you two!

Any questions, suggestions, or want to nerd out on design systems?

Tweet me: twitter.com/darrendub
Slack me: design-systems.slack.com
Connect: http://toolkit.usertesting.com/


UserTesting Design

Thoughts, stories, and learnings from the Design Team at UserTesting

Darren Wong

Written by

Design @UserTesting

UserTesting Design

Thoughts, stories, and learnings from the Design Team at UserTesting

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade