QuickStart: Core

All the Accoutrement tools are built around a shared syntax, using Sass Maps to define “tokens” of various types:

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

Tokens provide design abstractions, that can be easily reused across a product or design system. There are several reasons for this approach:

• Sass Maps provide a format that is readable by both humans & machines
• All related values are stored in a single variable, with explicit relationships intact
• We can build automation tools around meaningful token-groups, from font-imports to generated style guides
• Unlike YAML, JSON, and other object languages, Sass is a style language that understands the values involved, and provides specific tools for maintaining those values

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

Token Maps

Using the map syntax, we can create named tokens for any related values:

$colors: (
  'brand': rgb(13, 127, 165),
  'text': black,
);

We can also create alias tokens and explicit relationships, using a #token hashtag syntax:

$colors: (
  'brand': rgb(13, 127, 165),
  'accent': '#brand',
  'text': '#accent' ('shade': 75%),
);

Those relationships will be calculated at compile-time, using the get-token() function (or shortcut functions provided by plugins):

:root: (
  color: get-token($colors, 'text');
);

See Token Maps documentation for more detail.

Tokens » CSS Variables

CSS Variables provide a DOM-aware alternative to the pre-processed Sass variables we use to store tokens. Rather than using one or the other, we recommend defining tokens in Sass (where relationships can be stored in an abstract format), and then generating CSS Variables as-necessary.

See CSS Variables documentation for more detail.

Ratios

Since ratios are used by multiple plugins, we provide relevant defaults & shortcuts in the core:

$ratios: (
  'line-height': (1 / 3),
  '_golden': 1.61803399,
);
:root {
  line-height: ratio('line-height');
}

See Layout & Type Ratios documentation for more detail.

Utility Functions

We provide a core set of math utilities, list, and string helpers – prefixed to avoid conflict, but available un-prefixed inside token maps.

You can also register your own functions, or pass along functions from other Sass modules – giving them any alias you like. This is all handled using the token-map syntax.

  // Create a token-map of captured functions
  $functions: (
    'my-function': get-function('my-function'),
    'rgba': get-function('rgba'),
    'mine': '#my-function',
  );
  // Or add functions & aliases using the provided mixin:
  @include register-function('my-function', 'alias');

Once a function has been registered with accoutrement, it is available to call by name or alias in all token adjustment maps:

  @include register-function('rgba', 'fade');
  $colors: (
    'brand': hsl(120, 50%, 50%),
    'background': '#brand' ('fade': 50%),
  );