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.
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:
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
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
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.