Guidelines for sizing of icons that appear with text

[natalia-fitzgerald]

Which page is this about?

Design System -- Foundation -- Iconography

Sections:

• Icon with text
• Content guidelines

What kind of issue is this?
Add one or more of the issue labels below to the right-hand sidebar AND issue title.
(We strongly encourage you to make content changes yourself where possible!)

• Info incorrect
• Content enhancement (e.g. confusing or redundant content, small content items need to be added, etc.)
• Needs content written (page is missing key information, e.g. use cases)
• Needs code snippet
• Overhaul page (page needs large-scale content rewriting and restructuring)

Describe your issue
The Design System has two sets of sizing guidelines for icons that appear with text on the web. Neither of these guidelines match (or at least fully capture) what's happening with the code on the webpage. There is a section called "Content guidelines" that includes guidelines on the sizing and the color of icons with text. There is also a section called "Icons with text" that includes sizing guidelines but these guidelines don't indicate which specific heading levels they apply to. They use terms like "extra small" and "large." In web and in print we pair icons with specific headings and text. Our sizing guidelines should be specific. Additionally we should include examples as live code for all of the potential heading and text combinations.

Size this request (1=tiny, 5=enormous)
I estimate a 4 for figuring out the sizing by heading and writing a plain language explanation of what is happening in the code and what the design and sizing intent is.

Add any additional background info as needed

• Update all icons to have default 19px height; add new icons; revise some existing icons; add docs for devs
• Document new minicon standard
• Make updates to the icon font - "Noun Project"

Icons and text	Content guidelines

Thanks. Don't forget to add labels indicating issue type and size before submitting!
Once you've submitted your issue, please add it to the content backlog project board: https://github.com/cfpb/design-system/projects/1

[natalia-fitzgerald]

I have now dug through a lot of documentation on this and would like to move forward with attempting to update the Design System documentation to better reflect the design intent and the implementation of this intent in the code. My focus is on the specs for the sizing of icons that appear inline with text(specifically on the web).

In order to update the specs I would like to better understand the current state (and the history) of how we size icons that appear next to text on the website. These assumptions and guesses may not reflect the order in which these things happened but I wanted to try and piece this together in the hopes that someone may have some missing pieces to complete the picture.

My end goal is for the Design System documentation to have a single set of guidelines for the sizing and alignment of icons that sit inline with text. These guidelines should ideally include design intent, specs, live code examples for each heading and text level (and any special use cases - for example buttons, links, etc.), and documentation that reflects how we implement this in the code.

Original Design Manual Sizing Guidelines:
https://github.com/cfpb/design-manual/blob/9e8d7a6718a2d68226ebd2e570d6c5e45afd2648/brand-guidelines/minicons.md#scaling

New guidelines were added to the Design System on Aug 4, 2020:
7606b5c

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.

Assumptions

• The illustrator source files for the CFPB icon font were originally designed with artboards set to 1000 (w) x 1200 (h).

• The SVG view box for icons was set to 1000 (w) x 1200 (h). (When exported, the illustrator artboard dimensions are embedded into the SVG as the view box dimensions)

• When CSS was disabled icons would load very large.

• The vertical footprint of Avenir Next text at 16px (1em) renders with a height of 19px (h)

• We came up with a calculation to scale the icons based on the text size (19/16 = 1.1875).

• We set a CSS class that sets the icons height to 1.1875em (cf-icon-svg)

• The height was set to match the 19px “rendered canvas” of text set in Avenir Next

