TrustYou Brew

From component libraries and styleguides to comprehensive patterns and design systems, we’ve come a long way in pushing UI consistency across the web, and for good reason. Consistency is not only key to a good user experience (e.g. by reducing cognitive load) but it also helps us as creators to build things faster and better. That’s why ever since I joined TrustYou in early 2014 I’ve been so focused on establishing and maintaining a high standard for consistent UI design.

Background

When I joined the team most features were either built entirely from scratch or by mixing together different UI libraries such as Bootstrap or jQuery UI, and without any design direction in place this quickly led to plenty of design debt. In an effort to address this debt I started an inventory of components and styles, documenting and then gradually standardizing them into what would later become TrustYou UI, our living styleguide.

Atomic design

Because I was still coding my own designs at the time I kind of naturally ended up also coding our styleguide using Sass and Pug. This not only made handover to developers seamless using Git (via Bitbucket) but it also allowed for more rapid prototyping directly in the code.

By working closely with developers, I then also introduced Sass throughout our codebase and used atomic design principles to split components into their fundamental building blocks. Things like color, typography and spacing were stored as variables, and the SMACSS methodology acted as scaffolding for a more structured and scalable way of building interfaces.

Organized chaos

This flow worked well when we were just a couple of designers, but as the team grew and I transitioned into a leadership role it became increasingly difficult to maintain that styleguide format, especially as it required coding knowledge. At the same time, the adoption of React and styled components by our developers had anyway made our CSS obsolete, so my team eventually moved away from writing CSS in favor of what was the de facto design toolkit at the time: Sketch + Invision + Zeplin.

We began migrating components from styleguide to Sketch in a shared library file, using Invision for prototyping and Zeplin for developer handover. In an attempt to establish a new knowledge base we also turned to DSM for documentation but quickly found that it just wasn’t flexible enough for our needs. We were on the right track with the rest of our toolkit but still needed a hub where we could bring it all together, we still needed that so-called “single source of truth”.

By this point components had only been partially migrated to Sketch, documentation was scaterred across multiple platforms (e.g. styleguide, DSM, Storybook) and there was no clear process in place for design and development to collaborate on this. If we were going to make any progress we had to first take a step back, regroup, and approach things from a different angle.

Groundwork: planning, direction & team

Realizing that this was more than just a side project and that my team alone didn’t have the capacity to see it though, I roped in engineering leaders and product managers and started penciling a long term plan for us to finally establish a stable design system.

Creating a component inventory

Before we could go anywhere we had to first figure out where we were, so to get a better picture of the state of our UI design I created a Confluence page with an exhaustive list of all our UI components and their different stages of design, development and documentation.

This list was helpful not only in exposing the status quo of our interfaces, but it also served as a living document throughout that year as we kept track of cross-team efforts.

Getting support from stakeholders

Even though the need for a design system may have been obvious to the design team, we still had to make the case that this wasn’t just a nice-to-have but an actual cross-team necessity.

“When agencies suggest a design system to clients, the top reasons mirror what motivated in-house teams to consider a design system: consistency, the ability to reuse code, and greater efficiency in their work.”

—Sparkbox 2019 Design System Survey

The component inventory made it abundantly clear just how fragmented our UI library really was, especially when contrasted against other companies that had well established design systems already in place (e.g. Shopify, IBM, Atlassian, Salesforce, Uber). If we were to become more efficient and autonomous then we also needed to use a common design language. This would not only speed up our process and improve the quality and consistency of our products, but in the long run it would ultimately also reduce time to market.

Forming the team

Having the buy-in from product and engineering managers, we took this back to our front-end chapter and openly discussed it in a multi-disciplinary group of designers, engineers and leaders. As outlined by Jina Anne in the Design Systems Handbook, to build an effective design system several disciplines should be represented in the team:

• Designers to define the visual elements of the system
• Front-end developers to create modular, efficient code
• Content strategists who can help the team nail the voice and tone of the system
• Product managers to ensure the system is aligned with customer needs
• Leaders (VPs and directors) to champion and align the vision throughout the company, including up to executive leadership
• Accessibility experts to ensure your system conforms to standards like WCAG
• Researchers who can help you understand customer needs
• Performance experts who can ensure your system loads quickly on all devices

For small teams such as ours designers will often have T-shaped skills that cover several of these roles, making the team more nimble and allowing for faster decision making. That was definitely the case in terms of how we managed our design system, especially when looking at the team models that Nathan Curtis defined in his comprehensive article:

