(Alpha) Nested Tokens, Private Tokens, & Custom Properties

• Core:
  • NEW: $adjust-query-overlap (max | min | false)
    allows you to control if and how media-queries are adjusted
    to avoid overlap between min/max queries
    (thanks to @biw-joelschou)
  • NEW: Support for integrating accoutrement tokens & CSS variables
    with tokens--(), token--(), var-token(),
    and plugin-specific shortcuts
  • BREAKING: Token names starting with _ or -
    are considered "private" to Sass,
    and will not be output when auto-generating CSS
    (variables, font-names, etc.)
  • BREAKING: Default ratio tokens are now prefixed with _
    (search/replace e.g. minor-third -> _minor-third)
    to avoid CSS-variable output
  • NEW: is-private-token() and is-alias-for() are now public functions,
    to help with token-inspection
  • BREAKING: Support for nested-map tokens with -> syntax,
    both in #hash->references and get-token($source, 'function->calls')
    (thanks to @biw-joelschou)
• Plugin: Animate
  • BREAKING: Default easing tokens are now prefixed with _
    (search/replace e.g. in-out-quad -> _in-out-quad)
    to avoid CSS-variable output
  • NEW: Support for easing CSS variables with
    easing--(), ease--(), and var-ease()
  • NEW: Support for time CSS variables with
    times--(), time--(), and var-time()
  • NEW: Support for change CSS variables with
    changes--(), change--(), and var-change()
• Plugin: Color
  • BREAKING: _contrast-light and _contrast-dark colors are used
    for mixing tint() and shade(),
    with optional $light/$dark override parameters
    (thanks to @biw-joelschou)
  • NEW: Default _contrast-light and _contrast-dark provided,
    set _contrast-light/dark in $colors to override
  • NEW: Support for CSS Variables with
    colors--(), color--(), and var-color()
• [Plugin: Layout][layout]
  • BREAKING: Default ratio tokens are now prefixed with _,
    see core for details
• Plugin: Scale
  • BREAKING: Default ratio tokens are now prefixed with _,
    see core for details
  • NEW: Support for size CSS Variables with
    sizes--(), size--(), and var-size()
  • NEW: Support for ratio variables with
    ratios--(), ratio--(), and var-ratio()
• Plugin: Type
  • BREAKING: Non-map fonts are interpreted as font-stacks
  • BREAKING: Normalized font-data uses proper name-quotation,
    and ignores missing or private names/stacks
  • BREAKING: import-webfonts() no longer imports private fonts,
    but will import a direct alias of the private font
  • NEW: import-webfonts() accepts $source parameter
  • NEW: Support for CSS Variables with
    fonts--(), font--(), and var-font()

Typos & Nested Map Bug

• BUGFIX: Typos, including the cinema ratio spelling
• BUGFIX: Improved consistency of nested-map parser

Thanks to @biw-joelschou

Accoutrement Launch!

There are a number of changes from the old, individual Accoutrement modules – merging the syntax for all Accoutrement maps into a single, more explicit and flexible, format:

Internal Reference

The core module provides a generic map-parsing syntax,
for internal reference & adjustments --
establishing dynamic relationships between map values.
To refernce another key in the same map,
use the #tag hashtag format:

$map: (
  'root': 16px,
  // 'gutter' == 16px
  'gutter': '#root',
);

Reference hashtags don't have to stand alone,
but can be embedded inside a longer string:

$map: (
  'root': 16px,
  'scale': 1vw,
  // 'responsive' == calc(16px + 1vw)
  'responsive': 'calc(#root + #scale)',
);

Nested maps will compare #tags internally,
before looking at the parent keys:

$map: (
  'root': 16px,
  'large-screen': (
    'root': 24px,
    // 'alias' == 24px
    'alias': '#root'
  ),
);

Functional Adjustments

In many cases, we'll want to reference a value
and then make adjustments to it.
The explicit long-hand syntax uses a map
with 'value' as the first key.
Each additional key provides a function name
along with arguments for that function:

$map: (
  'root': 16px,
  // convert-units(16px, 'rem')
  'gutter': (
    'value': '#root',
    'times': 1.5,
    'convert-units': 'rem',
  ),
);

You can also string together multiple functions,
to create more complex relationships:

$map: (
  'root': 16px,
  // convert-units(times(16px, 1.5), 'rem')
  'gutter': (
    'value': '#root',
    'times': 1.5,
    'convert-units': 'rem',
  ),
);

Each function in the function map
(e.g. times & convert-units above)
will be run in order --
with any associated arguments included.
The value is always passed as the first argument.

Modular-Scale Adjustments

When managing numbers,
you can also move up and down exponential modular-scales
by calling a named ratio
in place of a function name.
Scales are exponential:

$map: (
  'root': 16px,
  // manipulating a 'value' with function & scale adjustments:
  'gutter': (
    'value': '#root',
    'convert-units': 'rem',
    // one step up a 'major third' scale (5 / 4)
    'major-third': 1,
  ),
);

Multiple functions/ratios
will be applied in the order they are given.

Adjustment Shorthand

We also provide a shorhand syntax
to simplify adjustments in most cases.
Here, the value is written first (any data type),
and a map of adjustments can be provided
at the end of the definition:

$map: (
  'root': 16px,
  // shorthand for value/adjustments
  'gutter': '#root' ('major-third': 1, 'convert-units': 'rem'),
);

