Accoutrement 2.1.1

Tokens » CSS Variables

aka “Custom Properties”

CSS variables are a useful way to manage values that might change in relation to the DOM – something that Sass variables cannot do. In many cases, we find it helpful to manage variables in Sass, and output CSS properties as-needed. These tools help integrate Accoutrement map values with CSS variables to keep that relationship intact.

The Core feature provides generic variable logic, while each plugin provides specialized shortcuts for maintaining:

Some of the use-cases covered here can be written more simply in pure CSS. but these tools provide two main advantages:

  • Core logic allows plugins to build additional shortcuts
  • Explicit relationships make code more meaningful

@mixin tokens--()

Convert any Accoutrement 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' ('shade': 50%),
  'border': '#text',
);
:root {
  @include tokens--($colors, 'color-');
}
css compiled
:root {
  --color-text: #206020;
  --color-border: var(--color-text, #206020);
}

Requires

@mixin token--()

@function is-private-token()

Used By

@mixin changes--()

@mixin easing--()

@mixin times--()

@mixin colors--()

@mixin ratios--()

@mixin sizes--()

@mixin fonts--()

@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' ('shade': 50%),
  'border': '#text',
);
.example {
  @include token--($colors, 'border');
  @include token--($colors, 'outline', 'border', red);
}
css compiled
.example {
  --border: var(--text, #206020);
  --outline: var(--border, red);
}

Requires

@function _a_var-name() [private]

@function is-alias-for()

@function var-token()

@function get-token()

Used By

@mixin change--()

@mixin ease--()

@mixin time--()

@mixin color--()

@mixin ratio--()

@mixin tokens--()

@mixin size--()

@mixin font--()

@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' ('shade': 50%),
  'border': '#text',
);
.example {
  border-color: var-token($colors, 'border');
  color: var-token($colors, 'text', black);
}
css compiled
.example {
  border-color: var(--border, #206020);
  color: var(--text, black);
}

Requires

@function _a_var-name() [private]

@function get-token()

Used By

@function var-change()

@function var-ease()

@function var-time()

@function var-color()

@function var-ratio()

@mixin token--()

@function var-size()

@function var-font()