Iconography

Icon library

Version: 4.1.1

Note: copy.svg and copy--code.svg have been deprecated. Use copy--new.svg instead.

Iconography uses images and symbols to represent an object visually. They communicate a message and should be simple, distinct, and informative. Icons should be used sparingly throughout the product to provide clarity and reduce cognitive load on users.

Resources

You can find the source file for the icon library within the Design Kit.

Icons GitHub repo
Icon library
Service provider master icon list
IBM Design Language icon library

Visual usage

Sizing

Icons come in 2 sizes: 24px and 16px.
While most icons occupy a square artboard, some icons may occupy a rectangular artboard where the width or height of the icons is either 24px or 16px.

In most cases, you can use icons at their original sizes.

Background

All icons should be on a transparent background and centered within the artboard boundaries at one of the below standard dimensions.

• Background: 100% Transparent

Padding

When creating icons:

• Do not add internal padding with Sketch or Illustrator.
• If the icon needs padding, developers can add this with CSS.

When using icons:

• All touch targets need to be 44px or higher. With that said, a developer can add padding to a touch target with CSS to meet the 44px requirement.

Color

Interactive UI icons need to pass the same color contrast ratio as typography at a 4.5:1 ratio. UI icons are always a solid color. The color of the icon should depend on the importance of the icon's action.

If it is a primary action then the icon should be:

• Blue 30 for the dark UI
• Blue 51 for the light UI

If the icon is a secondary or supplementary action, then the icon color should be:

• Navy-Gray-8 for the dark UI
• Navy-Gray-7 for the light UI.

Blue should always be used with an icon to show that it is interactive. For secondary UI icons, the hover state should be blue to help emphasize that it is interactive.

Exception: There is an exception to both the Blue and Neutral color rules. Certain icons, such as status or notification icons, can inherit their parent color. For example, a warning icon is yellow because warning notifications are yellow.

Weight

Icons of the same size should have the same visual weight. One icon should not look heavier or lighter than another icon of the same size. Most UI Icons are drawn with a two pixel stroke.

Be mindful when resizing icons, make sure that the 2px stroke does not increase or decrease causing icons to look uneven. When scaling icons you should always start each icon at the same base size (preferably the default of 24px).

Glyphs or 16 pixel icons, should always be a filled icon. This adds visual weight to the icon, allowing it to maintain its proper emphasis and stay legible. Fine stroke weights can disappear or break at the glyph size.

Pixel grid

When drawing or re-sizing icons make sure the vector always aligns to the base pixel grid. This ensures pixel clarity and crispness on all screen ratios. The x and y coordinates of icons should never contain decimals.

Developer usage

The following guidelines are for developers who are using bluemix-icons.

Using SVG file from static assets

You can use sprite.svg or bluemix-icons.svg by serving it as a static asset (like an image file) and use it with the following HTML:

  <!-- From static assets  -->
    <svg>
      <use xlink:href="path/to/static-assets/img/sprite.svg#common--arrows"></use>
    </svg>
    

Using SVG file from Bluemix.Common

Bluemix.Common provides an endpoint to access their currently installed version of bluemix-icons. Using the icons in your HTML will look like this.

  <!-- From Bluemix.Common -->
    <svg>
      <use xlink:href="https://dev-console.stage1.ng.bluemix.net/api/v4/img/sprite.svg#common--arrows"></use>
    </svg>
    

Important notes about Bluemix.Common:

• If you need more control over how the polyfill is invoked, use bluemix-icons locally as a static asset.
• The polyfill acts directly on the window object, so it shouldn't need to be re-imported if you are using the header JavaScript from Bluemix.Common.

Main files

Bluemix icons ships with two main SVG files that contain different sets of external SVG sprite files:

Styling Icons with CSS

Note: The icons use original color by default, which should be black. Colors can be changed with CSS.

Some icons are colored while others are black by default. You can edit the fill to change this. See the temporary reference page for a guide with what xlink:href to use.

To edit these icons in CSS, add your own class to the <svg>. For example:

SCSS:

  .icon--add {
      fill: #cc6699;
    }
    

HTML:

  <svg class="icon--add">
      <use xlink:href="path/to/sprite.svg#service--add-filled"></use>
    </svg>
    

Accessibility

For screen reader accessibility, use <title> element and aria-labelledby attribute.

  <svg class="icon--add" aria-labelledby="add">
      <title id="add">Add a new service</title>
      <use xlink:href="https://dev-console.stage1.ng.bluemix.net/api/v4/img/sprite.svg#common--add"></use>
    </svg>
    

