Design and user interface changes

Follow these guidelines when contributing or reviewing design and user interface (UI) changes. Refer to our code review guide for broader advice and best practices for code review in general.

The basis for most of these guidelines is Pajamas, GitLab design system. We encourage you to contribute to Pajamas with additions and improvements.

Merge request reviews

As a merge request (MR) author, you must include Before and After screenshots (or videos) of your changes in the description, as explained in our MR workflow. These screenshots/videos are very helpful for all reviewers and can speed up the review process, especially if the changes are small.


Check these aspects both when designing and reviewing UI changes.


  • Follow Pajamas as the primary guidelines for UI text and documentation style guide as the secondary.
  • Use clear and consistent terminology.
  • Check grammar and spelling.
  • Consider help content and follow its guidelines.
  • Request review from the appropriate Technical Writer, indicating any specific files or lines they should review, and how to preview or understand the location/context of the text from the user's perspective.


  • Consider similar patterns used in the product and justify in the issue when diverging from them.
  • Use appropriate components and data visualizations.

Visual design

Check visual design properties using your browser's elements inspector (Chrome, Firefox).


Check states using your browser's styles inspector to toggle CSS pseudo-classes like :hover and others (Chrome, Firefox).

  • Account for all applicable states (error, rest, loading, focus, hover, selected, disabled).
  • Account for states dependent on data size (empty, some data, and lots of data).
  • Account for states dependent on user role, user preferences, and subscription.
  • Consider animations and transitions, and follow their guidelines.


Check responsive behavior using your browser's responsive mode (Chrome, Firefox).

  • Account for resizing, collapsing, moving, or wrapping of elements across all breakpoints (even if larger viewports are prioritized).
  • Provide the same information and actions in all breakpoints.


Check accessibility using your browser's accessibility inspector (Chrome, Firefox).


When the design is ready, before starting its implementation:


At any moment, but usually during or after the design's implementation:

  • Contribute issues to Pajamas for additions or enhancements to the design system.
  • Create issues with the ~UX debt label for intentional deviations from the agreed-upon UX requirements due to time or feasibility challenges, linking back to the corresponding issue(s) or MR(s).
  • Create issues for feature additions or enhancements outside the agreed-upon UX requirements to avoid scope creep.
  1. You're not required to design for dark mode while the feature is in alpha. The UX Foundations team plans to improve the dark mode in the future. Until we integrate Pajamas components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches.