Token Maps

We use “token” as a generic term for named values inside Accoutrement maps. In the following map, root and gutter are considered Accoutrement-tokens:

$map: (
  'root': 16px,
  'gutter': 1em,
);

Our core API provides token-map syntax parsing, and general token access with get() (below). Additional plugins provide shortcuts and utilities for managing and accessing common token-types, like colors, fonts, sizes, and animations.

Internal Reference

The core module provides a generic map-parsing syntax, for internal reference & adjustments – establishing dynamic relationships between map values. To reference another key in the same map, use the #tag hashtag format:

// 'gutter' == 16px
$map: (
  'root': 16px,
  'gutter': '#root',
);

Reference hashtags don’t have to stand alone, but can be embedded inside a longer string:

// 'responsive' == calc(16px + 1vw)
$map: (
  'root': 16px,
  'scale': 1vw,
  'responsive': 'calc(#root + #scale)',
);

Nested References

You can define nested tokens in Accoutrement maps, and access them using a #first->second->third syntax:

// 'large-screen->h2' == 24px
$sizes: (
  'root': 16px,
  'headings': (
    'h1': '#root' ('times': 2),
    'h2': '#root' ('times': 1.5),
  ),
  'pull-quote': '#headings->h2',
);

All -> nested references are resolved relative to the outermost map:

// 'large-screen->text' == 24px
$map: (
  'root': 16px,
  'large-screen': (
    'root': 24px,
    'text': '#large-screen->root'
  ),
);

Functional Adjustments

In many cases, we’ll want to reference a value and then make adjustments to it. The explicit long-hand syntax uses a map with '%value' as the first key. Each additional key provides a function name along with arguments for that function:

// convert-units(16px, 'rem')
$map: (
  'root': 16px,
  'gutter': (
    '%value': '#root',
    'times': 1.5,
    'convert-units': 'rem',
  ),
);

You can also string together multiple functions, to create more complex relationships:

// convert-units(times(16px, 1.5), 'rem')
$map: (
  'root': 16px,
  'gutter': (
    '%value': '#root',
    'times': 1.5,
    'convert-units': 'rem',
  ),
);

Each function in the function map (e.g. times & convert-units above) will be run in order – with any associated arguments included. The value is always passed as the first argument.

Adjustment Shorthand

We also provide a shorthand syntax to simplify adjustments in most cases. Here, the value is written first (any data type), and a map of adjustments can be provided at the end of the definition:

$map: (
  'root': 16px,
  'gutter': '#root' ('times': 1.5, 'convert-units': 'rem'),
);

Adjustments with References

Adjustment-function arguments can also reference keys in the map. In this example, we’re multiplying the root & line-height values to generate a rhythm token.

$map: (
  'root': 16px,
  'line-height': 1.4,
  'rhythm': '#root' ('times': '#line-height'),
);

String Interpolation

For CSS features like calc() you can create format-strings and interpolate values into the string. Use %s as a placeholder, and call the interpolate (or %s) adjustment function with replacement values for each placeholder:

$map: (
  'root': 16px,
  'scale': 1vw,
  'responsive': (
    '%value': 'calc(%s + %s)',
    '%s': '#root' '#scale',
  ),
);

Nested Adjustments

Since adjustment formats and values are parsed the same as any other value, it’s possible to build quite complex adjustments:

$map: (
  'root': 16px,
  'scale': 1vw,
  'responsive': (
    '%value': 'calc(%s + %s)',
    '%s': (
      '#root' ('convert-units': 'rem'),
      '#scale' ('times': 2),
    ),
  ),
);

Escaping References

• If you need to use the # character without creating an alias reference, you can prefix it with an (also-escaped) back-slash: 'this is \\#not-an-alias'
• If you need to end an alias without using punctuation or spaces, the same double-escape can be used: '#alias\\not-part-of--alias'