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:

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.

At OddBird, we love contributing to the languages & tools developers rely on. We’re currently working on polyfills for new Popover & Anchor Positioning functionality, as well as CSS specifications for functions, mixins, and responsive typography. Help us keep this work sustainable and centered on your needs as a developer! We display sponsor logos and avatars on our website.

Sponsor OddBird’s OSS Work