InVision presents

Design Systems Handbook


by Marco Suarez, Jina Anne, Katie Sylor-Miller, Diana Mounter, and Roy Stanfield

A design system unites product teams around a common visual language. It reduces design debt, accelerates the design process, and builds bridges between teams working in concert to bring products to life. Learn how you can create your design system and help your team improve product quality while reducing design debt.


Go to Chapter
Introducing design systems
The power of scale
Repetition and reusability make scale possible. InVision’s Marco Suarez takes you back to the foundations of component-based design and the many ways design systems enable scaling. He also addresses a few common misconceptions about design systems.
 
Go to Chapter
Go to Chapter
Designing your design system
Step by step

Starting can be the hardest step. Design systems expert Jina Anne walks through what to consider as you start out. Involve the right people, find the right model, add the right pieces—and you’ll be well on your way to establishing a successful design system.

 
 
 
 
Go to Chapter
Go to Chapter
Building your design system
A strong foundation

Building a flexible, maintainable, stable, scalable design system creates a strong base for your product design team. Etsy’s Katie Sylor-Miller shares foundational knowledge learned building design systems across cross-functional teams.

 
Go to Chapter
Go to Chapter
Putting your design system into practice
Better together

Encouraging adoption of your design system forges connections and creates champions across teams. GitHub’s Diana Mounter lays out practical strategies for sharing design systems and growing adoption, including examples from her experience.

 
 
Go to Chapter
Go to Chapter
Expanding your design system
More than the sum of its parts

Components form the core of a design system, but teams can align around much more than components. Marco Suarez outlines how teams can round out their systems with vision statements, design principles, voice and tone guides, and more.

 
Go to Chapter
Go to Chapter
The future of design systems
To infinity and beyond
Design systems play a huge role in shaping our present, but we may only be scratching the surface. Airbnb’s Roy Stanfield explores a bold future of intelligent, adaptive, context-aware systems that could further accelerate design’s possibilities.
Go to Chapter
Go to Chapter
Appendix
More resources
Design systems continue to evolve, and every company’s system can offer something to our collective knowledge and understanding. We’ve curated a list of publicly available design systems and resources to help you continue your exploration. 
Go to Chapter
02

Designing your design system

Step by step


by Jina Anne

Starting a design system can feel daunting. There are so many things to consider: the design style, how to design for modularity and scalability, how it will be used by other teams, how to sell the idea to the decision makers in the company. Where is a designer to start?

Big problems are always more manageable when broken into smaller pieces. Before diving into the design process, start by considering who needs to be involved in the creation of your design system and how the team will work together. Once you’ve got the right people assembled, you’re ready to start thinking about the design language of the system, which will include color, typography, spacing, and more. Your visual design language will be the foundation of your UI library—a series of components that can be quickly assembled to create an interface.

Let’s take a step-by-step look at how you can start designing your design system.

Who should be involved

Rachel Cohen, Jessica Clark, and David Carmona from LinkedIn's Art Deco Design System team discuss how the system was formed, rolled out, and governed.

Before beginning work on your design system, take a moment to think about the team you’ll need to bring it to life. Who needs to be involved? Spoiler alert! You’re going to need more than just designers.

Here’s a quick list of the disciplines that can be represented in your team to create an effective design system:

  • Designers to define the visual elements of the system
  • Front-end developers to create modular, efficient code
  • Accessibility experts to ensure your system conforms to standards like WCAG
  • Content strategists who can help the team nail the voice and tone of the system
  • Researchers who can help you understand customer needs
  • Performance experts who can ensure your system loads quickly on all devices
  • 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

Once you’ve got the right skillsets represented in the design systems team, identify leaders to represent each area. These people should be able to drive decisions forward. Know who on the team can advocate for each of the areas of the design system.

With a team of experts guided by strong leadership, your next task is to establish the right team model to help you achieve your goals.

Choosing the right team model

The team model that brings people together is as important as the team creating the design system. In “Team Models for Scaling a Design System,” design systems veteran Nathan Curtis outlines 3 popular team models used by many companies.

The solitary model: an “overlord” rules the design system.

The centralized team model: a single team maintains the design system as their full-time job.

The federated model: team members from across the company come together to work on the system.

There are strengths and weaknesses in each of the above models. A solitary model is fast and scrappy, but with 1 person in charge of so much, the “overlord” can become a bottleneck to the completion of many tasks. A centralized team, on the other hand, keeps the system well maintained, but the group may not be as connected to the customers’ needs as they may be less involved in user research. Finally, a federated team has great insight into what’s needed for all the product features and user needs, but this group can be quite busy working on those areas outside of building the system.

Many teams are moving away from the solitary model to the centralized or federated model. As Curtis mentions in his article, overlords don’t scale. The centralized or federated models are usually much better for scaling a design system.

I wrote about the Salesforce team model in response to Curtis’s piece. When I was at Salesforce on the Lightning Design System team, we used a combination of the centralized and federated models. In an enterprise organization as big as Salesforce, a centralized design systems team was not enough on its own. With so many key players involved and the amount of ground we had to cover across products and platforms, we needed a more sustainable approach.

