Accoutrement: Color 2.3.1

Managing Contrast & Accessibility

@function contrast()

For any color, select the best contrast among a set of options. For best results, pass in a combination of light and dark colors to contrast against –  or define default contrast-light and contrast-dark values in your global $colors map.

Parameters & Return

$color: (string | list)

The name or value of a color.

$options: #000, #fff (arglist)

Two or more colors to contrast against. This function will choose the best contrast of all the options provided, or the contrast-light and contrast-dark defaults if they are defined in your color palette, otherwise white and black are the default options.

@return (color)

Whichever color-option has the highest contrast-ratio to $color.

@error

Provide at least two contrasting color options for contrast()

Examples

scss default options 
$background: #333;
html {
  background: $background;
  color: contrast($background);
}
css compiled 
html {
  background: #333;
  color: #fff;
}
scss explicit options 
$background: #333;
html {
  background: $background;
  color: contrast($background, red, orange, yellow, green, blue, indigo);
}
css compiled 
html {
  background: #333;
  color: yellow;
}

Requires

@function color()

@function luminance()

@function contrast-ratio()

$colors

Used By

@mixin contrasted()

@mixin contrasted()

Apply any background color, along with the highest-contraast text color from a set of options. This works the same as the contrast function, but applies the resulting values to background-color and text color properties.

Parameters & Output

$background: (string | list)

The name or value of your desired background color.

$options: #fff, #000 (arglist)

A list of colors to contrast against, defaulting to white and black or your contrast-light and contrast-dark settings if they are prodided in the global $colors map.

{CSS output} (code block)

  • Sets the background-color to $background and the foreground color to whichever option has better contrast against the given background.

Examples

scss default options 
$background: #333;
html {
  @include contrasted($background);
}
css compiled 
html {
  background-color: #333;
  color: #fff;
}
scss explicit options 
$background: #333;
html {
  @include contrasted($background, red, orange, yellow, green, blue, indigo);
}
css compiled 
html {
  background-color: #333;
  color: yellow;
}

Requires

@function color()

@function contrast()

@function contrast-ratio()

Compare two colors using the WCAG comparison algorythm, and return the resulting contrast-ratio. Optionally pass in a standard (AA, AAA, AA-large) and return false when the contrast-check fails.

  • ‘AA-large’ == 3:1
  • ‘AA’ == 4.5:1
  • ‘AAA’ == 7:1

Parameters & Return

$color: (string | list | number)

The name of a color in your palette, any other color value, or even a pre-calculated numeric luminance.

$contrast: (string | list | number)

The name or value of a color to contrast against the first.

$require: false ('AA' | 'AA-large' | 'AAA' | number | false)

An optional WCAG contrast ratio to require. The function will return false if the required ratio is not met.

@return (number)

The WCAG-defined contrast-ratio of two colors.

Example

scss 
/* black and white: #{contrast-ratio(white, black)} */
/* failed 'AAA': #{contrast-ratio(white, #999, 'AAA')} */
css compiled 
/* black and white: 21 */
/* failed 'AAA': false */

Related

WCAG Contrast Definition [external]

Requires

@function luminance()

$WCAG-CONTRAST [private]

Used By

@function contrast()

@function luminance()

Get the WCAG luminance of a color in your palette.

Parameters & Return

$color: (string | list)

The name or value of a color.

@return (number)

WCAG-defined numeric luminance value.

@error

#{$color} is not a color.

Related

WCAG Relative Luminance [external]

Requires

@function color()

@function _acc-pow() [private]

Used By

@function contrast()

@function contrast-ratio()