accoutrement

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.

• Official Site
• Documentation
• Source Code
• Issues

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:

• Retrieve & parse map values with token.get() and other token api functions
• Use the many registered functions to manipulate tokens in the map
• Register your own functions, for extra functionality

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.