Guidelines

Icon artboard

Because our icons typically appear beside text we designed our icon artboards (in Illustrator) to match the vertical footprint of Avenir Next. Avenir Next text set to a font size of 16px has a rendered height of 19px. To account for the additional white space, we set the icon artboards to 19px (h).

Relative sizing

When typing or placing an icon next to Avenir Next in print or web, all icons should have a similar size. Refer to our guidelines on how type should scale relative to neighboring text.

When designing these icons, we used two sizing grids: a smaller one that fits within the standard circle, and a larger one for non-circle icons. This allows icons to have a similar visual prominence, whether inside or outside of the circle.

Alignment

The overall position of a circle icon is centered on the cap height of Avenir Next. Within the circle, the icon is centered optically.

The alignment of non-circle icons depends on the icon height in relation to the footprint of Avenir Next. For more horizontal icons, vertically centering the icon on the cap height of Avenir Next often leaves it floating. To solve this, we start the grid on the baseline for more horizontal icons. For more vertical icons that exceed the cap height of Avenir Next, we center the icon on the cap height.

Color

The color of an icon should match the color of neighboring text. This setting is built into our code and happens automatically, provided that the icon is within the same parent element as the text. If the icon sits outside of the text’s parent element the color must be applied manually but should still match the color of the text.

Code examples:

• Heading color automatically applied to the icon: <h2>{icon} Heading text</h2>
• Heading color must be manually applied to the icon: <div>{icon}<h2>Heading text</h2></div>

Scale

Icons should be scaled relative to the size of neighboring text. This setting is built into our code and happens automatically, provided that the icon is within the same parent element as the text. If the icon sits outside of the text’s parent element the scaling must be applied manually but the icon should still be scaled relative to the size of the text.

In code, the SVG height is scaled to match the rendered text height, calculated by dividing the rendered height by the assigned font size (19/16 = 1.1875em). This appears in the code as @cf-icon-height: 1.1875em.

Code examples:

• Icon is automatically scaled relative to the heading size: <h2>{icon} Heading text</h2>
• Icon must be manually scaled relative to the heading size: <div>{icon}<h2>Heading text</h2></div>

Behavior

SVG icon basics

The cfpb-icons component provides Scalable Vector Graphic (SVG) icons. The filenames of the SVGs included with cfpb-icons match the names in the icon library section. We encourage using your templating system to inject the SVG icon files, as opposed to copying and pasting the raw SVG.

Note: Jinja2, the templating language that consumerfinance.gov 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' %}.

What the SCSS is doing

If you look in cfpb-icons.scss 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 CSS 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.

Inline SVG background

In some cases we embed an SVG as a background image. To accomplish this, a custom postcss plugin is used to inject the SVG icon source file inline into the CSS background-image property. This is exposed via a custom CSS property, --cfpb-background-icon-svg: '[name] [color]', where [name] is the SVG icon canonical name, and the optional [color] is the color of the icon in rgb(r,g,b) format.

Interaction details

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