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.

Icons take inspiration from elements expressed as part of the GitLab brand.

  • Balance and structure. Regardless of symmetry, icons should feel complete and in control. Icons act as visual anchors or guides and should be designed to either stop or direct the eye.
  • Modern and approachable. Border radius and open counters help our icons combine beauty and utility with a touch of personality.
  • Crisp and intentional. Icon elements should have purpose and place.
  • Simple and concise. Design to minimize time to comprehension. In the same way the concept of “invisible UI” moves a user to task completion without getting hung up on visual elements or controls, icons should move users to concept and action without extra time spent deciphering a metaphor.

Icon collections

There are four icon collections used in the product (not including the Web IDE): UI, status, pipeline, file and folder icons. The design guidelines covered in the sections below only apply to UI and status icons.

Example UI icon
Example status icon
Example pipeline icon
Example file icon
File and Folder

UI icons

As the largest of the four collections, comprising of several subcategories, these icons are used broadly in the product to represent GitLab concepts and indicate actions and information in the UI. UI icons can be interactive or informational depending on the context. Third-party brand icons are included in this collection, but are exempt from most design guidelines.

Status icons

These smaller icons complement text or relevant content to indicate the general status, health, or the trend direction of an object. Due to their small size, these icons aren’t interactive unless paired with text or contained within an element, like a badge component, giving them a larger target size.

Pipeline icons

These icons represent the status of a pipeline, like running and pending. There are both bordered and borderless versions of each icon. They use a separate grid from all other icons and are also used to generate favicons associated with web pages. Although a pipeline status can overlap conceptually with status elsewhere in the product, these icons are strictly limited to the pipeline context.

File and folder type icons

These third-party icons have specific file and language associations, like SCSS, JavaScript, and YAML, and are maintained under a separate MIT license. More information can be found in the project repository.

Icon grids

Icon elements are aligned to a pixel grid. Elements within an icon, such as curves or diagonal lines, won’t always align exactly to the grid. This is okay; in these instances it’s better for the element to feel natural rather than forced.

Alignment considerations for a 1.5px stroke are covered in the Strokes section below.

In nearly all instances icons should be used at the size they were created at and not scaled. This keeps the icons crisp and consistent in the UI.

Crisp icon on pixel grid
Icon outside edges aligned to the pixel grid
Blurry icon on pixel grid
Icon edges not horizontally aligned to the pixel grid<

16 pixel grid

The 16px icon size is the default, and most UI icons are created at this size. Icons using this 16×16 pixel grid have a 14px live area surrounded on all sides by 1px for padding and optical sizing.

16px icon grid at 100% scale
16 pixel icon at 100%
Icon live area
Grid 14×14 pixel live area
Icon padding
1px icon padding

12 pixel grid

The 12px grid is used for all status icons, and some UI icons. Icons using this 12×12 pixel grid have a 10px live area surrounded on all sides by 1px for padding and optical sizing.

12px icon grid at 100% scale
12 pixel icon at 100%
Icon live area
Grid 10×10 pixel live area
Icon padding
1px icon padding


A keyline grid is a set of guides to help maintain optical balance (visual weight) between icons. Use it as a starting point and guide, but not a hard rule. There are four basic shapes that represent common icon scale and placement. Squares can fill the live area, while circles and rectangles can extend into the padding, which allows icons to be proportionately consistent.

Icon keyline grid
Keyline grid
Icon keyline shapes
Keyline icon shapes
Icon keyline examples
Keyline icon examples
Add 12px grid keylines. Create an issue

Optical balance

In regard to icons, optical balance is the perceived size of an icon relative to other icons. The more that icons feel balanced with one another, the easier it will be to rely on other characteristics to provide visual hierarchy and flow in the UI. Icons that are not balanced can draw unnecessary attention to themselves, or seemingly disappear in the mix of other elements.

Here are a few considerations when trying to achieve optical balance.

  • More detail equals more visual weight. As the density of the graphic increases, it will draw more attention. Try offsetting this by simplifying detailed icons.
  • Rotate narrow icons 45º, which gives them more visual weight.
  • At times, optically adjusting an icon may mean less adherence to the grid or other spacing rules to the benefit of balance or clarity.


Nearly all UI icons use a 1.5px stroke weight. Lines use rounded caps, unless doing so would misrepresent the metaphor, or if you are trying to infer depth or element clipping. Round line joins are optional and also depend on the metaphor. For example, a checkmark is one continuous object and the round line infers fluidity, whereas clock hands are two joined objects and a miter join defines a joint.

A 1.5px stroke:

  • Is more balanced with other UI elements and is similarly weighted to regular system font weights at body text sizes.
  • Provides more room to convey abstract concepts and metaphors by allowing for both more detail where needed and extra space between elements for clarity.
  • Works well in both light and dark UI.

Since icons use a 1.5px stroke, there are a few alignment considerations:

  • A stroke is either aligned to inside or center.
  • Outside edges of closed shapes should align to whole pixels.
  • A line should have at least one edge aligned to a whole pixel. This won't always be possible when two lines comprise an element that has to be centered within the grid or to other elements, but the line end points should always terminate on a whole pixel.
Icon stroke settings
1.5px stroke weight and rounded stroke caps
Line with rounded join
Line with round join
Line with mitar (square) join
Line with mitar join


Using a stroke (outline) is the default design approach, however a limited number of UI icons and all status icons use a solid fill instead. As a general rule, UI icons that use a solid fill have a specific reason for doing so. For example, the clear (×) icon used to clear a text input requires extra visual weight to not be missed in the UI, and thus has a solid fill applied.

Border radius

