Accoutrement 2.1.1

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

Requires

@function _a_best-contrast() [private]

Used By

@mixin contrasted()

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

Requires

@function _a_best-contrast() [private]

@function is-private-token()

@function _a_var-name() [private]

Used By

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

Requires

@function color()

@function contrast()

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

@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

$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

Requires

@function luminance()

@function _a_valid-contrast() [private]

Used By

@function _a_best-contrast() [private]

@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.

Related

Requires

@function color()

@function _a_type-check() [private]

Used By

@function contrast-ratio()

@function shades-of()

@function _a_best-contrast() [private]