The cf-icon component provides Scalable Vector Graphics (SVG) icons for Capital Framework. This component can be used by itself, but is designed to work with Capital Framework.

Table of contents

• Variables
  • Size variables
• SVG icon basics
• Rotating update icon
• The icons
  • Navigation icons
  • Status icons
  • Social/sharing icons
  • Communications icons
  • Document icons
  • Financial products, services, and concepts
  • Web application icons

Variables

Component variables are used to theme a component. They likely will be left as is, but if needed can be overwritten by duplicating the variable in a @key: value format with a different value. This customized variable would be placed in the same file where this component’s less file is imported.

Size variables

The standard icon height in ems matches the 19px rendered canvas of text set in Avenir Next sized at 16px (19/16 = 1.1875).

@cf-icon-height: 1.1875em;

SVG icon basics

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

As a simple example, you could create one of our icon links like so:

Download the info sheet

<a class="a-link a-link__icon" href="#">
    <span class="a-link_text">Download the info sheet</span>
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 651.7 1200" class="cf-icon-svg"><path d="M507.1 692.8c-15.6-15.6-40.9-15.6-56.6 0l-85.1 85.1V466.6c0-22.1-17.9-40-40-40s-40 17.9-40 40V778l-85.1-85.1c-15.6-15.6-40.9-15.6-56.6 0-15.6 15.6-15.6 40.9 0 56.6L297 902.9c7.5 7.5 17.7 11.7 28.3 11.7s20.8-4.2 28.3-11.7l153.3-153.4c15.8-15.7 15.8-41 .2-56.7z"/><path d="M30 161c-16.5 0-30 13.5-30 30v827.8c0 16.5 13.5 30 30 30h591.7c16.5 0 30-13.5 30-30V343.7L469 161H30zm389.6 60v134.8c0 19.9 16.3 36.2 36.2 36.2h135.9V988.8H60V221h359.6z"/></svg>
</a>

The SVG code in this example was copied from cf-icons/src/icons/download.svg.

Because including raw SVG code is not necessarily pretty or user-friendly, we encourage using your templating system to include them by reference. For example, here is how we include them in the templates of the Capital Framework documentation site:

<a class="a-link a-link__icon" href="#">
    <span class="a-link_text">Download the info sheet</span>
    {% include icons/download.svg %}
</a>

Which renders as:

Download the info sheet

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 cf-icons match the names in the tables below. 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 cf-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 ), where @name is the SVG icon canonical name.

Rotating update icon

Our previous font icon system provided modifiers to rotate any icon. We found in reality this wasn’t practical and only one icon is ever animated, update. We’ve provided an alias–updating–to be used within the UI when a user needs to be made aware that the website is working on responding to their actions. See the status icons table below

The icons

Each icon has a circled variant shown in the second column (or square, in the case of the social media icons) that can be accessed by appending -round (or -square) to the canonical name or any of its aliases.

Navigation icons

Status icons

Social/sharing icons

Communications icons

Document icons

Financial products, services, and concepts

Web application icons