• The aria-labelledby attribute will reference the id attribute in the the <title> element. Make sure that you do not duplicate this id.
• The <title> element will be read by the screen reader to the user so it should describe it's purpose.

Visual guidelines

Adding icons

If you would like to add an icon to our library, please submit a Pull Request in our GitHub Repo.

If you're not comfortable with making a Pull Request, please submit an issue in the repo with the icon attached.

1. Fork the GitHub repo.
2. Clone it to your local system.
3. Add icons in the proper folder (you may add your own) within the svg/ folder.
4. In your terminal run npm install.
5. Run npm run build to rebuild the sprite.svg.
6. Submit a Pull Request and rejoice!

Exporting SVGs

Best practices

• Square icons: create an artboard for an individual icon that is 24 x 24 pixels (or 16 x 16 pixels for glyphs)
• Rectangular icons: make sure the width or the height of the artboard is 24 pixels (16 pixels for glyphs).
• Each artboard and the artwork within it must be pixel perfect.
• No decimals in x and y coordinates or width and height fields.
• No padding when exporting icons (internal and external padding can be added with CSS).
• Do not trim transparent pixels.
• Ungroup icon layers completely. It should be on the top-most layer in your artboard.
• Make sure to properly name layers and artboards (these names will also be exported into the code).

How to export SVGs from Sketch

1. Draw a 24 x 24 pixel stand-alone artboard.
2. Place icon in the pixel perfect center of the artboard.
3. Convert all strokes to outlines (Shift + ⌘ + O)
4. Select any overlapping shapes and click the Union icon from the top navigation, to merge all of the shapes together.
5. Make sure the icon is at #000000 and has no additional styling.
6. Select the entire artboard (not just the icon).
7. Click “Make Exportable” at the bottom of the right toolbar in Sketch.
8. In the “Export” widget select SVG in the format dropdown.
9. Click “Export 'Artboard-Name'”.
10. Name icon with the #name--modifier convention. (ex. copy.svg, copy--code.svg, add.svg, add--outline.svg).

Example: This is what a Sketch artboard should look like before SVG export

How to export SVGs from Adobe Illustrator

1. Draw a 32 x 32 pixel stand-alone artboard.
2. Place icon in the pixel perfect center of the artboard.
3. Expand all strokes (Object > Expand).
4. Select all overlapping shapes and click the Unite icon in the Pathfinder panel, to merge all of the shapes together.
5. Make sure the icon is at #000000 and has no additional styling.
6. Select “File” from the top navigation.
7. Select “Save A Copy...” which will open a dialog.
8. On the “Format” dropdown select SVG (svg).
9. Below “Format” select “Use Artboard” then select either all or a range of artboards depending on your need.
10. Click “Save”.
11. The “SVG Options” dialog will then open.
12. Make sure the preferences are the same as in the image below.

SVG export options from Adobe Illustrator

Developer guidelines

These are contributing guidelines for adding UI icons.

Service icons: you can find all icons for internal services on the Master icon list on Release Blueprints.

Submitting pull requests

Do not commit built files.

• These are files created when running npm run build
• Committing build files results in unintended merge conflicts

Keep your branch up to date with master branch.

Adding SVGs

1. Fork this repo
2. Clone the fork to your computer
3. Add icons to svg folder
4. Optional: Open terminal to your forked repo
5. Run npm install to make use of dev environment
6. Submit a pull request

When submitting pull requests to bluemix-icons, simply add icons to svg folder directly.

Do not add new icons to svg subfolders, these are legacy icons that will be removed in 4.0.0.

For example, icons in any subfolders, like taxonomy or common, are legacy icons.

Prepping SVG XML code

All SVG icons are optimized through SVGO and other build steps to prepare icons for use via external SVG sprite files (sprite.svg and bluemix-icons.svg).

For example, here's how XML code for add--glyph.svg can look:

  <svg width="16px" height="16px" viewBox="0 0 16 16" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <path
        d="(removed for brevity)"
        id="Shape"
        stroke="none"
        fill="#000000"
        fill-rule="evenodd"
      ></path>
    </svg>
    

The XML code must have the following attributes:

• width and height
• viewBox
• fill-rule="evenodd"

It must not have the following nodes:

• <g>
• <style>

SVGO and other build steps will not optimize correctly when <g> nodes are present.

About SVGO and Gulp API

Gulp is used for build tasks and are accessed via npm scripts.
SVGO is used with various other gulp tasks to format external SVG sprite files. These should only be used when submitting pull requests that bump the repo to new versions.

See API reference here.