Accoutrement 4.0.5

CSS 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 Sass variables with CSS custom properties, to keep that relationship intact.

@function ident()

Formats any string (like a Sass variable or token name) as a CSS “dashed-ident” that can be used for CSS custom properties. Spaces are replaced with a dash, and an optional prefix can be added, in the format --<prefix><string>.

Since 4.0.0:

  • NEW: Provided publicly as ident()

Since 2.0.0:

  • NEW: Initial private release as _a_var-name()

Parameters

$name: (string)

The name of the token to be used as a variable

$prefix: null (string | null)

Optional prefix added to the token name

Example

scss 
$colors: (
  'brand': mediumvioletred,
  'action': teal,
);

html {
  @each $name, $value in $colors {
    #{tools.ident($name, 'colors-')}: #{$value};
  }
}
css compiled 
html {
  --colors-brand: mediumvioletred;
  --colors-action: teal;
}

Requires

@function replace()

Used By

@function var-contrast()

@mixin token--()

@function var-token()

@mixin custom-props()

@mixin custom-props()

Converts a map of variable names and values into CSS custom properties, in the format --<prefix><map-key>: <map-value>.

This can be used with manually-generated maps, but we can also use the Sass module-variables function to generate a map of all the variables in a given module:

  @use 'accoutrement/tools';
  @use 'sass:meta';
  @use '_my-colors';

  $my-colors: meta.module-variables('_my-colors');
  html {
    @include tools.custom-props($my-colors, 'colors-');
  }

Since 4.0.0:

  • NEW: Initial release

Parameters & Output

$map: (string)

A map of keys and values to be converted into custom properties

$prefix: null (string | null)

Optional prefix added to each property name

{CSS output} (code block)

  • Custom properties for every key/value pair in a map.

Example

scss 
$colors: (
  'brand': mediumvioletred,
  'action': teal,
);

html {
  @include tools.custom-props($colors, 'colors-');
}
css compiled 
html {
  --colors-brand: mediumvioletred;
  --colors-action: teal;
}

Requires

@function ident()