Accoutrement 4.0.5

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

scss 
$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);
}
css compiled 
.example {
  --border: var(--text, hsl(120, 50%, 25%));
  --outline: var(--border, red);
}

Requires

@function ident()

@function is-alias-for()

@function var-token()

@function get() [private]

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

scss 
$colors: (
  '_brand': hsl(120, 50%, 50%),
  'text': '#_brand' ('color.scale': ('lightness': -50%)),
  'border': '#text',
);
html {
  @include tools.tokens--($colors, 'color-');
}
css compiled 
html {
  --color-text: hsl(120, 50%, 25%);
  --color-border: var(--color-text, hsl(120, 50%, 25%));
}

Requires

@mixin token--()

@function is-private-token()

@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

scss 
$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);
}
css compiled 
.example {
  border-color: var(--border, hsl(120, 50%, 25%));
  color: var(--text, black);
}

Requires

@function ident()

@function get() [private]

Used By

@function var-change()

@function var-ease()

@function var-time()

@function var-color()

@function var-ratio()

@function var-size()

@mixin token--()

@function var-font()