Guidelines

Color

Icons should always be one color. If used over a color field, negative space should be knocked out.

Although color usage is flexible, icons should always be used in high contrast tones relative to the background to maximize legibility.

Spacing

Padding varies around icons of various primary shapes. Square, vertically and horizontally rectangular, diagonal, and most complex icons can fit within the relative padding bounding box. Circular and some complex icons should be slightly larger to offset the visual weight of surrounding negative space.

Content guidelines

• Icons are typically used in conjunction with text.
• They typically match the color of the corresponding text.
• The size of the icon should match the size of the text it corresponds to.

Interaction details

Please reference the Links page for guidance regarding icons paired with links.

Behavior

SVG icon basics

The cfpb-icon component provides Scalable Vector Graphics (SVG) icons. This component can be used by itself, but is designed to work with the Design System.

We subscribe to the guidance offered by Chris Coyier in his article, “A Pretty Good SVG Icon System”, in which he concludes, “Just include the icons inline.”

Because including raw SVG code is not necessarily pretty or user-friendly, we encourage using your templating system to include them by reference.

Note: Jinja2, the templating language that cfgov-refresh uses, has a near-identical syntax for includes, but it requires that the path be enclosed in quotation marks, like so: {% include 'icons/download.svg' %}.

The filenames of the SVGs included with cfpb-icons match the names in the icon library section. There are duplicate SVG files for each alias, as well.

Note to contributors: If any icon is ever updated, you must be sure to also update each of the alias SVGs.

What the Less is doing

If you look in cfpb-icons.less, below the aforementioned sizing variable, you’ll see this simple rule:

.cf-icon-svg {
    height: @cf-icon-height;
    vertical-align: text-top;
    fill: currentColor;
    …
}

Referring back to the example above, you can see that we have encoded class="cf-icon-svg" in the root element of each of our SVG icons. As a result, the Less rule gets applied to all of the SVGs on the page, just like any other HTML element.

We start by limiting the size of the SVG to a proportion of the text height, using the @cf-icon-height variable’s em value. To align the canvas of the icon with the canvas of neighboring text, we set vertical-align: text-top;. Finally, setting fill: currentColor; tells the SVG to set its path’s fill color to match the color value of its parent element.

Caveats

There are two modifications based on restrictions in Internet Explorer 8 and 9 (IE8/IE9).

First, IE8 does not support fill: currentColor. Typically the fallback would be to use a PNG image, but due to the inability to know what the background or text color of its surroundings are, we found it better to fall back to the paired text with no icon.

Second, IE9 displays SVGs as full width by default (not the paths, just the SVG container). To eliminate this issue we’ve set the width of the SVGs to match the height. The whitespace to the left or right may not be quite accurate, but we determined this is an acceptable difference for a legacy browser like IE9.

Inline SVG background

In some cases we embed an SVG as a background image. To accomplish this, a custom Less plugin is used to inject the SVG icon source file inline into the CSS background-image property. This is exposed via a mixin, .u-svg-inline-bg( @name, @color: @black ), where @name is the SVG icon canonical name and @color is the SVG fill color (which defaults to black).