Scale Configuration
$sizes (map)
$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
$sizes: (
'root': 24px,
'text': '#root' ('convert-units': 'em'),
'h1': '#root' ('times': 2),
'calc': 'calc(%s + %s)' ('%s': '#root' 2vw),
);
@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
$text-sizes: (
'root': 24px,
'h1': '#root' ('times': 2),
);
@include tools.add-sizes($text-sizes);
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, butsize('root', 'em', 10px)
should be changed tosize('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.
@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, butsize('root', 'em', 10px)
should be changed tosize('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, butsize('root', 'em', 10px)
should be changed tosize('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.