Adjustments with #References

Adjustment-function and ratio arguments
can also refernce keys in the map:

$map: (
  'root': 16px,
  'line-height': 1.4,
  // multiply by line-height (linear)
  'rhythm': '#root' ('times': '#line-height'),
  // 2-steps up the (exponential) line-height scale
  'gutter': '#root' ('#line-height': 2),
);

String Interpolation

For CSS features like calc()
you can also create format-strings
and interpolate values into the string.
Use %s as a placeholder in Sass strings,
then call the %s adjustment function
with values for each placeholder:

$map: (
  'root': 16px,
  'scale': 1vw,
  'responsive': (
    'value': calc(%s + %s),
    '%s': '#root' '#scale',
  ),
);

Nested Adjustments

Since adjustment formats and values
are parsed the same as any other value,
it's possible to build quite complex adjustments:

$map: (
  'root': 16px,
  'scale': 1vw,
  'responsive': (
    'value': calc(%s + %s),
    '%s': (
      '#root' ('convert-units': 'rem'),
      '#scale' ('times': 2),
    ),
  ),
);

Included & Third-Party Functions

We provide a core set of
math utilities,
named scales,
and list/string helpers --
prefixed to avoid conflict,
but available unprefixed inside data maps.
You can also register functons of your own,
or pass along functions from other Sass modules --
giving them any alias you like.

$functions: (
  // register any functions…
  'my-function': get-function('my-function'),
  // including Sass core functions…
  'rgba': get-function('rgba'),
  // provide alias names…
  'mine': '#my-function',
);

Functions can also be registered
with the register-function() mixin:

@include register-function('rgba', 'alias1', 'alias2', 'etc');

Minor size() Bugfix

• Plugin: Scale
  • BUGFIX: size() function removes quotes from string (calc) sizes

Improved flexibility with $do and $source args

• Core:
  • NEW: ratio() function accepts $source argument,
    for passing in a custom source map
  • NEW: Improved error-handling and messages
  • NEW: Added str-trim and str-split aliases
    in addition to the existing trim and split
• Plugin: Animate
  • NEW: ease(), time(), and change() functions all
    accept $source argument,
    for passing in a custom source map
• Plugin: Layout
  • NEW: break() function accepts $source argument,
    for passing in a custom source map
  • NEW: break() function accepts $scale boolean,
    to turn off access to the scale-plugin $sizes map
  • NEW: fluid-ratio() function and mixin both accept $source argument,
    for passing in a custom source map
• Plugin: Scale
  • BREAKING: negative() function and square() mixin
    both accept $do argument for on-the-fly adjustments --
    replacing the old $units… variable argument.
    Non-map $do values are converted to
    ('convert-units': $do) before processing,
    to provide a shortcut for unit-conversions.
    negative('root', 'cm') will continue to work,
    but negative('root', 'em', 10px) should be changed to
    negative('root', 'em' 10px) (with all unit args in a single list)
  • NEW: size()/negative() functions and square() mixin
    accept $source argument, for passing in a custom source map
• Plugin: Type
  • NEW: font()/font-family() functions
    and font-family()/font-face() mixins
    accept $source argument,
    for passing in a custom font-source map

Eyeglass import, `$do`, and `font()`

• NEW: Add _index.scss to simplify default "tools" import (core + plugins) in Eyeglass: @import 'accoutrement';
• Core:
  • NEW: get-token() and ratio() functions accept $do argument, for on-the-fly adjustments
  • NEW: trim($string) utility now available in map-syntax, to trim white-space from the start and end of a string
  • NEW: str-replace() utility now forces arguments to string-type when appropriate, allowing e.g. calc(16px + 1vw) ('str-replace': 1vw 2vw)
• Plugin: Animate
  • NEW: change(), time(), and ease() functions all accept $do arg for on-the-fly adjustments
• Plugin: Color
  • BREAKING: color() functions accept $do arg for on-the-fly adjustments – before existing $palette argument
• Plugin: Layout
  • NEW: break() function accept $do arg for on-the-fly adjustments
• Plugin: Scale
  • BREAKING: size() function $units… variable argument has been replaced with $do map argument, for flexible on-the-fly adjustments. Non-map $do values are converted to ('convert-units': $do) before processing, to provide a shortcut for unit-conversions. size('root', 'cm') will continue to work, but size('root', 'em', 10px) should be changed to size('root', 'em' 10px) (with all unit args in a single list)
• Plugin: Type
  • BREAKING: import-webfonts() mixin no longer accepts any arguments
  • NEW: font() function provides access to parsed font-data
  • NEW: 'trim' string helper strips whitespace from the start and end of a string
  • NEW: Improved font-normalization handles more font-map edge-cases
  • NEW: Font-stacks can be written as comma-delimited strings, e.g. 'Helvetica Neue, Helvetica, Arial' or 'Helvetica Neue, Helvetica, Arial'

Initial merged release

• Merges all existing Accoutrement plugins: Color, Init, Layout, Scale, and Type
• NEW: Animate plugin
• NEW: Core functionality and utilities
• BREAKING: All modules now use a shared map syntax, with explicit #tag references and the option for explicit value/adjustment maps. Learn the new syntax.

(broken links will be fixed shortly, once we publish the docs…)