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.

DoDon’t
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 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.

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

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

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.

Icon keyline grid
Keyline grid
Icon keyline shapes
Keyline icon shapes
Icon keyline examples
Keyline icon examples

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.
Icon stroke settings
1.5px stroke weight inside aligned and rounded stroke caps
Line with rounded join
Line with round join
Line with mitar (square) join
Line with miter join

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 1px and 2px border radius helps the elements fit together better.
Icon with 0px and 4px border radius
A combination of 0px and 3px 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 doing so risks losing features critical to the icon’s meaning.

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.

Angle settings
15º angle increments

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.

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.

DoDon’t
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.

DoDon’t
Simple house icon
Simplified icon
Complex house icon
Overly complex icon

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

DoDon’t
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.

DoDon’t
Duplicate icon
Icon with square clipped cap
Duplicate icon
Icon with round clipped cap

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.

DoDon’t
Shield icon
Crisp shield icon
Shield icon
Friendly 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.

DoDon’t
Menu icon
Icon represents “menu”
menu icon
Menu icon used for “list”
DoDon’t
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.

DoDon’t
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.

DoDon’t
Flat screen display with play symbol
Flat screen display
Tube TV with antenna
Old tube TV

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

Last updated at: