Accoutrement 4.0.5

@function var-contrast()

An extension of the contrast() function, designed to output CSS variables rather than simple color values.

Since 2.1.0:

  • NEW: Provides access to contrast colors as CSS-variables, when defined

Parameters & Return

$color: (string | list)

The name or value of a color.

$options...: (colors | min-contrast)

List of colors to contrast against. This function will choose the best contrast of all the options provided, or the contrast-light and contrast-dark defaults defined in your color palette or the factory settings.

  • Any {'AA' | 'AA-large' | 'AAA' | 0-21 } values will be treated as a minimum color-contrast ratio – and will return the minimum accessible option, rather than the maximum contrast.

@return (color | var())

CSS Variable for the color-option that has the highest contrast-ratio to $color, or the color if no variable exists.

Examples

scss max contrast / no variable names 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  color: tools.var-contrast(
    'background',
    'light', 'dark', black, white
  );
}
css compiled 
html {
  color: white;
}
scss min contrast / variable names 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  color: tools.var-contrast(
    'background',
    'light', 'dark', black, white,
    'AAA'
  );
}
css compiled 
html {
  color: var(--color-light, #eee);
}

Requires

@function best-contrast() [private]

@function get() [private]

@function is-private-token()

@function ident()

$color-var-prefix (string)

Used By

@mixin var-contrasted()

@mixin var-contrasted()

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

Since 2.1.0:

  • NEW: Applies contrasting colors as CSS-variables, when defined

Parameters & Output

$background: (string | list)

The name or value of your desired background color.

$options...: (colors | min-contrast)

List of colors to contrast against. This function will choose the best contrast of all the options provided, or the $contrast-light and $contrast-dark defaults defined in your color palette or the factory settings.

  • Any {'AA' | 'AA-large' | 'AAA' | 0-21 } values will be treated as a minimum color-contrast ratio – and will return the minimum accessible option, rather than the maximum contrast.

{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 max contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  @include tools.var-contrasted(
    'background',
    'light', 'dark', black, white
  );
}
css compiled 
html {
  background-color: var(--color-background, blue);
  color: white;
}
scss min contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  @include tools.var-contrasted(
    'background',
    'light', 'dark', black, white,
    'AAA'
  );
}
css compiled 
html {
  background-color: var(--color-background, blue);
  color: var(--color-light, #eee);
}

Requires

@function var-color()

@function var-contrast()

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 (with or without a private _ prefix) in your global $colors map.

Parameters & Return

$color: (string | list)

The name or value of a color.

$options...: (colors | min-contrast)

List of colors to contrast against. This function will choose the best contrast of all the options provided, or the contrast-light and contrast-dark defaults defined in your color palette or the factory settings.

  • Any {'AA' | 'AA-large' | 'AAA' | 0-21 } values will be treated as a minimum color-contrast ratio – and will return the minimum accessible option, rather than the maximum contrast.

@return (color)

Whichever color-option has the highest contrast-ratio to $color, or the minimum needed contrast to meet a given accessibility ratio.

Examples

scss max contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  color: tools.contrast(
    'background',
    'light', 'dark', black, white
  );
}
css compiled 
html {
  color: white;
}
scss min contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  color: tools.contrast(
    'background',
    'light', 'dark', black, white,
    'AAA'
  );
}
css compiled 
html {
  color: #eee;
}

Requires

@function best-contrast() [private]

Used By

@mixin contrasted()

@mixin contrasted()

Apply any background color, along with the highest-contrast 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...: (colors | min-contrast)

List of colors to contrast against. This function will choose the best contrast of all the options provided, or the contrast-light and contrast-dark defaults defined in your color palette or the factory settings.

  • Any {'AA' | 'AA-large' | 'AAA' | 0-21 } values will be treated as a minimum color-contrast ratio – and will return the minimum accessible option, rather than the maximum contrast.

{CSS output} (code block)

  • Sets the background-color to $background and color to the option with highest contrast against that background, or minimum contrast that still meets a given accessibility ratio.

Examples

scss max contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  @include tools.contrasted(
    'background',
    'light', 'dark', black, white
  );
}
css compiled 
html {
  background-color: blue;
  color: white;
}
scss min contrast 
tools.$colors: (
  'background': blue,
  'light': #eee,
  'dark': #111,
);
html {
  @include tools.contrasted(
    'background',
    'light', 'dark', black, white,
    'AAA'
  );
}
css compiled 
html {
  background-color: blue;
  color: #eee;
}

Requires

@function color()

@function contrast()

@function contrast-ratio()

Compare two colors using the WCAG comparison algorithm, 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

$base: (color | number)

Color value, color token name, or pre-calculated numeric luminance for the base color.

$contrast: (color | number)

Color value, color token name, or pre-calculated numeric luminance for a contrast color to compare against the base.

$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: #{tools.contrast-ratio(white, black)} */
/* failed 'AAA': #{tools.contrast-ratio(white, #999, 'AAA')} */
css compiled 
/* black and white: 21 */
/* failed 'AAA': false */

Related

WCAG Contrast Definition [external]

Requires

@function luminance()

@function valid-contrast() [private]

@function check() [private]

@function error() [private]

Used By

@function best-contrast() [private]

@function luminance()

Get the WCAG luminance of a color in your palette.

Parameters & Return

$color: (string | list)

A color value or color token name.

@return (number)

WCAG-defined numeric luminance value.

Related

WCAG Relative Luminance [external]

Requires

@function color()

@function check() [private]

Used By

@function contrast-ratio()

@function shades-of()

@function best-contrast() [private]