Iconography

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.

Layout

Pixel grid

Icon elements are aligned to the pixel grid. Elements within an icon, such as curves or diagonal lines, won’t always align exactly to the grid, and 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.

Do	Don’t

16 pixel grid

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

12 pixel grid

The 12px icon size is used for small, complimentary icons commonly used to indicate status where text or other context is available. Due to their small target size, these icons aren’t interactive unless paired with text or within a larger element. Icons that use a 12×12 pixel base grid have a 10px live area surrounded on all sides by 1px for padding and optical sizing.

Scaling

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.

Keylines

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.

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 scaling detailed icons down.
• Rotate narrow icons 45º, which allows them to scale and have 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.

Strokes

All 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.

Border radius

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

Stroke aligned inside	Stroke aligned center	Result
0px	0px
1px	0.25px
2px (default)	1.25px
3px	2.25px

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

Angles

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.

Shape

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.

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.

Do	Don’t

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

Do	Don’t

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

Do	Don’t

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

Do	Don’t

Concepts

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.

Do	Don’t

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.

Do	Don’t

Do	Don’t

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.

Do	Don’t

Modern metaphors

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

Do	Don’t

Usage

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.

Resources

• You can view all of the current icons at the GitLab SVGs site.
• View the GitLab Product Icons Figma file.