@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
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
color: tools.var-contrast(
'background',
'light', 'dark', black, white
);
}
html {
color: white;
}
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
color: tools.var-contrast(
'background',
'light', 'dark', black, white,
'AAA'
);
}
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 foregroundcolor
to whichever option has better contrast against the given background.
Examples
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
@include tools.var-contrasted(
'background',
'light', 'dark', black, white
);
}
html {
background-color: var(--color-background, blue);
color: white;
}
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
@include tools.var-contrasted(
'background',
'light', 'dark', black, white,
'AAA'
);
}
html {
background-color: var(--color-background, blue);
color: var(--color-light, #eee);
}
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
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
color: tools.contrast(
'background',
'light', 'dark', black, white
);
}
html {
color: white;
}
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
color: tools.contrast(
'background',
'light', 'dark', black, white,
'AAA'
);
}
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
andcolor
to the option with highest contrast against that background, or minimum contrast that still meets a given accessibility ratio.
Examples
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
@include tools.contrasted(
'background',
'light', 'dark', black, white
);
}
html {
background-color: blue;
color: white;
}
tools.$colors: (
'background': blue,
'light': #eee,
'dark': #111,
);
html {
@include tools.contrasted(
'background',
'light', 'dark', black, white,
'AAA'
);
}
html {
background-color: blue;
color: #eee;
}
@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
/* black and white: #{tools.contrast-ratio(white, black)} */
/* failed 'AAA': #{tools.contrast-ratio(white, #999, 'AAA')} */
/* 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.