Though the Lightning Design System has a core team, there are also core contributors from many of the product and feature areas in the Salesforce ecosystem who act as a federation of practitioners, surfacing new ideas and making requests for the design system to evolve. Researchers, accessibility specialists, lead product designers, prototypers, and UX engineers work with the central design system team to both consume and help establish the patterns, components, and the overall design system. Engineers refine all code to make sure the system is performant and production ready.

Though the solitary model is less popular in most teams because the primary contributor can become a bottleneck, there are situations where it can work quite well. In the midst of a political campaign moving at breakneck speeds, Mina Markham had little time to bring in reinforcements as she developed new online assets for Hillary Clinton. She created a design system called Pantsuit to help many teams in many locations expedite design and production while maintaining consistency in the campaign brand. The solitary model let Markham focus on speed first and longevity second, which is a different tract than a typical enterprise might take.

As you determine what team model works for you, consider your goals. If you want to move fast, the solitary method is ideal initially, though some work may need to be done later to fully adopt it across other teams. If you want to move fast, but want to encourage buy-in from the start, consider the centralized team model. And to get the most buy-in and shared ownership, the federated model is a good option. In any case, remember that a design system is a product, so staff it like a product instead of a project; you want people committed to maintaining and evolving it.

With the team and the model that organizes them established, it’s time to start your design system just as you would any new product—by talking to your customers.

Interviewing customers

As with any product design process, it’s important to do your research. Who will be using your design system and how will they use it? Your design system will get used much more often if you create it to fit into the workflow of other teams. By interviewing users, you can pinpoint problems ahead of time, define principles that will help others use the system properly, and focus your energies on the most important things.

A less common group of people to interview are members of your open source community. This exists more likely in organizations that provide developer tools for customer and partner communities. If you plan to open source your design system—a potentially bigger project—then you’ll need to speak with potential contributors and consumers to discover what use cases your design system will need to satisfy.

And then there are the executives, leaders, and management. It is important to get their thoughts as well. You will need their buy-in to support and fund the system. Listen to their concerns and use them as actionable goals and metrics to achieve. Examples of requests might be shipping features faster, better performance, and improved UI quality.

With insights in hand from customer interviews, it’s time to take an inventory. There are 2 types of interface inventories to be created:

  • An inventory of the visual attributes (such as spacing, color, and typography), which will help create a codified visual language
  • An inventory of each UI element (such as buttons, cards, and modals), which will help create a UI library of components

Let’s first focus on a global visual inventory.

Creating a visual inventory

Of course, if you’re starting a design system for a product that doesn’t yet exist, you can skip this step and jump straight to creating a visual language for your new product. Lucky you!

Conducting a visual audit

As we start to take inventory, it’s good practice to take a look at the CSS used to create all of those elements you just captured in your visual inventory. Use a tool like CSS Stats to see how many rules, selectors, declarations, and properties you have in your style sheets. More relevant, it will show you how many unique colors, font sizes, and font families you have. It also shows a bar chart for the number of spacing and sizing values. This is a great way to see where you can merge or remove values.

If you’re creating an inventory in Sketch, use the Sketch-Style-Inventory plugin to aggregate all colors, text styles, and symbols. It also gives you the ability to merge similar styles.

Creating a visual design language

I must admit, as an art school graduate the visual design language in a design system is my favorite part to work on. I love thinking about color theory, typography, and layout, which are at the core of any design system.

If we break apart each component of a design system we find that these fundamental elements make up its visual design language:

  • Colors
  • Typography (size, leading, typefaces, and so on)
  • Spacing (margins, paddings, positioning coordinates, border spacing)
  • Images (icons, illustrations)

Depending on your needs, you may also include the following to further standardize the user experience:

  • Visual form (depth, elevation, shadows, rounded corners, texture)
  • Motion
  • Sound

Consider the role each of these design elements plays in a simple component like a button. A button typically has a background color, typography for the label, and spacing inside it. There may be an icon next to the label to create a visual cue. A border on the edge serves as simple ornamentation and may even round the corners. Finally, hovering over or clicking the button could trigger animation or sound as feedback to the user. Though a button may seem simple, there are many design decisions required to bring it to life.

Design tokens

Before we dive into visual design standards, I want to discuss design tokens. Design tokens are the “subatomic” foundation of a design system implementation. At its simplest, they’re name and value pairs stored as data to abstract the design properties you want to manage. With the values for all design tokens stored in a single place, it’s easier to achieve consistency while reducing the burden of managing your design system.

Example:

SPACING_MEDIUM: 1rem

In design tokens you can store colors, spacing, sizing, animation durations, etc., and distribute them to various platforms.

We’ll look more closely at design tokens in Chapter 3.

Color

The colors you choose for your design system are more than just an extension of your brand. A UI uses color to convey:

  • Feedback: Error and success states
  • Information: Charts, graphs, and wayfinding elements
  • Hierarchy: Showing structured order through color and typography

Common colors in a design system include 1–3 primaries that represent your brand. If none of these work well as a link and button color, then you may have an extra color for that as well. It’s a good idea to use the same color for links and button backgrounds as it makes it easier for users to recognize interactive elements.

You’ll likely have neutrals for general UI backgrounds and borders—usually grays. And finally, you’ll have colors for states such as error, warning, and success. Group these colors to see how well they work together and refine as needed.