1. Solitary: “One team make a system available, but with efforts focused primarily on that team’s needs.”
2. Centralized: “A single, central design team produces and supports a system used by others as a part of their job.”
3. Federated: “Designers from multiple product teams decide on the system together.”

Our approach was more hybrid and similar to what Salesforce called the cyclical model. Even though as product designers we were the primary curators of the design system (i.e. federated model), every other week one of us would pair up with a front-end developer to also host our regular front-end chapter meeting and to coordinate design and development efforts. This enabled us to reduce the load on one single team or individual by sharing responsibilities.

Defining requirements

As we knew from product design, simply building something didn’t guarantee adoption, so if our design system was going to be at all successful then it had to first and foremost address the needs of its users. In our case these were primarily designers and developers, and much like in the 2019 survey conducted by Sparkbox we each had clear needs.

These didn’t come as a surprise, being in fact consistent with our own internally conducted research. They did however make it clear that before we could build anything we first needed a solid foundation of color, typography and spacing, as well as a restructuring of our design files.

Making time instead of finding time

Even though we had the buy-in and the expertise, capacity was already stretched thin so we didn’t really have the resources to focus on just this single project. Fortunately around that time our engineering teams were experimenting with objectives and key results (OKRs) so I proposed that we also tried it out in our design team. We broke the effort down into quarterly milestones and used tools like Koan to keep track of our progress on a weekly basis, making the entire process completely transparent not only to management but also to other teams as well.

With support from product managers and engineering leadership, other (development) teams also started defining their own design system related OKRs and soon enough we were all making steady progress towards that common design language.

Migration: styles, colors & components

As excited as we were to kick things off, we knew that we didn’t have the luxury of starting with a clean slate and that there would be plenty of clean-up work to be done, as made evident by our very lengthy component inventory.

Divide et impera

One of the first items on our agenda was to split our old Sketch library into smaller files for color, typography and spacing. With each designer responsible for one foundational library we made faster progress by working in parallel without stepping on each other’s toes.

Once these were ready we began gradually migrating components from their original Sketch file into a new library, using the newly established colors, typography and spacing. Apart from the actual variations supported by each component we also created anatomy artboards to showcase the building blocks that each component was made of.

These artboards would eventually be published to Invision and from there they would be embedded into our documentation platform. This way any changes made in Sketch could be easily pushed to Invision via Craft Manager and would be automatically reflected in our docs.

Workflow & design ops

Because there was no support in Sketch for real-time collaboration, we ended up creating personalized work-in-progress (WIP) files that we tracked in Git via Bitbucket. As soon as a component was updated we pushed those file changes to Git and a Slack notification would trigger in our design channel, notifying the team that something was ready for review.

As soon as the other designers signed off on the new component (e.g. by commenting on the linked Jira ticket), it was moved from its WIP file to a new page in our main component library and all relevant assets were then be pushed to Invision and Zeplin, triggering similar Slack notifications in our design system channel to keep the developers in the loop.

Working in such a multi-disciplinary team made it even more important for everyone to stay in sync, so we created a dedicated Confluence page along with a Jira project explicitly for our design system. This enabled us to aggregate tickets from different teams into design system (DS) epics that were tracked in a Kanban board.

Apart from keeping everything centralized and transparent, we also used this board to kick-off every front-end chapter meeting by reviewing tickets and openly discussing any blockers.

What’s more, because we also had our own design project in Jira and were using Git on design files, tagging commits with the ticket number made it very easy to track progress on any given component, from design to development.

Documentation: content, structure & platform

What we were building was more than just a component library and with so many touch points across design, development and marketing, we needed to have a central hub where we could bring it all together, we needed a well structured and easily accessible documentation.

Inspiration from market leaders

With so many mature design systems already out there we were never short of inspiration when it came to organizing and documenting our own:

We learned a lot from all of these, but one was particularly interesting because it really walked the line between modest and comprehensive, and that was Orbit by Kiwi.com. As opposed to Material Design, or Lightning, or Polaris, this one actually seemed reasonably doable to us.

Finding the right name

Much like with these other design systems we also wanted to name ours so that we can reference it easier in refinement meetings, ticket specs, code reviews and conversations in general. We didn’t just want a generic name either, we wanted one that was meaningful and professional, but also catchy and easy to remember.

“There are only two hard things in Computer Science: cache invalidation and naming things.”

— Phil Karlton

Naming things is always tricky so we made the decision in the most designer-way possible: we each came up with a proposal and ran a preference test with our front-end chapter colleagues.

