Tokens » Custom Properties
There are many cases where it can be useful to convert a Sass token map into CSS custom properties. Here are some tools to help.
@mixin token--()
Set a single custom property based on a map-token, with optional alias, fallback, and prefixing
Since 2.0.0
:
- NEW: Initial release
Parameters
$map: (map)
Accoutrement map of tokens to use as source
$token: (*)
Token name available in the source $map
$value: null (string | null)
Optional new value for the given token
$fallback: true (*)
The optional fallback value for a var()
function:
true
will generate a fallback based on the token value- A token name will fallback to the value of that CSS variable and then to the token’s calculated value
- Any other fallback will be passed through unchanged
$prefix: null (string | null)
Optional prefix used for naming token variables
Example
$colors: (
'_brand': hsl(120, 50%, 50%),
'text': '#_brand' ('color.scale': ('lightness': -50%)),
'border': '#text',
);
.example {
@include tools.token--($colors, 'border');
@include tools.token--($colors, 'outline', 'border', red);
}
.example {
--border: var(--text, hsl(120, 50%, 25%));
--outline: var(--border, red);
}
Used By
@mixin tokens--()
@mixin tokens--()
Convert any Accoutrement Tokens map into CSS custom properties (aka variables).
- Token names that start with
_
or-
are considered “private” and will not be output as variables - Tokens that contain a simple alias with no adjustments
will be output with a
var()
value, keeping the alias relationship intact
Since 2.0.0
:
- NEW: Initial release
Parameters & Output
$map: (map)
Accoutrement map of tokens to set as CSS variables
$prefix: null (string | null)
Optional prefix for naming token variables
{CSS output} (code block)
Custom properties for all public tokens in the map
Example
$colors: (
'_brand': hsl(120, 50%, 50%),
'text': '#_brand' ('color.scale': ('lightness': -50%)),
'border': '#text',
);
html {
@include tools.tokens--($colors, 'color-');
}
html {
--color-text: hsl(120, 50%, 25%);
--color-border: var(--color-text, hsl(120, 50%, 25%));
}
@function var-token()
Access the CSS variable associated with a given token, along with a fallback value based on the token itself
Since 2.0.0
:
- NEW: Initial release
Parameters & Return
$map: (map)
Accoutrement map of tokens to use as source
$token: (*)
Token name available in the source $map
$fallback: true (*)
The optional fallback value for a var()
function:
true
will try to generate a fallback based on the color value- A color name will fallback to the value of that CSS variable and then to the color’s calculated value
- Any other fallback will be passed through unchanged
$prefix: null (string | null)
Optional prefix used for naming token variables
@return (string)
CSS variable call, in the format:
var(--<color>, <fallback>)
Example
$colors: (
'_brand': hsl(120, 50%, 50%),
'text': '#_brand' ('color.scale': ('lightness': -50%)),
'border': '#text',
);
.example {
border-color: tools.var-token($colors, 'border');
color: tools.var-token($colors, 'text', black);
}
.example {
border-color: var(--border, hsl(120, 50%, 25%));
color: var(--text, black);
}