Design Systems at GitHub

Design systems have become core to the way we design and build at GitHub. Since 2011 GitHub designers have documented UI patterns and shared common styles. In 2012, CSS and other assets were packaged up into a Ruby Gem for use in GitHub websites — this package was named Primer. Primer continued to be used internally for years before eventually having its CSS and accompanying documentation open-sourced as Primer CSS. In 2016 the design systems team was formed with its first full-time employees. This post shares a brief history of how the team grew, what we’ve been working on, and what’s next.

Starting from grass-roots

Product designers and web designers at GitHub contribute production code and often assist in implementing their own designs. Some designers get deeper into the stack, but every product and web designer writes CSS. This means designers are primary users of Primer, our design system, and are often the first to notice when there are problems with styles or gaps in documentation.

When I started working at GitHub in late 2015, I noticed that there were many undocumented patterns, I had to write a lot of new CSS to implement designs, and that there weren’t obvious underlying systems connecting all the pieces together. I knew things could be better and I was enthusiastic about making improvements—I quickly discovered that I wasn’t the only one that felt this way. There were several folks working on efforts to improve things, but weren’t working together. With support from design leads, a group of us started to meet regularly to discuss improvements to Primer and prioritize work—this was the beginnings of the design systems team.

Showing our value

We started by tackling the highest impact problems that solved some of the biggest pain points for people implementing design.

We reduced the need for people to have to write new CSS by adding utilities for primitives like typography, color, and spacing, and by making our components easier to reuse in multiple locations; we worked on consolidating patterns by reducing code repetition and removing unnecessary design variations; we made use of previously under-utilized Sass features by defining global variables for shared systems styles; and we introduced consistent and easy-to-internalize naming conventions.

While improving the code we updated our documentation, starting with increasing the coverage for implementing patterns, followed by adding supporting documentation such as code style principles and accessibility guidelines.

Tackling our biggest pain points and working on tasks that provided high value to designers and developers at GitHub, helped us start to build recognition and show the value of design systems. By the end of 2016 we had a new internal documentation site with a lot more coverage, we had improved Primer to make it easier to prototype and implement designs without writing a ton of new CSS, and we had our first full-time design systems team members—myself and Jon Rohan.

Growing pains

As the new system got used more, requests for our attention grew, and keeping track of requests became increasingly difficult. At GitHub people will mention a team on a pull request or issue to request feedback, or to keep the team in the loop about upcoming work—this mention sends a notification to the team via GitHub or via email (depending on the users settings), and is available as a filter or search parameter. It can be hard to keep track of these notifications when there is a high volume of traffic (something the product team are trying to improve). We were frequently missing our team mentions which didn’t do much for our reputation, and it also meant we were missing opportunities to promote the new system. At a team hack-week we decided this was one of our highest priority issues to address.

We decided to set up several new processes:

1. Communicate updates more widely through team posts: we have an internal tool called “Team” which GitHub staff typically use to announce important internal updates, new feature ships, and new hires. We started using team posts to tell people about new Primer and style guide updates, to give people a heads up when we shipped large code changes, and share more information behind our decisions.
2. Make the status of styles more obvious: with the refactor of many of our styles things were constantly changing, we needed to communicate that clearly so that people knew what was safe to use. To help make status clear, we added a Changelog that gets updated with every release, and we added status labels to a modules documentation page. Similar to the status labels in Lightning Design System, ours are: stable, new release, in review, experimental, and deprecated.
3. Introduce on-call duty rotation: Most teams at GitHub have an on-call duty rotation that we call First Responder. Whoever is on call is responsible for triaging issues and responding to requests for help or code review. Having someone on call means the rest of the team can stay focused on deep work.

Scaling our impact

As Primer was used more across GitHub.com and other GitHub websites, we needed to scale our own processes so that we could be more efficient with our time and ensure people could use Primer with confidence.

Improving our release workflow

One of the biggest pain points for our team was publishing new releases of Primer. Each module (a component or set of related styles) was hosted in its own repository on GitHub and was published as its own package on npm. This made it difficult to make system-wide updates across all modules, such as updating typography variables. We struggled with broken builds which caused us and other teams using Primer lots of problems. Frequently people would forget to bump a package version, or forget to update dependency, or not understand the full impact of changes they made to the websites that used Primer. We needed a more robust publishing workflow and better checks on changes we made.

Our solution was to move all our module repositories into one monorepo, and use Lerna to help us manage version updates and publish new releases. After the initial updates, we iterated on our publish scripts using Travis CI to automatically publish alpha versions on pull requests—this means that every time someone opens a pull request or pushes up changes, they can test their changes by installing the alpha release in their project. This is helpful for testing changes in GitHub.com before shipping the new release.

Getting robots to do the work

We noticed over time there were common patterns with the feedback we gave in code review—we were repeating the same feedback for things like using variables or utilities rather than writing new CSS. We wrote a script for a bot that automatically comments on pull requests for us, this comment tells the pull request author how to fix their changes and provides a link to documentation in the style guide. This saves us time with code review and helps more people learn about our design system.

We continue to look out for repetitive processes and how we might improve and automate them. This year we updated our Octicons publish workflow, and used GitHub’s open-sourced bot, Probot, with the Figma API and Travis CI to automate parts of the workflow. You can read more about this on the GitHub blog.

Office hours

In addition to First Responder, we started doing office hours 3 days per week to give people a regular time to ask us questions in person. This is used for pairing on code, talking through product updates that need our support, and responding to general questions.

