Accoutrement 4.0.4

Scale Configuration

$sizes (map)

scss 
$sizes: (
  'root': $accoutrement-browser-default-font-size,
) !default;

Define a palette of common sizes to be used across your project, in the format “name: size” or “name: basis (ratio/function: value)”. If your map includes a px-comparable value for root, it will be used in relative-size unit conversions.

Named sizes can contain length values (24px), references to previously-defined sizes ('root'), a map of relative-adjustments using ratios ((scale: '_golden' 2)) and math functions (('plus': 2)), or a format-string & list for interpolating calc() values ('calc(%s + %s)' ('#root', 2vw)).

Internal math functions are always available by name, but recent versions of Sass require you to capture 3rd-party functions using the get-function($name) syntax before calling them. To simplify your maps, we recommend using the $functions map to store captured functions in one place, where we can continue to retrieve them by name.

Map Properties

'root': 16px (Map)

Include a root font-size for your document, used for calculating relative sizes. This should match the size applied to your html element.

Example

scss 
$sizes: (
  'root': 24px,
  'text': '#root' ('convert-units': 'em'),
  'h1': '#root' ('times': 2),
  'calc': 'calc(%s + %s)' ('%s': '#root' 2vw),
);

Used By

@function break()

@mixin add-sizes()

@function convert-units()

@mixin add-sizes()

Merge individual size maps into the global $sizes variable, in case you want to define sizes in smaller groups such as text-sizes, spacing-sizes, etc before merging them into a single global size-palette. This can be useful for internal organization, documentation with SassDoc, or integration with our pattern-library generator: Herman.

Parameters & Output

$maps: (map...)

Pass any number of maps to be merged.

{CSS output} (code block)

  • An updated global $sizes variable, with new maps merged in.

Example

scss 
$text-sizes: (
  'root': 24px,
  'h1': '#root' ('times': 2),
);
@include tools.add-sizes($text-sizes);

Requires

@function multi-merge()

$sizes (map)

Accessing Sizes

@function size()

Access a named size in your $sizes map, using any comparable units.

Since 1.0.0:

  • BREAKING: The previous $units… vararg 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)
  • NEW: Accepts $source map argument, for custom source-palette

Parameters & Return

$size: (string)

The name of any size in your configuration

$do: null (map | unit-args | null)

A map of function/ratio adjustments to run on the returned value, or a unit followed by any necessary arguments for conversion

$source: $sizes (map)

Optional Accoutrement-format map of sizes to use as the origin palette

@return (length)

The calculated length, in the requested units.

Requires

@function compile()

@function get() [private]

Used By

@function scale()

@function negative()

@mixin square()

@function convert-units()

@function compile-sizes()

Compile all the tokens in a size map. This is particularly useful for exporting a static version of the token map with all the Accoutrement syntax removed – e.g. for use in javascript or documentation.

Since 4.0.0:

  • NEW: Provides an export option for size token maps

Parameters & Return

$map: $sizes (map)

The map to be compiled

$source: $sizes (map | null)

A map of reference tokens that can be used for resolving sizes. (defaults to the global $sizes map)

@return (map)

A copy of the original map, with all token values resolved

Requires

@function map-compile-with()

@function negative()

Return the inverse value of any length, in comparable units.

Since 1.0.0:

  • BREAKING: The previous $units… vararg 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)
  • NEW: Accepts $source map argument, for custom source-palette

Parameters & Return

$size: (string | length | list)

The name of a size in your configuration (e.g. line-height), or a length to be converted into different units (e.g. 24px), or a base-size and adjustments to be made (e.g. 24px (scale: '_minor-third' 2)). For the sake of consistent documentation, I recommend keeping adjustments in the configuration whenever possible.

$do: null (map | unit-args | null)

A map of function/ratio adjustments to run on the returned value, or a unit followed by any necessary arguments for conversion

$source: $sizes (map)

Optional Accoutrement-format map of sizes to use as the origin palette

@return (length)

The calculated negative length, in the requested units.

Requires

@function size()

@mixin square()

Create a square by setting equal CSS height and width properties with the given size & unit value.

Since 1.0.0:

  • BREAKING: The previous $units… vararg 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)
  • NEW: Accepts $source map argument, for custom source-palette

Parameters & Output

$size: (string | length | list)

The name of a size in your configuration (e.g. line-height), or a length to be converted into different units (e.g. 24px), or a base-size and adjustments to be made (e.g. 24px ('_minor-third': 2)). For the sake of consistent documentation, I recommend keeping adjustments in the configuration whenever possible.

$do: null (map | unit-args | null)

A map of function/ratio adjustments to run on the returned value, or a unit followed by any necessary arguments for conversion

$source: $sizes (map)

Optional Accoutrement-format map of sizes to use as the origin palette

{CSS output} (code block)

  • Equal CSS height and width properties, set to the given size and units.

Requires

@function size()