Larger design systems sometimes include colors for objects and products. For example, at Salesforce we had a color for contacts, for sales deals, or groups, and so on. We also had them for products: Sales Cloud, Marketing Cloud, Analytics Cloud, etc. Color can be a helpful wayfinding tool for your users.

Using color for wayfinding can be tricky to do while maintaining accessibility, as people who are color blind may not be able to discern some differences.

Depending on how strict you want to be with your palette, you may want to include a range of tints—a color mixed with white—and shades—a color mixed with black. Sometimes you may use other colors instead of white or black to avoid muddiness, such as an orange to darken a yellow so it doesn’t appear brown.

These color variations allow designers to have choices. But be warned, having too many choices can lead to major design inconsistencies. Keep your inclusion of tints, shades, and neutral palettes slim to prevent misuse of the system while still giving designers the flexibility they need. You can always add more colors as you find the need.

Typography

Fonts and weights

The fonts you choose have a high impact on both your brand and your user experience. Keep legibility in mind as you select the right fonts for your system. Keeping to common system fonts like Helvetica, Times New Roman, or Verdana can be a great shortcut, as they are familiar to the user’s eye. Some companies prefer custom web fonts to better reflect their brand, but pay special attention to how you use them as performance can be affected.

Most design systems I’ve worked on include just 2 typefaces: 1 font for both headings and body copy, and a monospace font for code. Sometimes there’s an additional font for headings that compliments the body font. Most design systems do not have a need for more, unless you have a system that supports multiple brands. It’s best to keep the number low as it’s not only a best practice of typographic design, it also prevents performance issues caused by excessive use of web fonts.

These days it’s trendy to use a font at a very thin weight, but be aware that legibility can become an issue. If you want to use light or thin weights, only use them at larger text sizes.

Type scale

When selecting the size to set your type, consider the legibility of the font you’ve chosen. In most cases, a 16px font size works well. It’s the default font size in most browsers, and it’s quite easy to read for most people. I like using 16px as it works with the 4-based metrics used by Apple and Google (and is gaining traction as the standard approach). I recommend this as your baseline, though I would use it in a relative format like 1rem for CSS-based systems.

You can use a modular scale for larger or smaller font sizes for other elements such as headings. A modular scale is a set of numbers in which you have 1 base number, and a ratio to generate the next number. You keep applying the ratio to the new number to get yet another number.

As you design your type treatments, be sure to give thought to how it will respond to various screen sizes to maintain legibility. You won’t want your headings to be too large for mobile devices. And for much larger displays, you have the room to bump up sizes.

A common method is to enlarge headings on larger viewports. You can also use viewport units to scale your type based on a percentage of your screen size.

Leading

Leading, or line-height in CSS, can improve readability and aesthetics of your typography. While the best line-height can vary depending on the font face and the line length, a general rule of thumb is to have leading at around 1.4–1.5x the font-size. 1.5 is recommended by the W3C Web Accessibility Initiative.

It also makes your math more predictable, but you don’t have to calculate it. You can define your line-height without a unit of measurement and the browser will do all the hard math for you.

For headings, tighten it up depending on your typeface. In most cases, I find a 1.25 or 1.125 ratio works quite well.

Spacing and sizing

The system you use for spacing and sizing looks best when you have rhythm and balance. This means using numbers based on patterns and proportions. Using a consistent spacing scale also promotes maintainability through ratios by making layouts more predictable and more likely to “fit” and align well.

When I designed an Android app, I studied Google’s design guidelines. I noticed a pattern of using 8dp between elements and 16dp for outer gutters. It broke me out of using a 10-based scale I was accustomed to, as I found that 4-based worked so much better.

A 4-based scale is growing in popularity as the recommended scale for many reasons. Both iOS and Android use and recommend metrics that are divisible by or multiples of 4. Standard ICO size formats (which are used by most operating systems) for icons tended be 4-based (16, 24, 32, etc.) so that they scaled more easily. The browser’s default font size is usually 16. When everything is using this system, things are more likely to fit in place and line up. And finally, responsive math works out well.

For horizontal spacing, an 8-based scale works quite well. You can make margins and padding equal or in proportion to the font size. But for vertical spacing, I tend to use a 12-based system. This is due to the line-height I get of 1.5 (with the default font size of 16px) getting us to 24.

Occasionally, you may have to break this rule. If you’ve added a 1px border to something, this border can throw off alignment by a hair. So you might find yourself using a padding or margin that subtracts that amount. This is something that you do on a case-by-case basis.

You probably want elements to grow and shrink with the content. For general sizing, avoid setting widths and heights unless totally necessary. You can achieve responsive design much easier if you let elements flow to fill the space they’re given in the layout.

Images

File formats

For icons and illustrations, I find using a vector format (SVG) works best for scalability and responsive design. However, if you find yourself needing to use photography, you may need to use a rasterized image format like JPG or PNG.

For most photos, illustrations, and diagrams, you can allow the image to go 100% to the container or viewport and let the height automatically set itself by not defining it. This works best for responsive layouts. You may also want to define some preset widths for images if you don’t want it to go full width (for example, half-width, a third, or a fourth). I recommend setting these as max-widths so that the image can rescale for smaller screens.

