Documenting ratios & sizes
Herman provides custom annotations
for visualizing sizes and ratios,
along with other design tokens.
See the sass.jsonFile configuration
to ensure that Herman has access
to your exported Sass data.
In addition to documenting colors and fonts, you can use Herman to document and display ratios and sizes. In the end, Herman will need a map – but we’ll start with individual ratios/sizes, and build the export from there.
Let’s start with a ratio and two sizes:
$line-height-ratio: 1.4;
$root: 18px;
$xlarge: 3rem;
$demo-ratios
$demo-ratios: (
'line-height': $line-height-ratio,
);Preview ratios
In order to export our ratios to Herman, we’ll want to combine them into maps of name/value pairs. Sass does not provide any shortcuts for automating this step, or removing the duplication, but you can use a tool like our Accoutrement to store and access ratios directly in a Herman-friendly map.
$demo-ratios: (
'line-height': $line-height-ratio
);
Create as many maps as you like
to organize different types of ratios –
text, spacing, etc.
Each map will be displayed individually,
using the @ratios annotation:
/// @ratios my-ratios
The @ratios annotation accepts an optional one-word key argument,
which defaults to the map-variable name.
That key will be used to access the data from JSON,
so it doesn’t matter what key is used,
as long as the key given here matches the group-name
used when adding this data to $herman.
Ratio line-height (1.4)
$demo-sizes-text
$demo-sizes-text: (
'root': $root,
'responsive': calc(1.5em + 1vw),
'xlarge': $xlarge,
);Preview sizes
Similar to ratios, sizes can be combined into any number of maps to preview with Herman. you can build these maps out of existing variables, or use a tool like our Accoutrement to store and access sizes directly in a Herman-friendly map.
$demo-sizes-text: (
'root': $root,
'xlarge': $xlarge
);
Each map will be displayed individually,
using the @sizes annotation:
/// @sizes {ruler}
The @sizes annotation accepts two optional arguments:
-
An optional one-word key argument, which defaults to the map-variable name. That key will be used to access the data from JSON, so it doesn’t matter what key is used, as long as the key given here matches the group-name used when adding this data to
$herman. -
An optional
styleargument (in curly-brackets{...}), defaulting totext, which specifies the type of output to display:text: Displays a sentence of lorem-ipsum text for each given size.ruler: Displays horizontal bars of the given sizes.ruler-large: Displays horizontal bars – each on their own line, for more visible space.output-only: Displays values only, without demonstration.
Text Sizes
/// @sizes demo-sizes-text {text}
Size Previews
Rulers
/// @sizes demo-sizes-theme {ruler}
Size Previews
Large Rulers
/// @sizes demo-sizes-large {ruler-large}
Size Previews
Name/Value Only
/// @sizes demo-sizes-text {output-only}
Size Previews
Add ratio/size data to $herman
In order to preview the $demo-ratios and $demo-sizes-* maps,
we also need to export the data to JSON.
You can add data to the $herman export-map by hand,
or use the provided add mixin
to combine existing maps into the proper structure.
See the size/ratio map documentation for details »
@include add('ratios', 'demo-ratios', $demo-ratios);
@include add('sizes', 'demo-sizes-text', $demo-sizes-text);
@include add('sizes', 'demo-sizes-theme', $demo-sizes-theme);
@include add('sizes', 'demo-sizes-large', $demo-sizes-large);
If your map needs to be parsed or compiled before export,
you can pass additional compilation functions and arguments to add.
Once your data is all stored in the $herman map,
it can be converted to JSON using export.