README.md

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]

Import what you need:

// core and all plugins (also available with `/index`)
@import '<path-to>/accoutrement/sass/tools';

// init normalization
@import '<path-to>/accoutrement/sass/init';

// individual plugins (core is required)
@import '<path-to>/accoutrement/sass/core';
@import '<path-to>/accoutrement/sass/plugin/<name>';

If you're using Eyeglass, you can import the default "tools" (core + plugins) using only:

@import 'accoutrement';

Usage

The accoutrement tools are built around a shared data-storage syntax using Sass "map" objects:

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

Using a 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' ('_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 (provided in the plugins)

Core

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

• Retrieve & parse map values with the generic get-token() function
• Use our built-in math, modular-scale, list, and string utilities
• Register your own first class functions, for reference inside data maps

Init

We provide light-weight browser-normalization, as a distinct include. This is not part of the accoutrement/sass/tools package because it is the only module to produce direct CSS output.

Plugins…

While the core module handles generic data-management, we also provide plugins for a few common data types:

• Animate -- Tools for managing CSS transitions and animations
• Color -- Tools for managing CSS colors and contrast-ratios
• Scale -- Tools for managing CSS sizes: typographic scales, spacing, etc.
• Type -- Tools for managing webfonts, generated content, and other text needs