Iconography

Before drawing your icons, come up with your guidelines around them first. Will they be filled or outline? What is the line weight? Will they use more than 1 color? What sizes will they be? Is there an icon art boundary set inside an outer boundary?

You may have different styles for different icon types. For example, utility and action icons (like a notifications bell or a settings cog icon) may be solid and 1 color, while navigation icons may be multicolored and more creative. Clear guidelines will keep your icons unified.

Illustrations

Illustrations are a great way to add some character to your product. You can use these for empty states, loading screens, modals, and other components that invite visual interest. Shopify went to great lengths to produce unique illustrations for all of the empty states of their platform, which conveyed a strong sense of brand personality (figure 19).

Similar to icons, it’s helpful to have guidelines for the style of your illustrations (figure 20).

Visual form

Visual form, or the material quality of your UI, is about the background images, gradients, and textures, shadows and elevation (z-indexes), rounded corners, and borders. These are visual qualities that help emphasize and decorate elements to add visual hierarchy and aesthetics. In any case, all are examples of ornamentation that need to be standardized.

Google does a great job indicating how depth and elevation work with layering of components (figure 21).

Motion and sound

When you define your visual language, motion and sound might not immediately come to mind. You experience these in a different way. But motion and sound can have a high impact on the experience of your app. You’ll want to have that systemized as well for consistency. I personally haven’t explored these areas as much as I’d like to admit, but there are some great examples in the wild.

Creating a user interface library

Before we conducted a visual inventory, which looked at the visual qualities of elements, such as color, spacing, and typography. Now, we will conduct a UI inventory, in which we look at the actual pieces of UI—like buttons, cards, lists, forms, and more. Where visual language is all about the visual approach and how things look on a global visual level, a user interface library (otherwise known as a pattern library) looks at actual components of a UI.

Let’s take a look at each of these design elements and the role they’ll play in your design system. Take stock of all interface elements in production to see just how much design debt you need to address and what elements are most commonly used. Warning! This can get a bit depressing, as most companies have an intense amount of inconsistency in their UIs.

To create an interface inventory simply open all products in production at your organization, screenshot all buttons, forms, various type styles, images, and collect them in a slide deck or on big posters where the whole team can see.

You can do this with cut out print-outs or through screenshots. Gather the folks you’re involving (as mentioned earlier in this chapter). Have them conduct this inventory with you, either through a shared presentation or via a hands-on activity. The idea is to gather the different components you’re using and categorize and merge them.

Some like dividing the pieces into elements, components, regions, utilities, and so on. Atomic Design is a great example of this line of thinking, which is a great conceptual model. But when it comes down to it, everything is pretty much a component, so at the end of the day, you could label all as such. But in general, what I see most design systems break things down into are:

  • elements (or basics, or atoms)—these are small, stand-alone components like buttons and icons
  • components (or molecules, or modules)—these are usually an assembly of small components into a larger component like a search form (which includes a form input, a button, and potentially even a search icon)
  • regions (or zones, or organisms)—these are an area of the UI like a left-hand navigation
  • layouts—how the pieces are laid out on the page (like a header region, followed by a sidebar and main content area, followed by a footer)

After you complete the inventory, you can merge and remove what you don’t need (either in a spreadsheet or even directly in a code refactor if you want more immediate change). Also, document what the component is and when to use it. This will become your UI library (or pattern library, or component library, depending on what your organization chooses to call it.).

Most design system documentation includes the component’s name, description, example, and code. Others may show meta data, release histories, examples, and more. What matters most is that you show what’s necessary for your team to get your work done.

Conclusion

Creating a design system not only helps your team produce more consistent user experiences, it also builds bridges between design and development. By creating a common visual language codified through design tokens, and a set of components and patterns cataloged in a UI library, you’ll vastly improve designer/developer communication. You’ll also have fine-tuned control of the UI in a way that is manageable, scalable, and robust.

04

Putting your design system into practice

Better together


by Diana Mounter

How you develop your design system will influence how you share and encourage adoption of the system. Broadly speaking, there are 2 general approaches to developing and rolling out a new design system: incremental and large-scale redesigns.

In this chapter, we’ll walk through the 2 approaches, highlight the pros and cons of each, and discuss adoption strategies.

Tina Koyama, Ashlie Ford, and Devon Beard discuss Twitter's approach to building and rolling out their Horizon Design System.

Large-scale redesign

When a team takes this approach, it often means they spend more time designing the system before rolling it out everywhere, including doing a visual refresh or consolidation of components. This allows the team to develop a fuller system—from the primitive layer of colors and typography to components, page layouts, and interaction flows.

Some teams approach their new system by creating imaginary products to help them step away from the constraints of working within a real application. Other teams design their new system alongside the redesign of a real product or feature.

Testing with pilot projects

At Etsy, I worked with a team of designers and engineers on the redesign of seller tools. This project provided a great opportunity to test a new approach to our CSS and refresh our visual styles. We built a new style guide alongside the seller tools redesign that documented implementation and design guidelines.

This became a pilot project for testing the new design system. Rebuilding a real part of the product gave us a great playground for testing new components, responsive layouts, and new typography styles.