Scaling the team

Being able to show the value of design systems has enabled me to grow the team. As the team’s manager, I’ve been able to make the case for new headcount by showing the positive impact we’ve made, such as how teams have been able to ship new features more efficiently, or that developers are able to get farther with front-end design without having to wait for design help. Rather than talking about what we can’t do when asking for headcount, I focus on showing all the great work we are already doing, and then paint a picture of what else we could do with more people.

In 2017 we hired a new Systems Designer, Shawn. Shawn came to us from the US Web Standards. Having experience working in design related roles and design systems previously, he is able to make development decisions with design consideration.

This year (2018) we hired our first full-time engineer, Emily. Previously she worked on front-end at Buffer and contributed to their component library. Emily has experience with React.js and accessibility which is important for our team and current projects.

Whether we hire designers or engineers, we usually look for people with some generalist skills. We want developers than have design sensibilities so that they can make good decisions on how systems will work when implementing design, and we want designers that have some code literacy and can empathize with and design for the developer experience. This is important to us because design systems are where design and engineering meet. They need to provide a unified design language and work for both designers and engineers.

Scaling myself

As the team lead and manager, I’ve had to scale my impact too. I manage more people than I did a year ago, and I’ll be managing more people and teams by the end of 2018 as I start to build out design operations. This means I can’t do individual contributor work very often anymore. Earlier this year I found I started to become a bottle-neck and so have worked on being more of an editor than an author for design systems work.

In the past I contributed to more of the visual design work for Primer and have been the main decision-maker on the design of its API. I’m learning to let other members of the team take the lead on those decisions, and where there are gaps, I’m learning to teach those skills to others.

Scaling how we build

One of our popular meetings (yes meetings can be fun!) is our weekly component API review. Each person that’s worked on new components walks through their code, demonstrates what the public API would look like for people to use, and talks through items they need feedback on. This meeting helps us work towards the same set of code-style principles so that no matter who builds a component, it will be built in the same way. This helps us create a consistent API for people who use the design system.

What’s next

Each year we set goals, the following list doesn’t cover everything but here’s the main projects we’re focusing on in 2018:

Modernizing our front-end stack

GitHub.com is a Ruby on Rails app and the source of truth for our design system thus far has been Sass. That means people have to make a lot of design decisions when building UI and write a lot of markup.

Rather than separating concerns by languages (such as HTML, CSS, and JavaScript), we’re are working towards a model of separating concerns at the component level. To achieve this, our biggest project this year is building a component library with React.js. We’re in beta at the moment but we will open-source the project as soon as we create a stable v1 release. Several teams at GitHub are already using React; we’ll be focusing on having those applications consume our component library as well as figuring out how to work with components in the GitHub.com Rails application. This work is being carried out in collaboration with our awesome App Systems team, who have already been adding custom elements to make it easier to implement common JavaScript behaviors.

Creating a vibrant hub for collaboration

We want to see even more contributions and collaborations between design systems and other teams; we want to make it easier to work with Primer, and easier to learn to use Primer. To achieve this we’re spending more time on design tools, tutorials, development tools, and simplifying contribution workflows.

This year we’ve been moving our UI Kits into Figma for designers to create mockups and prototypes with. Figma is built on web technology which means we can make use of tooling we use for other design systems workflows, and avoid having to work around software specific to macOS. Figma’s new Styles feature lets us map system primitives like colors and typography to components, similar to how we do in code. Figma’s API makes it easier for us to integrate with other parts of our workflow and automate tasks, such as checking components in Figma against our components in code.

Later this year we’ll turn our attention to code prototyping tools. While visual design tools are great during certain stages of the design process, sometimes it’s helpful to get a bit closer to the metal. Many designers at GitHub work in production code and spike out a branch to explore a new design, however this isn’t always the best approach since it can mean grappling with parts of the stack that are more difficult (and distracting) to work with. Some designers use our codepen template or project to prototype in HTML with Primer CSS.

We know both approaches aren’t ideal for all use cases though. Designers often mockup pages and flows. They need to be able to tweak and adjust designs and quickly see the results just like we do in visual design tools. This can be hard in production, but if they start with a Codepen template instead they might have to build a lot of existing UI before they get to focus on the feature they’re working on. In an ideal world designers want to work with production data, or something that closely represents it, and it would be great if they didn’t have to start from scratch and build out all of the chrome around their feature. We know this is a challenge for many companies, and I’m hoping we can find a setup that works.

Working in the open

We’d like to be one of the first companies people think of when they want to learn more about design systems. Many companies are investing in design systems, and it’s an ever evolving field. We want to share what we learn along the way in case it might help others.

Earlier this year we made our new style guide public—I shared this after speaking at a design systems event where I talked about the pressure people might feel by comparing their design system to those of other companies. Rather than comparing our design systems to others, we should create our own metrics for success. What’s right for other companies might not be right for yours. Even though our style guide has quite a few bugs and room for improvement, I felt we should share ours too, warts and all!

We have been working more in the open, doing all our release planning in our open-source repository. We will continue to publicly share new projects that we think might be useful to others, either to use in their project or just as a reference for how to do something. We plan on writing more (hence this post!), and speaking at or participating in community events.

If there’s something you’d like to hear more about from us, please let us know here or open an issue in the Primer repo.

GitHub is continuing to invest in design systems. We’ll keep striving to do our best work, and share our successes and failures along the way. If you want to help build design systems that GitHubbers use to build features that millions of developers use every day, consider joining our team.