To have parity between inside and center aligned strokes with a 1.5px weight, the border radius options are:

Stroke aligned insideStroke aligned centerResult
0px0px0 border radius example
1px0.25px1 pixel border radius example
2px (default)1.25px2 pixel border radius example
3px2.25px3 pixel border radius example

Clarity should always override consistency, and the guides are flexible when necessary to best represent the metaphor or parts of it.

Icons with 0px, 1px, 2px, 4px, 6px, and 100% border radius options
Border radius options, 2px is default
Icon with 2px and 4px border radius
A combination of 2px and 4px border radius helps the elements fit together better.
Icon with 0px and 4px border radius
A combination of 0px and 4px best represents the subject matter.
Icon with 1px border radius
A 1px border radius works well for angles that are less than 90º.
Icon with no border radius
This icon does not use a border radius because in doing so features critical to the meaning would be lost.


Use increments of 15º to achieve consistency throughout the icon set. Angles can be combined in an icon to create more dynamic shapes and movement, while remaining consistent as a whole.

Angle settings
15º angle increments


Sharp interior angles help icon clarity. A 1px gap between elements is acceptable, but 2px is preferred when possible — consistency will always help the icons feel more unified.

Icon shape settings
Icon with sharp interior angles and at least 1px spacing between elements

Design most icons in 2D. Depth and perspective should only be used when it’s absolutely necessary to clarify a concept, and even then 2px strokes are used to add dimension instead of larger fill areas.

3D box icon
Icon with depth clarifies concept
Square icon
Icon with no depth is too vague

Simplify icons for clarity and legibility, avoiding embellishment or unnecessary details.

Simple house icon
Simplified icon
Complex house icon
Overly complex icon

Remove or close counters that are less than 1px to avoid distracting artifacts.

Pencil icon
Icon with no small counters
Pencil icon
Icon with small, distracting counter

Use square caps and shape edges to directly indicate clipping or layering. Round should still be used when breaks and intersections are more stylistic.

Duplicate icon
Icon with square clipped cap
Duplicate icon
Icon with round clipped cap


Design to the concept

The guidelines are helpful constraints to help focus on the concept without overthinking style. On the other hand, it’s critical to not let the same guidelines negatively impact a metaphor. A great example is a shield icon. While the default border radius is 2px, using that here could make the icon feel too friendly, when really we want to emphasize robust and accurate security.

In another more literal example, an icon representing tabular data should have crisp edges. Why? Because the UI of tables in the product have crisp, 90º angles. This creates a 1:1 relationship between the icon and the object it represents, making it much easier for users to infer the intended meaning.

As with all of the guidelines, there will always be some level of subjectivity. Use your best judgement, and test when necessary.

Shield icon
Crisp shield icon
Shield icon
Soft shield icon
Table icon
Literal table icon
Table icon
Rounded table icon

Icon meaning

GitLab icons should reflect positive or neutral metaphors. Avoid concepts related to violence or that generally have a negative meaning. Ask yourself, will this icon benefit all users? Is there any potential that its meaning could be confusing or cause anxiety? If there's any doubt, explore other options that are at least neutral in meaning.

Specific meaning, specific icon

Using an icon consistently to represent a single concept or action helps with overall learnability for a user. For example, the icon used to represent a feature or an object shouldn't be used to refer to other unrelated concepts or actions in the UI.

Avoid using different icons to refer to one specific meaning. For example, pencil should be used for editing or updating an item, rather than pencil-square which is used for composing.

Menu icon
Icon represents “menu”
Menu icon
menu icon used for “list”
Full screen icon
Correct icon for “full screen”
Alternate full screen icon
Different icon for “full screen”

Icons with multiple meanings

There are, however, several icons whose design doesn't match a single metaphor, but multiple. In these cases, meaning must be provided in context. Examples of these cases are:

  • An '×' icon in a close button on a modal can also represent a failed status.
  • An 'eye' icon to indicate a confidential issue can also be used to show a password, or to view a preview of an object.
  • A 'chevron' icon in a dropdown button can also represent the expanded state of an accordion.

In addition to context, ensure that aria-label attributes and/or tooltips are used to communicate the icon meaning.

Unique metaphors and concepts

If an icon is not accompanied by a label or its use isn't clear based on the immediately surrounding context, then provide a quick explanation in a tooltip.

Got hook icon with label and tooltip
Icon meaning is available
Git hook icon
Is that a smiling cat?

Modern metaphors

Try to avoid potentially antiquated concepts, especially when something more modern is recognizable.

Flat screen display with play symbol
Flat screen display
Tube TV with antenna
Old tube TV


Existing GitLab SVGs icons haven't historically followed a naming convention, so you may encounter different patterns until we're able to address them individually. Use the following guidelines for new icons:

  • When an icon represents a recognizable object, use the name of the object. For example, an icon of a pencil that represents editing is named 'pencil'.
  • When an icon represents an abstract metaphor or concept, choose a name that best represents the concept or use case. For example, an icon made of stacked shapes to represent an epic is named 'epic'.
  • The file name should be lowercase and use hyphens as a separator between terms. For example, 'cloud-gear'.
  • Icons in the GitLab Product Icons Figma file contain keywords and usage details in the component description (each icon is a component) to help unite naming with use and concepts. We hope to eventually have similar capabilities in the GitLab SVGs website.


Icons are used to stress visual weight for elements with a high priority or to explain the universal knowledge in a simple way.

The level of visual weight from heavy to light is: Icon + label > Icon > label.

Referencing icons in code

For more information on how icons are referenced in the product, go to GitLab Docs - Icons and SVG Illustrations.


Last updated at: