Accoutrement Launch!

There are a number of changes from the old, individual Accoutrement modules – merging the syntax for all Accoutrement maps into a single, more explicit and flexible, format:

Internal Reference

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

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

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

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

Nested maps will compare #tags internally,
before looking at the parent keys:

$map: (
  'root': 16px,
  'large-screen': (
    'root': 24px,
    // 'alias' == 24px
    'alias': '#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:

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

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

$map: (
  'root': 16px,
  // convert-units(times(16px, 1.5), 'rem')
  '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.

Modular-Scale Adjustments

When managing numbers,
you can also move up and down exponential modular-scales
by calling a named ratio
in place of a function name.
Scales are exponential:

$map: (
  'root': 16px,
  // manipulating a 'value' with function & scale adjustments:
  'gutter': (
    'value': '#root',
    'convert-units': 'rem',
    // one step up a 'major third' scale (5 / 4)
    'major-third': 1,
  ),
);

Multiple functions/ratios
will be applied in the order they are given.

Adjustment Shorthand

We also provide a shorhand 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,
  // shorthand for value/adjustments
  'gutter': '#root' ('major-third': 1, 'convert-units': 'rem'),
);

Adjustments with #References

Adjustment-function and ratio arguments
can also refernce keys in the map:

$map: (
  'root': 16px,
  'line-height': 1.4,
  // multiply by line-height (linear)
  'rhythm': '#root' ('times': '#line-height'),
  // 2-steps up the (exponential) line-height scale
  'gutter': '#root' ('#line-height': 2),
);

String Interpolation

For CSS features like calc()
you can also create format-strings
and interpolate values into the string.
Use %s as a placeholder in Sass strings,
then call the %s adjustment function
with 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),
    ),
  ),
);

Included & Third-Party Functions

We provide a core set of
math utilities,
named scales,
and list/string helpers --
prefixed to avoid conflict,
but available unprefixed inside data maps.
You can also register functons of your own,
or pass along functions from other Sass modules --
giving them any alias you like.

$functions: (
  // register any functions…
  'my-function': get-function('my-function'),
  // including Sass core functions…
  'rgba': get-function('rgba'),
  // provide alias names…
  'mine': '#my-function',
);

Functions can also be registered
with the register-function() mixin:

@include register-function('rgba', 'alias1', 'alias2', 'etc');