QuickStart: Core
All the Accoutrement tools are built around a shared syntax, using Sass Maps to define “tokens” of various types:
$sizes: (
'root': 16px,
'gutter': 1em,
);
Tokens provide design abstractions, that can be easily reused across a product or design system. There are several reasons for this approach:
- Sass Maps provide a format that is readable by both humans & machines
- All related values are stored in a single variable, with explicit relationships intact
- We can build automation tools around meaningful token-groups, from font-imports to generated style guides
- Unlike
YAML
,JSON
, and other object languages, Sass is a style language that understands the values involved, and provides specific tools for maintaining those values
Import
If you already imported accoutrement/sass/tools
you are ready to go.
If you want to import the core alone:
@import '<path-to>/accoutrement/sass/core';
If you’re using Eyeglass, you can leave off most of the path:
@import 'accoutrement/core';
Token Maps
Using the map syntax, we can create named tokens for any related values:
$colors: (
'brand': rgb(13, 127, 165),
'text': black,
);
We can also create alias tokens
and explicit relationships,
using a #token
hashtag syntax:
$colors: (
'brand': rgb(13, 127, 165),
'accent': '#brand',
'text': '#accent' ('shade': 75%),
);
Those relationships will be calculated at compile-time,
using the get-token()
function
(or shortcut functions provided by plugins):
:root: (
color: get-token($colors, 'text');
);
See Token Maps documentation for more detail.
Related
@function get-token()
Tokens » CSS Variables
CSS Variables provide a DOM-aware alternative to the pre-processed Sass variables we use to store tokens. Rather than using one or the other, we recommend defining tokens in Sass (where relationships can be stored in an abstract format), and then generating CSS Variables as-necessary.
See CSS Variables documentation for more detail.
Example
$colors: (
'_brand': hsl(120, 50%, 50%),
'text': '#_brand' ('shade': 50%),
'border': '#text',
);
:root {
// generate CSS Variables based on the map above…
@include tokens--($colors);
// access CSS Variables with smart fallbacks…
border-color: var-token($colors, 'border');
color: var-token($colors, 'text');
}
:root {
--text: #206020;
--border: var(--text, #206020);
border-color: var(--border, #206020);
color: var(--text, #206020);
}
Ratios
Since ratios are used by multiple plugins, we provide relevant defaults & shortcuts in the core:
$ratios: (
'line-height': (1 / 3),
'_golden': 1.61803399,
);
:root {
line-height: ratio('line-height');
}
See Layout & Type Ratios documentation for more detail.
Utility Functions
We provide a core set of math utilities, list, and string helpers – prefixed to avoid conflict, but available un-prefixed inside token maps.
You can also register your own functions, or pass along functions from other Sass modules – giving them any alias you like. This is all handled using the token-map syntax.
// Create a token-map of captured functions
$functions: (
'my-function': get-function('my-function'),
'rgba': get-function('rgba'),
'mine': '#my-function',
);
// Or add functions & aliases using the provided mixin:
@include register-function('my-function', 'alias');
Once a function has been registered with accoutrement, it is available to call by name or alias in all token adjustment maps:
@include register-function('rgba', 'fade');
$colors: (
'brand': hsl(120, 50%, 50%),
'background': '#brand' ('fade': 50%),
);