In From Design Systems: Pilots & Scorecards, Dan Mall writes about the criteria he uses to find good candidates for design systems pilot projects. Though our approach at Etsy was more opportunistic, many of the attributes Mall lists happened to match the seller tools project:

  1. Potential for common components. Does this pilot have many components that can be reused in other products?
  2. Potential for common patterns. Does this pilot have many patterns that can be reused in other products?
  3. High-value elements. Even if uncommon, is there a component or pattern with high business value at the heart of this project? We’re talking about elements that are integral to a flow or audience with unusually high value for the organization.
  4. Technical feasibility. How simple is a technical implementation of the design system? Is a large refactor required?
  5. Available champion. Will someone working on this product see it through and celebrate/evangelize using the design system (and even contribute to it)?
  6. Scope. Is this work accomplishable in our pilot timeframe of [3–4 weeks] (insert your timing here)?
  7. Technical independence. Is the work decoupled enough from other legacy design and code that there are clear start and end points?
  8. Marketing potential. Will this work excite others to use the design system?

There was one downside to building the new design system alongside a product—it ended up being biased to the needs of that product. Afterward, it needed further development to work for the whole Etsy application. Working in a silo with minimal outside feedback allowed us to make progress quickly, but meant that we had to work harder to encourage other teams to adopt the design system.

Showing value through a sandbox environment

While working on the new Etsy style guide, we set up a simple sandbox environment that allowed us to quickly prototype HTML/CSS mockups. As we prepared to share the new style guide with other designers, we realized the sandbox could be helpful with adoption.

One of our goals was to reduce the time designers and developers had to spend writing CSS, so they could spend more time iterating on designs. The new approach we took with CSS, combined with the sandbox environment, made prototyping designs in the browser fast and easy.

The best way for people to see value is to experience it.

We set everyone up with sandboxes for training. This approach empowered people to prototype and experiment with the style guide using the sandbox, revealing value through hands-on use.

To set people up for success, we wrote tutorials teaching them how to apply different styles—such as atomic vs. component classes, build mobile-first responsive layouts, and create complex views such as a search results page—without writing CSS. To help people understand the why behind our decisions, we included a presentation on our design principles with example scenarios, code samples, and live coding demos.

The sandbox’s CSS environment mirrored production, so a designer’s prototypes easily translated to a developer’s production work, avoiding costly and unnecessary new CSS. Since code prototypes are written in the same language, they gave developers a better sense of the intent than a static mockup. Developers didn’t have to translate like they do with comps from design tools. This further helped with adoption. A design system that both designers and developers love has a greater chance of success.

Documentation is key

Another key to adoption is up-to-date documentation. As design systems peers say, “If it’s not documented, it doesn’t exist.”

When styles go undocumented you run the risk of people writing new but duplicate code. Documentation becomes more important when introducing a new design system because old patterns can outweigh new ones. Documentation helps promote those new patterns, reduce the need to write new code, and makes implementation easy with code examples and guidelines.

Outdated documentation can cause damage too since it can lead people down the wrong path and cause frustration. It’s worth investing time in developing practices that help you keep updated documentation.

Find opportunities to check documentation accuracy—such as before and after an onboarding session, or as you add new styles. Writing docs on the fly helps you test your code and avoid building documentation debt. If you can, add tests that check documentation when patterns are added and updated, and try to make it easy for people to report inaccuracies.

At Etsy, some engineering teams created onboarding projects for new engineers. This usually involved building a small feature from the backlog that would help them get familiar with the engineering stack. I was stoked to see them implementing UI layouts without help from designers, just by following style guide documentation.

Post-rollout follow-up

Design systems are never done. The launch of your new system should be thought of as version 1.0, with many iterations will follow.

Whether you form a full-time team to evolve and maintain your system or not, you likely have a few groups of people interacting with it—makers of the system, users of the system, and users who also contribute to the system. Whatever form your team takes, makers need to stay in touch with the needs of users and the organization.

A few months after rolling out the new design system at Etsy, we ran working sessions with staff from a cross-section of teams. Our goal was to learn how to improve the experience for people using and contributing to the system, how successful we’d been with promoting the system, and where it was lacking. We took a qualitative research approach so that we could be open to discovering things we didn’t realize were problems—this meant a lot of face-to-face discussions with light agenda’s to stimulate conversation.

Contributors

We ran a user-journey mapping workshop with first-time contributors to understand their experience. We suspected people had mixed experiences—some seemed to struggle or give up on their contribution entirely, and some had taken a really long time to add their new pattern.

Findings: We discovered how deflating the experience could be even when the contribution was successful. This led us to develop a more collaborative pairing approach and take an encouraging mindset toward code review for first-time contributors.

Engineering early adopters

We met with early adopters on product teams with a particular focus on understanding the engineering perspective. Most engineers hadn’t taken part in training sessions and had learned to use the new design system by reading the style guide.

Findings: We learned a lot about out holes in our documentation. For example, tutorials didn’t lend themselves well to engineers, utilities were useful but buried, and people felt concerned about how to use styles safely in experiments. This led us to reorganize and elevate important information up-front, improve search and navigation, add tutorials that appealed more to engineers, and provide more clarity on style usage.

