Accoutrement 4.0.3

Sass Accoutrement

Robust design systems require meaningful, readable, reusable code. These Sass utilities are designed to help define and manage your design tokens (colors, fonts, sizes, etc.) in a format that can be understood by both humans and parsers – opening the door for automation, while improving consistency and readability. These tools also integrate with Herman, our automated living pattern-library generator built on SassDoc.

Brought to you by OddBird – the creators of Susy, True, and Herman.

Installation

Install the package with npm or yarn

npm install accoutrement [--save-dev]
yarn add accoutrement [--dev]

Use what you need:

// all the modules (these are functionally the same)
@use '<path-to>/accoutrement';
@use '<path-to>/accoutrement/sass/tools';

// individual modules (at `/accoutrement/sass/<name>`)
@use '<path-to>/accoutrement/sass/color';

If you’re using Eyeglass, you can use the default “tools” using only:

@use 'accoutrement';

Modules for common data types

  • Utilities – For helpers with Sass lists, strings, and maps
  • Ratios – For managing aspect and typography ratios (several common ratios are provided)
  • Animate – For managing CSS transitions and animations
  • Color – For managing CSS colors and contrast-ratios
  • Layout – For managing CSS sizes: typographic scales, spacing, etc.
  • Scale – For managing CSS sizes: typographic scales, spacing, etc.
  • Type – For managing webfonts, generated content, and other text needs

Tokens

The Tokens module provides a special syntax for managing design tokens with Sass “map” objects:

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

Using the custom syntax, we can extend maps to handle internal reference, and functional adjustments – capturing meaningful relationships between design tokens:

$map: (
  'root': 16px,
  // internal reference & adjustments
  'gutter': '#root'
    (
      scale: '_major-third' 1,
      'convert-units': 'rem',
    ),
);

Map storage serves a larger purpose:

  • Related data is grouped explicitly, making the code more readable and maintainable
  • The “single source of truth” encourages reusable design patterns
  • Meaningful structure allows automation, from automated style guides to automated functionality

This module provides the generic (non data-specific) setup and syntax parsing:

Note: We no longer use token maps internally at OddBird since Sass “modules” now provide a way to group & namespace normal Sass variables meaningfully, and access module variables as a map. By relying on core Sass features, we avoid any confusion around the custom token syntax.