Update banner settings and related mixins

[thisisdano]

This PR updates the banner settings to allow custom color for the background and link. It also allows developers to set the color of links against dark backgrounds.

setting	default	usage
$theme-banner-background-color	"base-lightest"	Set the background color of the banner
$theme-banner-link-color	default	Set the color of the link text and icon
$theme-link-reverse-color	"base-lighter"	Text link color against dark backgrounds
$theme-link-reverse-hover-color	"base-lightest"	Text link hover color against dark backgrounds
$theme-link-reverse-active-color	"white"	Text link active color against dark backgrounds

The component will adjust the text color of the banner (to either "white" or "ink" for proper AA contrast against the specified background. When $theme-banner-link-color is default, the link and icon will use the default link colors (either standard or reverse) or any color token set in $theme-banner-link-color. The system will throw an error if the custom color will not provide sufficient AA contrast against the specified background.

Note: This uses an SVG mask technique not supported by IE11. The fallback in IE11 will use either a "black" or "white" chevron icon, depending on the background color.

The icon object

This PR introduces the concept of the icon object, a Sass map that contains metadata about USWDS icons. The icon object requires some specific icon file setup to function properly:

• Icon must be an SVG
• A canonical icon must be saved in the format [name].svg. Ex: arrow.svg
• The canonical icon must be black (#000).
• Color icon variants must be saved in the format [name]-[variant].svg. Ex: arrow-red-50v.svg
• Variants must use the name of a valid USWDS token. Ex: red-warm-50v or gold-30
• There must be a white (#fff) icon variant. Ex: arrow-white.svg

key	required	description	example
"name"	Y	String. The name of the svg icon, assuming the following svg naming convention: [name]-[color-variant].svg	"arrow.svg"
"svg-height"	Y	Number. The unitless height value found in the SVG image.	9
"svg-width"	Y	Number. The unitless width value found in the SVG image.	16
"height"	Y	Size token or Number. Display height of the icon	0.8ex
"color"		Color token. The color of the icon. If omitted or null defaults to "ink".	"primary"
"color-hover"		Color token. Color the icon should be on hover. If omitted or null the icon color will not change on hover.	"primary-dark"
"color-variant"		Color token. A specific icon variant used as the preferred icon fallback color for IE11. If 'omitted or null, defaults to "white".	"blue-60"
"container-height"		Size token. Height of a container that surrounds the icon. If omitted or null defaults to svg-height.	2
"container-width"		Size token. Height of a container that surrounds the icon. If omitted or null defaults to icon height * svg-width / svg-height.	2
"rotate"		Number. Rotation of the icon in the form XXdeg. If omitted or null, no rotation.	180deg
"path"		String. A custom path to the icon, relative to the outputted CSS. Omit trailing slash. If omitted or null defaults to $theme-image-path	"../my-project/img"

Example:

// Define an icon object
$icon-chevron: (
  "name": "chevron",
  "svg-height": 39,
  "svg-width": 64,
  "height": 0.8ex,
  "color": "ink"
);

$icon-chevron-right:  map-append(
  $icon-chevron, (
      "rotate": -90deg
   )
);

// Get smart link colors
$banner-icon-colors: get-link-tokens-from-bg(
  $theme-banner-background-color,
  $theme-banner-link-color
);
$banner-icon-color: nth($banner-icon-colors, 1);
$banner-icon-hover: nth($banner-icon-colors, 2);

// Edit an icon object with a map-append()
$banner-icon-chevron-right: map-append(
  $icon-chevron-right, (
      "color": $banner-icon-color,
      "color-hover": $banner-icon-hover,
   )
);

// Use an icon object in a mixin
.icon-chevron {
  @include add-color-icon($icon-chevron, $contrast-bg);
}

.banner-link {
  @include place-icon($banner-icon-chevron-right, "after", 2px, middle, $contrast-bg );
}

Mixins

add-color-icon()

argument	required	description	example
$icon-object	Y	Map. An icon object variable	$icon-arrow
$contrast-bg	Y	Color token. The background color against which the icon appears. The mixin uses this color to pick the proper icon color for the IE11 fallback icon.*	"white"

*The system will first evaluate the contrast ratio between color-alt ("white" by default) and $contrast-bg and use that variant unless it fails, in which case it will use the default (black) icon.

Example:

.icon {
  @include add-color-icon($banner-icon-chevron, $contrast-bg);
}

place-icon()

Places an icon before or after an element as an inline-block, using the :before or :after pseudoelements.

$argument	required	description	example
$icon-object	Y	Map. An icon object variable	$icon-arrow
$direction	Y*	String. Where to place the icon (either before or after)	"after"
$margin	Y*	Units token Margin between the icon and element	0.5
$vertical-align	Y*	String. The vertical alignment of icon	middle
$contrast-bg	Y	Color token. The background color against which the icon appears. The mixin uses this color to pick the proper icon color for the IE11 fallback icon.*	"white"

.icon {
  @include place-icon($banner-icon-chevron-down, "after", 2px, middle, $banner-bg);
}

Functions

get-token-from-bg()

Returns a color token with proper WCAG contrast from two token options and a background.

$argument	required	description	default
$bg-color	Y	Color token. Background to check contrast against.	—
$preferred-text-color	Y	Color token. Preferred text color.	"white"
$fallback-text-color	Y	Color token Fallback text color.	"ink"
$wcag-target		String. The WCAG contrast level to check. Accepts AA, AAA, or AA-large	AA

$theme-color-primary: "blue-60v";

get-token-from-bg("gray-50") → "white"
get-token-from-bg("gray-30") → "ink"
get-token-from-bg("white", "primary") → "primary"
get-token-from-bg("ink", "primary") → "white"
get-token-from-bg("ink", "primary", "red-60v") → error

get-color-from-bg()

Returns a color hex with proper WCAG contrast from two token options and a background.

$argument	required	description	default
$bg-color	Y	Color token. Background to check contrast against.	—
$preferred-text-color	Y	Color token. Preferred text color.	"white"
$fallback-text-color	Y	Color token Fallback text color.	"ink"
$wcag-target		String. The WCAG contrast level to check. Accepts AA, AAA, or AA-large	AA

$theme-color-primary: "blue-60v";

get-color-from-bg("gray-50") → #fff
get-color-from-bg("gray-30") → #1b1b1b
get-color-from-bg("white", "primary") → #005ea2
get-color-from-bg("ink", "primary") → #fff
get-color-from-bg("ink", "primary", "red-60v") → error

get-link-tokens-from-bg()

Returns a two system color tokens (base link and hover) with proper WCAG contrast from two base link color token options and a background color.

$argument	required	description	default
$bg-color	Y	Color token. Background to check contrast against.	—
$preferred-text-color	Y	Color token. Preferred link color.	$theme-link-color
$fallback-text-color	Y	Color token Fallback link color.	$theme-link-reverse-color
$wcag-target		String. The WCAG contrast level to check. Accepts AA, AAA, or AA-large	AA

$theme-color-primary: "blue-60v";

// If neither option can provide a link and a hover with proper contrast, throw an error
get-link-tokens-from-bg("gray-50", "black", "white") → error (neither "black" nor "white" can have a valid hover value)
get-link-tokens-from-bg("gray-30") → error (neither default link value has proper contrast against "gray-30")

// Hovers are one step above or below the link color, with the same vivid value
get-link-tokens-from-bg("white") → ("primary", "blue-70v")
get-link-tokens-from-bg("ink") → ("base-lighter", "white")
get-link-tokens-from-bg("ink", "blue-40") → ("blue-40", "blue-30")

// Grade 90 is never vivid
get-link-tokens-from-bg("white", "green-80v", "red-50v") → ("green-80v", "green-90")

// Favor the preferred link color
get-link-tokens-from-bg("white", "green-60v", "red-60v") → ("green-60v", "green-70v")