Product managers

We ran a session with product managers to walk through the new system and discuss the impact of refactoring and building responsive layouts as part of feature development. Building a design system that was responsive by default was a core goal—and new for many parts of the Etsy web application.

Findings: We learned that most product managers trusted their engineering managers to guide them with impact on scope—this confirmed communication with engineers was a priority. PMs understood there might be extra work initially, but moving to the new design system would make front-end implementation easier in the future. We showed them they could scope work and make progress iteratively.

Collaboration creates investment in adoption

It might not be logistically possible to involve your entire company in design systems decisions, but some level of collaboration is worthwhile.

Before Etsy formed a dedicated design systems team, a working group made of a cross-section of designers drove the evolution of the system. This group met regularly to plan and prioritize projects, share work, and get feedback. Group members collaborated with engineers and specialists where needed, in situations like running experiments on high converting pages and measuring performance.

These collaborations spread adoption even further and resulted in design system champions across the company. People who spent time contributing to the system were invested in it and promoted it to others. Working in a silo had helped us for the short term, but extending contributions to outside the team set us up for success in the long term.

Incremental rollout

Not all design systems teams are able to take the time to develop a fully-fledged system before rolling it out. Many teams have to roll out parts of a design system at a time.

On the plus side, with an incremental rollout, teams can adopt new parts of the system as they become available, which can feel less daunting and disruptive. However, teams will also need to give more thought to communication and promotion of the system. Without a launch, there isn’t a big moment to get everyone’s attention. Instead, you need to find and create occasions to introduce people to your design system.

When I joined GitHub and began exploring how the small, then-part-time team might turn Primer into a more robust design system, I knew we weren’t able to go away for a long period of time and develop a complete system. There was a ton of work in flight, and no planned re-design or siloed feature we could use as a pilot project.

We needed to figure out the biggest pain points, reduce them to their smallest part, and roll out Primer updates incrementally.

Solve problems and win early adopters

One of the biggest pain points at GitHub was the amount of time people were spending writing CSS, particularly for things that should have been systematized, such as spacing and typography styles.

Our solution ended up being the introduction of utilities (single purpose classes, often referred to as atomic or functional classes) based on system variables. We weren’t able to start with auditing components and page layouts—we had to start small and test the foundation of the system before extending to larger parts. Adding utilities enabled us to make styles available without refactoring tons of UI. Designers and developers could start to use the primitive styles of the system as soon as we rolled them out.

Once people discovered they could use utilities instead of write new CSS, Primer started to catch speed. It solved a real problem while allowing us to test the primitive layers of the system. From there, we could start to replace and update the component layer of styles.

Improve documentation and findability

Like at Etsy, documentation was key to adoption at GitHub. Tons of widely used patterns in the GitHub codebase weren’t in Primer and thus weren’t documented.

We sorted through piles of custom CSS and created a directory in the GitHub codebase that formed a “waiting room” for patterns that should be moved into Primer. We focused a lot of effort on getting as much as possible documented, whether it was in Primer or not. We also focused on adding more layers of documentation, including describing our class naming conventions, accessibility principles, recommendations for tooling to work with our system, how to run linters, and an overview of our style organization and packages.

Just having styles documented wasn’t enough, though. We needed to prioritize the style guide navigation and search for findability.

We originally modeled the navigation to match our package organization—core, product, and marketing—prioritizing that information over the findability of searching for specific styles. The style guide also lacked search and hid styles behind several layers of navigation, forcing multiple clicks before people found what they were looking for.

I found myself acting as a human style guide search, with people pinging me to find what they were looking for rather than finding it themselves.

With research outlining people’s struggles to find styles, and the fact that we were wrestling with an aging web app we originally used for the style guide, we decided it was worth the effort to rebuild and redesign.

The new documentation site listed all our styles in the navigation, and we added a contextual search that helped people find documentation with similar keywords—such as finding “color” within utilities vs. support variables.

Getting a documentation site set up early on was important. Looking back, I don’t think it was the wrong choice to repurpose an old web app at first—it may not have been ideal, but it did what we needed. It is important to re-evaluate the quality of your documentation site over time though, to ensure it meets user needs, and is scaling with your design system as it grows.

Grow adoption through many touchpoints

When you don’t have that big moment to launch your design system, use every opportunity to share its value. You’re building systems to solve real problems and you know what your goals are—take some time to share those goals and how you plan to reach them. These details are helpful when you’re trying to show how changing something like a few lines of CSS matters.

At GitHub, we used lots of small interactions to promote Primer and the design systems team. Here are a few ways we made our piecemeal approach successful:

Creative comments in code review

We started to jump in and comment on pull requests in the GitHub app that touched CSS or design patterns we were trying to improve. This gave us an opportunity to suggest changes in line with the new design system, and point people to our documentation site so they knew it existed.

We spread the word about our team and our availability to help by adding simple comments to pull requests, such as, “Ping the design systems team,” or, “Find us in the design systems slack channel.”

Over time, people started to CC us on issues and pull requests, and we took advantage of features like Code Owners so we got automatically requested for review when someone made CSS changes.