The winner was TrustYou Brew by a landslide and funny enough, people were quick to assume that it was my proposal because of my brewing side project when in fact it was the brainchild of my colleague Laura Agudelo who said that a design system is ultimately just a mixture of elements brewed together by an interdisciplinary team.

Not only was this name spot on but it also played well with the fact that we established it at our headquarters in Munich, Germany, the capital city of Bavaria and a place with a long standing history of brewing according to well established standards.

Choosing a documentation platform

When it came to hosting our documentation, we pretty much knew what we wanted after having our own highly custom styleguide and then trying out the very rigid Invision DSM:

• Distribution: should be openable in the browser by anyone in or outside the organization.
• Permissions: should allow granular rights for accessing, editing, commenting, or sharing.
• Deep linking: should be able to open a specific page or section just via URL.
• Structure: should be able to organize content in custom structures and layouts.
• Code friendliness: should support formatting for different programming languages.
• Cost: should be affordable enough even for small teams such as our own.
• Low maintenance: should be easy to update and simple to use out of the box.
• Integrations: should support embedding dynamic content from external sources (e.g. Invision, Storybook, Codepen).

These requirements served as criteria for evaluating the other tools in our shortlist: Sketch Cloud, Zeplin, Confluence (which was already used company-wide) and Notion (which was suggested by a colleague during one of our front-end chapter meetings).

It didn’t take long until we realized just how far ahead Notion was from all the rest, and even by just playing around a bit I was able to quickly put together a proof of concept documentation. With its clean design and intuitive interface, Notion was flexible enough to give us what we needed while still being rigid enough to maintain consistency and structure.

Content is king, context is queen

Probably one of the most commonly heard phrases is that “nobody reads the docs”, but interestingly enough this often comes from people that do value a solid documentation, they just don’t want the hassle of having to create or maintain one themselves. In my opinion that’s just an excuse for not putting in the work, because a documentation doesn’t have to cover absolutely every single aspect for it to be useful, it just needs to cover enough so that it’s reliable in the right context, be it during a design handover or while onboarding new team members.

Another way to look at it is not as an exhaustive encyclopedia, but instead as a collection of design decisions that we have made as a team for handling certain scenarios. Why have the same discussions over and over when we could just document our decisions?

Structuring the content

With the overwhelming amount of information that could be covered by a design system it was easy to get lost in the details, which is why I always encouraged my team to work with what we knew and to take things one step at a time.

We started off with foundational elements like color, typography and spacing, then switched to icons, elevation and overlays, gradually working our way towards more complex components and ultimately towards topics like layout, loading screens, error states and more.

When it came to just how much could be achieved with Notion there was probably no better playground than the component page. Inline gallery databases allowed us to showcase variations, embedded blocks allowed us to pull dynamic artboards from Invision and deep-links allowed us to reference any page anywhere, just to name but a few effective features.

Notion allowed us to easily organize and reorganize all this content as many times as needed until we finally had a formula that worked, and pages that were still in progress were marked with an asterisk (*) so that people knew they were still subject to change.

Once everything was in place, TrustYou Brew became an integral part of our process and every (re)design that we worked on quickly turned into an opportunity to modernize and standardize even more of our interface, increasing the coverage of our design system and getting us ever closer to that “single source of truth”.

Conclusion

Such a project is of course never over because a design system is an ever evolving entity, but I’m nonetheless thankful that my team and I were able to establish these standards and practices that will hopefully continue to improve the TrustYou products for years to come.

Return on investment

Finding time to work on something like this was never easy because building things properly takes time and that slows down both design and development. This however was a perfect example of spending time now to save time later because once things were in place our teams’ efficiency increased massively.

Even though we didn’t have concrete ways to measure the impact of our design system, the return on investment (ROI) was made evident when the same features that took us nearly a quarter to build from scratch ended up getting done in just a matter of days, and in much more consistent and scalable ways.

Room for improvement

Looking back I think that we did the best we could with the tools and expertise we had, but as things settled down my team and I started noticing that despite our more integrated UI we were still switching between many tools for design, prototyping, asset handover and version control.

Looking forward I think that our next biggest improvement would be to have a less fragmented toolkit. In fact that is exactly why we even started a Figma trial to see if it could cover several of our design needs as an end-to-end solution, just as Notion had covered our documentation needs.

Whatever the tools we use, it’s important to remember that at the end of the day they are just a means to an end and will only be as good as the people using them. That’s why I’m grateful to have worked on this project with such talented, knowledgeable and all-round great people.