On May 19, 2021, we standardized the height of all icons for the web. We set the art boards and SVG view box height to 19px. (Update all icons to have default 19px height; add new icons; revise some existing icons; add docs for devs #1234 (#1234))

Related issues:

Dec 15, 2017 
Document new minion standard (cfpb/design-manual#551)

• Once it was determined that the icons would all live on Illustrator artboards of the same dimensions, @jimmynotjim and I needed to create a batchable action in Illustrator to remove whatever left and right whitespace exists in the files provided to us by the designers, so that when we actually display them on a webpage, that whitespace is not rendered.
• As there is no simple command to do that kind of thing in Illustrator, we determined with some Googling that the easiest way to handle it would be to write an Illustrator script – a snippet of JavaScript that can be executed on an Illustrator document. We found some Adobe forum answers to get us started down this path, beginning with the example script found here. Once that was working, we began iterating on the script to get it to do what we wanted, primarily referring to the official Adobe llustrator CC 2017 Scripting Guide [PDF].
• The final script we arrived at is documented in #577 (comment)

Notes about design intent: 


Pulled from: cfpb/design-manual#551 (comment)

Alignment

Circle icon alignment

The overall position of a circle icon is centered on the cap height of Avenir Next. Inside the circle, icons are centered (optically).

Open icon alignment

Outside of the circle, centering the icon often leaves it floating next to Avenir. To solve that, we started the grid on the baseline for more horizontal icons. Once an icon becomes taller than the cap height of Avenir, then it becomes centered on the cap height.

• Jan 22, 2018

FEWD - Update the canvas resizing script #577 (cfpb/design-manual#577 (comment))

• Update the script to only remove the left and right whitespace, leaving the top and bottom white space and the path sizes intact.

• February 14, 2018

Update cf-icons to use inline svgs rather than an icon font #752

Icon fonts have some shortcomings with accessibility and
maintainability. To simplify usage, we've converted them to inline SVGs
that are then included by each project's templating system. The process
from hand-off from Graphic Designers requires removing left/right
whitespace (we batch processed the icons through
an Illustrator script to save hours of work), followed by optimization
via SVGO within Capital Framework. The resulting icons are then copied
to their respective projects via that project's build process. Finally,
we updated each of the other components that require icons to use the
new pattern. The exception is the example for the rotating icon within
a button (see the usage doc for further info).

Additions

• SVG Icons
• CSS to size, position and color icons

Sep 18, 2018


Huge SVG icons when CSS is disabled (https://github.com/cfpb/capital-framework/issues/863)


“The new inline SVG icons look huge when CSS is disabled and makes it almost impossible to read the page.”

On August 23, 2019 the following comment was added to the Design System codebase:


Aug 27, 2020 
Make updates to the icon font - "Noun Project"

“I am currently working with Scott Cranfill on the web versions of the SVGs. We have come to certain conclusions regarding processing and necessary file considerations involved in export, which I will be documenting in detail. It's a very specific process and needs to be followed to a "T" in order to work properly. Now that we've almost gotten past the SVG coding, Scott is moving forward with testing the files by processing them through SVGO and using them "properly" in the dev environment.”

The final height of the artboard will always remain 19px regardless of width. This height was determined as optimal for the web when CSS is not available to load.

Once you have the width of your artboard set to match the icon, round up the artboard width measurement to a whole number using your up arrow key and then add one more pixel for padding.

Resize the artboards proportionately with artwork, so that the height becomes 19px and width 15.8333px. Once you have the width of your artboard set to match the icon, round up the artboard width measurement to a whole number using your up arrow key and then add one more pixel for padding. For example, the final size of a circle icon will be 19px high by 17px wide (which is 16px wide plus 1 px for padding).

May 19, 2021
 Update all icons to have default 19px height; add new icons; revise some existing icons; add docs for devs #1234 (#1234) - May 19, 2021

• we standardized the height of all icons for the web. We set the art boards and SVG view box height to 19px.

• “Previously, icons were very large in their native SVG format and had to be scaled down with CSS. Icons now have a more reasonable default size when viewed without SVG, and can be scaled up with CSS in the same way they were previously scaled down.”

• Revises all icons to fix sizing issue describe above
• Fixes the SVGO config file so that the process-icon-svgs script now works as desired.

The Design System (Iconography)

https://cfpb.github.io/design-system/foundation/iconography#behavior

SVG icon basics

The cfpb-icons component provides Scalable Vector Graphic (SVG) icons. This component can be used by itself, but is designed to work with the CFPB 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 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' %}.

The filenames of the SVGs included with cfpb-icons match the names in the icon library section.

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.




Current state:

• The height of the the icon artboards in illustrator are set to 19px (h)
• When exported, the artboard dimensions are embedded into the SVG as the viewbox dimensions
• The height of the SVG viewbox is set to 19px (h)
• The artboard/SVG viewbox for circle icons is set to 19 (w) x 17 (h).
• The artboard/SVG viewbox for open icons is set to 19 (h) and a variable width with a max of 17 (w)
• The artboard/SVG view box includes padding/white space
• The path dimension (the actual icon footprint) is smaller than the artboard/SVG viewbox

Questions:

• What was the original CSS goal for the sizing of the icons that appear inline with text? To scale down the size of the icons? What exactly were were trying to solve for/accomplish?
• What is the current CSS goal for the sizing of the icons that appear inline with text? To scale up the size of the icons? What are we trying to solve for/accomplish?
• Did we once use the 16/19=1.875em calculation to SCALE DOWN the 1000 x 1200 SVG files and then later use the 16/19=1.875em calculation to SCALE UP the 19px high SVGs?
• What is the current design intent for the sizing of circle icons that appear inline with text? Is there a size for each heading level? If yes, should we specify the SVG viewbox dimensions and/or the path dimensions?
• What does this do: process-icon-svgs?
• What does this script do: ArtboardWidthToArt.jsx
  var docRef = app.activeDocument;
  var index = docRef.artboards.getActiveArtboardIndex();
  pdtRedim(index,docRef);
  function pdtRedim(idx,doc){
  var ab, rect0, rect;
  ab = doc.artboards[idx];
  rect0 = ab.artboardRect;
  doc.fitArtboardToSelectedArt(idx);
  rect = ab.artboardRect;
  rect = [rect[0],rect0[1],rect[2],rect0[3]]
  ab.artboardRect = rect;
  }

Design intent (assumptions)

• The scaling of inline icons is relative to the size of the parent heading element.
• The overall position of a circle icon is centered on the cap height of Avenir Next. Inside the circle, icons are centered (optically).
• Outside of the circle, centering the icon often leaves it floating next to Avenir. To solve that, we started the grid on the baseline for more horizontal icons. Once an icon becomes taller than the cap height of Avenir, then it becomes centered on the cap height.
• The color of an icon should match the color of the text that it sits inline with (on the web there is code that makes this happen)

@anselmbradford @contolini @chaisamantha @designlanguage

[natalia-fitzgerald]

Goals (priority order)

• Confirm findings and current state, validate design intent
• Update Design System Guidelines - Inconography page (sizing guidelines, code examples, etc.)
• Correct incorrectly sized icons (12 round status icons)

Current state for SVG icons:

This is my overview of the current state.

• The illustrator artboards for icons are set to 19px(h)
• When exported, the illustrator artboard dimensions are embedded into the SVG as the viewbox dimensions
• The height of the SVG viewbox is set to 19px(h) for all CFPB icons
• The illustrator artboard/SVG viewbox for circle/round icons is set to 17px (w) x 19px (h)
• The path for circle icons is 15.833px x 15.833px.
  • There is 0.5835px of padding on each side (left and right).
  • There is 1.58335px of padding on top and 1.58335px padding on top.
• The illustrator artboard/SVG viewbox for open icons is set to 19px (h) and a variable width with a max of 17px (w)
• The illustrator artboard/SVG view box includes padding/white space
• The path dimension (the actual icon footprint) is smaller than the illustrator artboard/SVG viewbox
• The CSS code for icons is: .cf-icon-svg {height: 1.1875em; vertical-align: text-top; fill: currentcolor; max-width: 1em;}
• When the SVG icon sits outside of a parent element it defaults to 17px (w) x 19px (h) (path: 15.833px x 15.833px)

Design intent

These are my assumptions about the design intent (which I will pull from to write the guidelines)

• The scaling of inline SVG icons is relative to the size of the parent heading element.
• The overall position of a circle icon is centered on the cap height of Avenir Next. Inside the circle, icons are centered (optically).
• Outside of the circle, centering the icon often leaves it floating next to Avenir. To solve that, we started the grid on the baseline for more horizontal icons. Once an icon becomes taller than the cap height of Avenir, then it becomes centered on the cap height.
• The color of an icon should match the color of the text that it sits next to (in cases where the heading is the parent element the code will pull the color of the text and apply it to the icon)

Open questions:

Question 1:

What was the original CSS goal for the sizing of the icons that appear inline with text? To scale down the size of the icons? What exactly were were trying to solve for/accomplish?

Question 2:

What is the current CSS goal for the sizing of the icons that appear inline with text? To scale up the size of the icons? What are we trying to solve for/accomplish?

Related to Question 1 and Question 2:

Did we once use the 16/19=1.875em calculation to SCALE DOWN the 1000 x 1200 SVG files and then later use the 16/19=1.875em calculation to SCALE UP the 19px high SVGs?

Question 3:

What is the current design intent for the sizing of icons that appear inline with text? Is there a size for each heading level or should this be explained more in terms of being related to the height of the text on the webpage? I have some notes on design intent in this respect but no notes on design intent in terms of actual sizes.

Question 4:

What does this do: process-icon-svgs?

Question 5:

What does this script do: ArtboardWidthToArt.jsx

[Scotchester]

Here are my answers to the open questions from my perspective and historical recollection (caveat: my memory may be faulty):

Question 1:

What was the original CSS goal for the sizing of the icons that appear inline with text? To scale down the size of the icons? What exactly were were trying to solve for/accomplish?

Correct. Because the SVGs had 1000+ pixel artboards/viewboxes, CSS was required to scale them down to be appropriately sized in comparison to neighboring text.

Question 2:

What is the current CSS goal for the sizing of the icons that appear inline with text? To scale up the size of the icons? What are we trying to solve for/accomplish?

The current end goal is the same – ensure the icon renders at the proportionate size to the text, regardless of the size of the text. Without the 1.1875em rule, you would have to specify exact icon sizes for each size of text that they could potentially be paired with, which would be quite unwieldy. Using the relative em units also ensures that the proportions remain correct if a user chooses to set a different default text size in their browser.

Related to Question 1 and Question 2:

Did we once use the 16/19=1.875em calculation to SCALE DOWN the 1000 x 1200 SVG files and then later use the 16/19=1.875em calculation to SCALE UP the 19px high SVGs?

Yes, but to add a bit of nuance:

• For paragraph text that is set at 16px by default, the 1.1875em icon size results in the SVG rendering at exactly its native size (with a height of 19px).
• For anything larger than paragraphs, like headings, the 1.1875em icon size scales them up from their native height of 19px, maintaining the same visual proportion relative to the neighboring text size.

Question 3:

What is the current design intent for the sizing of icons that appear inline with text? Is there a size for each heading level or should this be explained more in terms of being related to the height of the text on the webpage? I have some notes on design intent in this respect but no notes on design intent in terms of actual sizes.

I think the answers to the previous three questions essentially answered this, but to be specific: I don't recall there being a specific actual size specified for icons paired with text larger than 16px. We just let the calculation do its thing.

Note: I feel like there may be a few one-off instances where icons paired with headings were intentionally made larger than the standard 1.1875em multiplier, but I can't point to any examples off the top of my head.

Question 4:

What does this do: process-icon-svgs?

It takes the SVG code that comes out of Illustrator and removes things that aren't needed for our use, which reduces the filesize, and it also adds two custom classes: cf-icon-svg and cf-icon-svg__ICON-NAME, which are used by our CSS to target the icons.

Question 5:

What does this script do: ArtboardWidthToArt.jsx

This was a script that I developed to take Illustrator source file artboards, remove any left or right margin from them, and ensure that the vertical positioning of the path within the artboard was consistent. It may not be relevant anymore if the source files' artboards have already been updated to take these things into account.

[anselmbradford]

@Scotchester Do you recall why the max-width is 1em and not 1.1875em?

design-system/packages/cfpb-icons/src/cfpb-icons.less

Line 47 in 9aaa41e

max-width: 1em;

[Scotchester]

@Scotchester Do you recall why the max-width is 1em and not 1.1875em?

design-system/packages/cfpb-icons/src/cfpb-icons.less

Line 47 in 9aaa41e

max-width: 1em;

No, I don't! I noticed that the other day and was curious, as well. For some reason, the SVGs were still rendering at 17px wide, according to the dev tools I was looking at, so I guess it should just be left alone!

[Scotchester]

If that rule was just for IE's benefit, though, maybe it can be removed entirely.

[natalia-fitzgerald]

@Scotchester
When I inspect in Chrome it looks like the max-width of 1em does make the SVGs slightly smaller (illustrator artboards and SVGs (viewBox) for round icons are all set to 17px (w) x 19px (h)).

@anselmbradford Was that max-width rule just for IE's benefit? If so can we remove it? The widest SVGs are 17px wide.

[natalia-fitzgerald]

Update:

I have now published an overhauled Iconography page which should bring us to the current state for how we design, style, and implement icons at the CFPB.

Design System - Iconography

Removed:

• References to exact sizing for icons in web and print (Design Style Guide - Minicons - 2013)
• Section on spacing (Design Style Guide - Minicons - 2013)

Added:

• Section at the top of the page linking to the SVG icons on GitHub
• Design intent and guidelines for designers tasked with creating new icons or using existing icons (developed in 2018)
  • The artboard (Illustrator artboard) (developed in 2018 but later updated for web in 2021 to standardize the artboard dimensions to 19px H).
  • Relative size (across icons in library)
  • Alignment (with Avenir Next)
  • Color
  • Scale
• Web guidelines about the icon artboard and how it relates to the SVG viewBox as well as how we scale icons in relation to the parent text size and color icons in relation to the parent text color
• Updated "Behavior" section with current guidelines for development and links to the GitHub icon page, the cfpb_icons.less file, etc. (reflecting shift from web font to SVG icons in 2018 and change in Illustrator artboard for SVGs (and website SVG icons) to 19px (h) in 2021).
• Live code examples of icons with text for H2-H5 and paragraph

Related additions

• Numerical icons added to the Design System
• Updated the icon scaling explanation in cfpb_icons.less to include the 2021 update to SVG height x width
• fix: [Icons] Update the viewbox of round icons to be a consistent 17(w) x 19(h) #1695
• [Bug] Max-width value is narrower than widest SVG icons #1698

Changed:

• 50/50 content at the top of the page previously linked to the Noun Project and a download for the icon font.
  • The latest release prioritizes the 2 primary use cases: SVG web icons (website) and the CFPB icon font (print).

Next steps:

• Decide where on the page to link to the Noun Project (discuss with designers)
• Change "Icons with text" live code from 50/50 to a table
• Do we need guidelines for print sizing or are the design intent and guidelines sufficient?

I welcome (and would appreciate) any feedback or suggestions. And a special thanks to @anselmbradford and @meissadia for their collaboration on this update as well as special guest @Scotchester for his historical contributions and feedback.

[natalia-fitzgerald]

@anselmbradford @Scotchester
I discussed the max-width with my team and we have decided to remove it. Once this is in production if we later identify a need for a specified max-width we can add it then.

[anselmbradford]

I discussed the #1675 (comment) with my team and we have decided to remove it. Once this is in production if we later identify a need for a specified max-width we can add it then.

The original intent, as you no doubt know, is that we'd support IE much further back in regard to the CSS than in regard to JS. That said, I think if the patterns are kinda broken on legacy IE, but still readable, that's fine. So maybe we'll have unsightly gaps between icons and text in legacy IE. Given Microsoft was abandoned IE support, that seems good enough at this point.

[natalia-fitzgerald]

I'm closing out this issue because we have accomplished the majority of the identified goals. There are longer term next steps for the graphic designers to discuss. These are not urgent so there is no need to keep the issue open.

To discuss with designers:

• Decide where on the page to link to the Noun Project or whether we should include a link to the Noun Project considering we link to our now open sourced our icon font
• Do we need specific guidelines for print sizing or are the design intent and guidelines sufficient?