Recently, we’ve started adding bot scripts that comment on pull requests with simple feedback. With lots of points of communication about our team and Primer, we’re growing awareness and adoption of design systems.

Show, don’t tell

We noticed when teams updated the GitHub UI, they would go to another part of the website and literally copy and paste the markup and CSS. Refactoring away old instances of patterns is our best fight against the continued reuse of old patterns. It is a long-term initiative, but we can prioritize the most popular and troublesome patterns.

Respond quickly to support requests

Most teams at GitHub have an on-call duty rotation called First Responder. It means one or more team members are on call to triage issues, respond to support requests, or provide code review.

As support requests grew for design systems, we adopted this process to help respond to people in a timely manner. Over time, we’ve iterated on the process and created a number of automated scripts that help track notification items that need attention. Responding to people quickly increases the likelihood that they react positively to our team and recommendations.

Presence and responsiveness  

Particularly early on, we made the simple effort to be available via Slack to answer questions, pair on code, or jump on a call to walk through something. It takes time away from deeper work, but allocating time to this is worth it to help win friends and champions on other teams.

Publishing and distribution at scale

Most of my recent experience working on design systems has been on large-scale web applications like Etsy and GitHub. The scale to which those systems need to be distributed and published usually requires more complex infrastructure than a small company with a small system and small team.

However, many companies intend to grow the size of their team and scale of their product over time, so understanding how to set your design system up for scalability will benefit you in the future.

Let’s walk through methods of style organization, distribution, and public vs. private documentation and code, to help you consider what’s right for you and your team.

Package management and organizing modules

Design systems should be built for change, large or small. This isn’t just important for how you code your system or use things like variables or design tokens—it’s important for how you organize modules, and version, and distribute them too.

At GitHub, we iterated on how we organize and package styles multiple times. Like Etsy, we pulled our design system out of the GitHub monorepo into its own repo. We wanted to have more control over the changes made and when those changes made it back into GitHub.com.

We also use Primer for more websites and applications beyond GitHub.com. Conference websites like git-merge.com are built with Primer, as well as community websites such as developer.GitHub.com and opensourcefriday.com.

Not all these sites need the full suite of styles we use for GitHub.com, and GitHub.com doesn’t use all the marketing-oriented styles in the core application. This led to taking a modular approach with style organization and influenced how we packaged and distributed Primer.

Versioning the entire system vs. versioning by module

Versioning the entire system means everything within the system belongs to just one version number and can only be installed in its entirety. This could be likened to browser or software versions. When you update to a new version of Google Chrome or your phone’s OS, for instance, you’re updating the whole piece of software in one go.

If you were to version your design system in the same way, it would mean everything within the design system would be updated too.

For example, you may have updated your font styles, added a new navigation component, or deprecated an old grid layout. When a user of your design system chooses to upgrade, they get all of those changes together. This still gives teams the flexibility of when to update the system, but a more granular approach can be helpful as your system scales.

Versioning individual modules means having a version number for every component or group of styles within the design system. So if you put your button component into one module and your utility styles into another, they would each have their own version number, such as primer-buttons@2.4.0 and primer-utilities@2.8.0.

You can still maintain a package that includes the entire set of the modules and version that too. For example, primer-css@9.5.0 includes primer-buttons, primer-utilities, and all the other Primer modules. So you can provide the best of both worlds—the option to use the entire system, or just use individual modules.

This modular versioning approach does require more effort for initial setup because you need to work out what to boil each module down to. For instance, should you have a module for layout utilities as well as a grid system, or combine them all into one layout module?

The benefit of this approach is that users of your design system can choose to upgrade just the bits they need. Giving teams the option to selectively update when they have the time to do it can mean they’re more likely to iteratively keep up to date—whereas the overhead of updating the entire system in one go can act as a barrier.

Versioning by package enables a design systems team to push updates more frequently without the pressure of forcing an update to the entire system.

Compared with versioning the entire system in one go, versioning by module creates more flexibility around major design systems releases, can lead to a culture of continuous development, and enable your systems team to move faster overall.

Releases, branches, and version numbers

Design system teams often have to balance competing priorities. Attending to bug fixes or other commitments has to be balanced with intensive projects requiring more research and planning, such as developing a new color system or bringing in a newly supported feature like a CSS grid.

Your publishing workflow needs to work for both the users and the maintainers of the design system. Maintainers want to have confidence in what they test and ship. Users of the system want to have clarity on status and what type of updates they’re getting.

At GitHub, we found the combination of versioning and organizing releases with Git branches gave us the right amount of flexibility in planning and shipping new design system releases.

We maintain a “dev” branch that includes work in progress and creates a new branch for each individual release. Since Git allows us to create multiple branches of the design systems code, we can work on a minor or patch release at the same time as a major release. This means we can take our time with a major release that might include breaking changes, while also shipping timely updates and bug fixes in minor and patch releases.

Versioning our system and using Semver makes this workflow possible. We can clearly point to a specific version number for each release, and know by the Semver system what type of updates are included with it, and therefore what type of testing we need to do.

Since Semver is a well-recognized standard for versioning, it helps clearly communicate to users of Primer—internally at GitHub or externally—what updates they’re getting and what type of testing they may need to do in order to use the updates.

