Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Pajamas Design System

What is the Pajamas Design System?

Located at, the goal of Pajamas is to be the single source of truth for the robust library of UI components that we use to build the GitLab product—including usage and implementation guidelines.

As a fully implemented design system, Pajamas includes:

Why is Pajamas important?

Pajamas enables anyone to contribute towards GitLab. It allows Product, Engineering, UX Design, and Contributors to work together more seamlessly and improve our product faster.

It’s efficient.

It creates a cohesive product.

It helps GitLab communicate.

Who can contribute?

Everyone can contribute! Pajamas is a living system, meaning it continually evolves to support new UI components and also deprecate outdated components. For this evolution to be scalable, we encourage everyone to contribute ideas, designs, code, and bug reports.

External contributions can be particularly valuable, because GitLab Contributors have experiences and insights we may not have considered.

We have specific rules around design review.

When do we add a new component to Pajamas?

Not every component used in the GitLab product must be codified as part of the design system, because sometimes we create components that are relevant for only a specific use case in a distinct product area.

The questions we ask to determine whether to include a component include:

We may find over time that a component we once considered unique is more broadly relevant. In that case, we reevaluate the component to ensure it’s scalable, and we add it in.

What is the component development lifecycle?

The goal of this process is to make it easy to: submit new designs (including documentation), propose changes to existing designs, use existing designs in wireframes, and translate component designs into implemented components.

Some of these processes can run in parallel. WIP: Diagram to show the end-to-end workflow.

Component design

This is the process for understanding user needs, designing the functionality/interaction, vetting the design with users, applying high-fidelity visual design to the component, and annotating the design specs.

  1. Determine if the component should be included in the design system.
  2. Create an issue within the design repository using the UX pattern issue template.
  3. Complete each checklist item from the UX pattern issue template.

Component development

This is the process for implementing the component design in our Vue.js framework.

  1. Determine which issue to work on within gitlab-ui and assign it to yourself.
  2. If the component has already been added to gitlab-ui, create an MR to update the component to match the usage guidelines. Otherwise, build the component.
  3. Include styling that matches the spec preview and conforms to our frontend guidelines (WIP).
  4. Create an issue in the design system to add component documentation and live examples.

Component implementation

To implement the component within the product, the following steps should be followed.

  1. Create an Epic within the gitlab-org group and label it with the gitlab-ui label.
  2. Create sub epics within the Epic for implementing the component within each stage group.
  3. Label the sub epics with the stage group label, as well as gitlab-ui.
  4. Categorize instances of existing implementations of the component or similar components, and create an issue for each one.
  5. Label the issues with the stage group label, as well as gitlab-ui.
  6. Align with Product Management and Engineering to get this scheduled to replace existing older legacy code and/or to be used in upcoming feature development.

Adding technical documentation

  1. Determine which issue to work on and assign it to yourself.
  2. Create a merge request that adds the related Vue.js component.
  3. Fill in any live demo todos for that particular component.
  4. Assign the MR to a design and frontend maintainer for review.
  5. Once approved, the maintainer will merge the MR. A notice of the change will be added to the #design-system Slack channel.

Beautifying the GitLab UI

A design system is only valuable if it’s used consistently throughout the product it supports. Because Pajamas is a new design system, we have to catch up the existing product to using “single source of truth” Pajamas components.

To ramp up implementation, we commit to ensuring that:

This structure ensures capacity by dedicating 50% of five individuals’ time toward owning design system implementation for the first 3-6 months. The remaining 50% is spent within their individual stage groups. Ensuring that each stage group commits to building one component each release will set the design system team up for success by creating a backlog of components that adhere to design system documentation.

How do we measure success?

There are two avenues of success in relation to a design system: adoption and goal achievement. Providing metrics for both adoption and goal achievement provides the organization with a tangible way to measure the overall success of a design system over time.


The value of a design system is only fully realized when the organization ships product that uses its parts. A commitment to adopt is essential to ensuring that the design system achieves the goals highlighted in this document.

To measure adoption, we:

Goal Achievement

As design system adoption increases, we are able to measure the success of our goals, which can be evaluated regularly at major adoption milestones (0%, 25%, 50%, 75%, 100%).