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