Public vs. private

As your system and its number of users grow, you might find yourself considering whether to make your design system public to some degree. There isn’t a one-size-fits-all solution to this—it should be based on what’s right for your team. Making a system public doesn’t have to be an all-or-nothing approach, there are multiple ways of breaking down what’s public.

Many pioneering teams have created and published beautifully designed documentation, such as Material Design, Lightning Design System, and Shopify’s Polaris. We shouldn’t assume the solution that worked for these companies is right for everyone else. These are companies making a significant investment in design systems. Plus, they have the broader objective of wanting external developers to use these systems to build on their platform.

When deciding what, if anything, is made public, you should prioritize based on your company’s needs, rather than standards set by other companies.

Here are a few ways you can make your design system public:

Public documentation only

You might decide that making the source code public isn’t right for your team, but you want to make the documentation public.

Marvel’s style guide and Mailchimp’s patterns are examples of public documentation sites that don’t (yet) share their source code.

Open-source design systems

Many companies open-source their design system. This means the general public can open issues to request new features, give feedback, or let the maintainers know of bugs. Maintainers can also choose to accept contributions in the form of code or documentation changes via pull requests. If the maintainers choose, they can make the design system available for modification and reuse by adding a license.

The US Web Standards, Primer, Help Scout, and Solid are all examples of design systems open-sourced on Github.com.

Open-source the docs with your code on GitHub

You don’t necessarily have to share a crafted documentation website—you can just share documentation written in markdown format and it will be rendered and styled on GitHub. Another option is to publish the docs via GitHub pages. This can be a low-barrier way to share documentation since GitHub hosts the documentation, giving you a default public URL if you don’t add a custom domain.

Share a ZIP file to download

If you want to keep the source-code and/or the npm packages private, you could choose to share the code for your design system so it can be used by others. This might be a nice option if you don’t want to make in-progress work on your system public, or add the overhead of managing open-source contributions, but are still happy to share the code for use by others.

Projects like Lab by Compositor (a design tool for creating React components for design systems) use the Releases feature on GitHub to share release notes and a ZIP file download of the software. They also use the repo to host documentation and issues to get feedback from users.

Publish a Storybook of your UI components

Storybook has become a popular tool for design systems teams, especially for those using React, though it can also be used with Sass or CSS-based design systems too. As Brad Frost describes, Storybook is a “workshop” tool designed to output rendered examples of your styles and components, which you can use in development for testing changes. Style guide documentation is your “storefront” and includes crafted and detailed documentation with information like usage guidelines and code-style principles.

Providing rendered examples of your components, even without detailed documentation, is still very useful to users, maintainers, and would-be contributors of your design system. It provides a catalog of what’s included in your design system.

Pattern Lab (created by Brad Frost), Fractal, and React styleguidist are other tools that provide similar features to Storybook with options for documentation and code examples. All these tools can be used without sharing your design system’s source code, and give you options as to what level of documentation you share.

As you consider varying degrees of access to your system, also consider some of the reasons teams make their systems public:

No authentication barriers to sharing

Anything behind authentication, like outside VPNs or firewalls, means one more barrier to access. I know this firsthand since we have a new, in-progress documentation site for Primer that requires staff login. People frequently think the style guide had been taken down or don’t even know it exists.

Authentication also makes it difficult to give external contractors access. It’s a small barrier, but it can have a negative impact and mean people who could be using your design system documentation can’t or won’t because it’s too much hassle.

Helps with recruiting through previewing design maturity

Design systems are a popular topic in the design and front-end community right now and might be part of a prospect’s decision to choose one company over another.

Design systems can be a sign of maturity for a team, and also provide insight into what it might be like to work at that company. Especially if you’re trying to recruit directly for your design systems team, making the documentation public is an obvious way to attract people and set expectations.

Opens you up for input from the community

Making your documentation and/or your source-code public opens you up to external contributions, whether via simple feedback comments or direct contributions to code. This risks overhead, particularly if your system becomes popular, but the benefit is that you get feedback and insights from a wider range of people.

Primer is open-sourced on GitHub. We’ve been increasingly working in the open and sharing issues and pull requests so people can see how we work. We’ve noticed a gradual increase in contributions from the community and internal GitHub contributors. People generally feel proud to contribute to an open-source project that can benefit anyone.

Conclusion

There’s a lot that goes into the rollout of your design system, and much of it will extend naturally from how you decide to build your system, who you’re working with, and the best way to spread adoption inside your company.

Creating a perfect rollout strategy is less important than ensuring you’re involving the right people, being clear about your end goals and how your strategy supports those, and documenting your plan methodically through each step.

Design systems are always evolving, and the way you share and encourage adoption of new iterations will evolve along the way as well. An intentional, thoughtful strategy with room to scale will go a long way to making sure adoption is treated as a crucial part of the building process.

About the Authors

Marco Suarez
Product Designer, InVision
Katie Sylor-Miller
Staff Software Engineer, Etsy
Roy Stanfield
Design Lead, Airbnb
Diana Mounter
Design Systems Manager, GitHub
Jina Anne
Design Systems Pioneer, Independent
Design Systems Handbook
Design Systems Handbook