GitLab Iconography: MVC meets visual design

Dec 2, 2019 · 8 min read
Jeremy Elder GitLab profile

Anyone who uses GitLab knows how extensively we use icons in our product. Because information density is high and screen real estate is at a premium, we use them for everything from indicating status and critical actions to navigation and label clarity. In short, icons have a comparatively large impact for such a visually small UI element.

In traditional product development, it’s common to incrementally update features and functionality, and then save visual updates for major version bumps or larger brand updates. But we already had a collection of issues (the medium for collaborating on ideas and planning work in GitLab) telling us change was needed, so we wanted to address that without the dependency of a new version or brand update spurring us on.

True to GitLab fashion, this meant we could exercise our efficiency value with a minimum viable change (MVC) approach – iteratively making visual updates while providing continuous improvement.

Minimum viable change

At GitLab, we’re comfortable iterating and releasing designs similar to how our development counterparts iterate on functionality. We still research and test our solutions, but we have the freedom to quickly learn and iterate because of our constant exposure to real use. Our end goal is always to have a beautiful, guiding, and functional interface.

At the time of this writing, we have 277 custom SVG icons in our library. There are also more than 800 instances of FontAwesome icons in the product. We reference icons in HAML, HTML, JavaScript, Ruby, and Vue. A wholesale change to use a new set of custom icons across the entire product would be a massive undertaking. Incremental changes are a must.

As it turns out, one of our weaknesses is also a strength. With our UI already mixing icons from two different sources and two different styles, we can concern ourselves less with near-term differences and instead focus on making the right changes moving forward.

Pipelines row that has both SVG and FontAwesome icons together A row in the Pipelines section that contains SVG and FontAwesome icons.

Laying the foundation

One of our values is to create a distinct GitLab personality that is strong and consistent. Iconography offers a powerful visual cue to users and should reflect our particular sense of style. (This is the opening statement in our new iconography documentation.)

We decided that the MVC with the greatest initial impact was updating the icon documentation itself. To reflect the promise of a strong and consistent presence within the product, we had to offer docs that would help fix problems in meaningful and sustainable ways.

To be sure we were iterating in the right direction, we established guidelines that considered the entire icon ecosystem, but still allowed us to make quick changes. At the same time, we also overhauled our iconography documentation to make icon updates and creation as self-help as possible.


One of our values is to create a distinct GitLab personality that is strong and consistent. Iconography is a powerful visual cue to the user and should reflect our particular sense of style.

With directional guidelines and documentation in place, we turned to specific constraints that we could leverage in practice.

Embracing constraints

Who doesn’t love a good set of constraints? We definitely have some.

Perhaps the largest (pun intended), was the small 16×16 pixel grid used for each icon. We wanted to use a fairly common 24×24 pixel grid with strokes set to 2 pixels, so that we could include more fidelity in each icon, scale more freely, and stay within our base-8 pixel grid. When scaled down to our most common size (16 pixels), the strokes would effectively be 1.5 pixels, which looks great on a HiDPI screen. It's just enough weight to stand out and not feel too bold, although they’re blurry on standard definition due to the half pixels.

Visual guidelines from the icon documentation Examples of visual guidelines from the icon documentation

Our analytics show that many users are still on non-HiDPI screens, and while we wanted to push for a new standard, we weren’t ready to make the leap until a majority of users could experience crisp icons in the UI. So, the best choice was to keep the 16 pixel grid and have crisp icons for all.

Another key constraint was stroke weight. Within an even-pixel grid, a 1 pixel stroke can never be centered and aligned to the pixel grid, so we chose to stick with a 2 pixel stroke weight rather than offset some icons. This meant less room for fidelity in the small space, and as a result we aimed for the least amount of detail that provided the most concept clarity.

By nature, other constraints exist in the documentation that deal primarily with stylistic elements.

The process

Work at GitLab starts with an issue or merge request, so we can tackle things in an efficient, async way. Since there were already many icon issues in existence, we created an epic to collect them and added new issues to it. As common themes emerged, we knew that updating documentation would be the place to start, as it gave us something to point back to for current issues and something to stand on for new work.

Updating nearly 300 icons takes time, so we divided them into separate batches where related groups, like everything associated with documents, were updated at the same time. Even though, at this step, style might differ between groups, we were still consistent within the group itself.

Every batch of icons went through an async group review, where we offered feedback and made adjustments over the course of several days. At the close of the review period, we created a merge request to bring the updates into the SVG library. Then, we could test and evaluate the new icons one last time through a review app before releasing them into production.

In each batch, we added a few new icons and deprecated others. We also released updated versions of our Sketch UI Kit concurrently with the product changes.

Not all icons followed this exact process. For example, concepts like epics and issues are fairly abstract, and we really want to ensure their visual representation is both meaningful and proprietary. There’s an entire subgroup that is just for the status of these, so getting them right is crucial. These icons are currently undergoing three rounds of usability testing, and testing will continue to be an important step in our process.

Early results and next steps

After working through hundreds of icons, five batches of updates, and several rounds of usability testing, reactions thus far have been positive and productive. Here are a few worth noting:

Before and after of editor icons Before (top) and after of text editor icons

Because this was an MVC, the work isn’t done yet. Here are some things to watch for in the coming months:

Lastly, you can contribute too! If you have anything you’d like us to consider with regard to icons, create a new issue and tag the GitLab UX Department (@gitlab-com/gitlab-ux). Also, if you’d like to be a part of our testing efforts at any level, be sure to sign up for our GitLab First Look program.

“How the @GitLab UX team is iterating their way to iconography greatness 🙌” – Jeremy Elder

Click to tweet

Free eBook: The benefits of single application CI/CD

Download the ebook to learn how you can utilize CI/CD without the costly integrations or plug-in maintenance.

Learn more
Open in Web IDE View source