Accoutrement 1.0.1

QuickStart: Core

The accoutrement tools are built around a shared data-storage syntax using Sass “map” objects. We can use maps to store and name our design tokens:

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

Import

If you already imported accoutrement/sass/tools you are ready to go. If you want to import the core alone:

  @import '<path-to>/accoutrement/sass/core';

If you’re using Eyeglass, you can leave off most of the path:

  @import 'accoutrement/core';

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 embeded 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.

Related

@function ratio()

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',
  ),
);

Related

@function interpolate()

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',
);