Accoutrement 4.0.4

Ratio Tokens

All the tools you need to define and access ratios using the token syntax.

Import

If you’ve already imported accoutrement you are ready to go. You can also import the ratio module on its own:

  @use '<path-to>/accoutrement/sass/ratio';

$ratios (map)

scss 
$ratios: () !default;

Define your own ratios, or alias built-in named ratios (all provided names are prefixed with _ in token maps).

Example

scss 
tools.$ratios: (
  'line-height': calc(1 / 3),
  'hero': 1.778,
  'card': '#_golden',
);

Used By

@mixin add-ratios()

@function ratio()

Retrieve a scale ratio by name from either the $named-ratios or user $ratios configurations.

Since 1.0.0:

  • NEW: Accepts $do map argument, for on-the-fly adjustments
  • NEW: Accepts $source map argument, for custom source-palette

Parameters & Return

$ratio: (string | number)

The key-name or value of a ratio

$do: null (map | null)

A map of function/ratio adjustments to run on the returned value

$source: $ratios (map)

Optional Accoutrement-format map of ratios to use as the origin palette (in addition to the provided defaults)

@return (number)

The numeric value of a ratio

Example

scss 
/* _octave: #{tools.ratio('_octave')} */
/* _fifth: #{tools.ratio('_fifth')} */
css compiled 
/* _octave: 2 */
/* _fifth: 1.5 */

Requires

@function get() [private]

$named-ratios

Used By

@function is-ratio()

@mixin add-ratios()

Merge individual ratio maps into the global $ratio variable. 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 $ratios variable, with new maps merged in.

Requires

@function multi-merge()

$ratios (map)

@function compile-ratios()

Compile all the tokens in a ratio 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 ratio token maps

Parameters & Return

$map: $ratios (map)

The map to be compiled

$source: $ratios (map | null)

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

@return (map)

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

Requires

@function map-compile-with()

@function is-ratio()

Check to see if a ratio is valid, converting tokens in the process.

Since 4.0.0:

  • NEW: Provides type-checking of ratios in addition to converting ratio tokens.

Parameters & Return

$ratio: (string | number)

The key-name or value of a ratio

$source: $ratios (map)

Optional Accoutrement-format map of ratios to use as the origin palette (in addition to the provided defaults)

$allow-tokens: true (bool)

Optionally turn off token-parsing.

@return (number | 'linear' | false)

The numeric value of a ratio, the ‘linear’ keyword, or false if the value is not a valid ratio.

Example

scss 
/* _octave: #{tools.is-ratio('_octave')} */
/* 1.4: #{tools.is-ratio(1.4)} */
/* linear: #{tools.is-ratio('linear')} */
/* blue: #{tools.is-ratio(blue)} */
css compiled 
/* _octave: 2 */
/* 1.4: 1.4 */
/* linear: linear */
/* blue: false */

Requires

@function check() [private]

@function ratio()

Used By

@function scale()