In Summer 2019 we will be moving Capital Framework's code to the design-system repository. Until that migration occurs, please continue to use these docs.

cf-icons

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

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.

icon icon-round canonical name aliases
up chevron-up
right chevron-right
down chevron-down
left chevron-left
arrow-up  
arrow-right  
arrow-down  
arrow-left  

Status icons

icon icon-round canonical name aliases
approved check, checkmark, success
error delete, close, remove, multiply, multiplication, x
warning alert, exclamation-mark
help question, question-mark
update updating (used for animated state)
dollar  
plus add, addition, expand
minus subtract, subtraction, collapse
divide division
equal equals
percentage percent

Social/sharing icons

icon icon-square canonical name aliases
email envelope, envelope-back
facebook  
flickr  
github  
linkedin  
twitter  
youtube  

Communications icons

icon icon-round canonical name aliases
email envelope-back
fax fax-machine
mail envelope-front
phone telephone, handset
technology cellphone, tablet
web globe, world

Document icons

icon icon-round canonical name aliases
appendix  
paper-clip attach, attachment
copy duplicate
document doc, pdf
download  
upload  
edit pencil
print printer
rss feed
save disk
supplement  

Financial products, services, and concepts

icon icon-round canonical name aliases
bank bank-account
building-credit  
car car-loan, auto, auto-loan
complaint  
fountain-pen contract
credit-card  
credit-report  
debt-collection  
debt  
getting-a-credit-card credit-card-contract
loan  
money dollar-bill
money-transfer  
mortgage sold
house buying-a-house, owning-a-home, home
payday-loan  
college paying-for-college, grad-cap, mortarboard
prepaid-cards prepaid
quick-cash  
piggy-bank retirement
     
     
piggy-bank-check      
     
     
split      

Web application icons

icon icon-round canonical name aliases
audio-max audio-high
audio-medium  
audio-low  
audio-mute mute, audio-off
bookmark  
unbookmark  
broadcast antenna, radio
bullhorn megaphone
chart graph
clock time
date calendar
dialogue discussion
disabled no, disallowed
external-link  
favorite star, starred, fav, fave
unfavorite unstar, unstarred, unfav, unfave
information info, i
lightbulb idea
link  
list  
lock locked
unlock unlocked
menu hamburger
microphone mic
newspaper news
parent family
play  
open-quote  
close-quote  
search zoom, magnifying-glass
settings preferences, gear, cog
share  
speech-bubble  
user person
wifi wi-fi, wireless