Herman 2.0.0

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

scss
$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-Scale 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)

-3 0.36
 
-2 0.51
 
-1 0.71
 
base
 
1 1.4
 
2 1.96
 
3 2.74
 

$demo-sizes

scss
$demo-sizes: (
  'root': $root,
  '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-Scale to store and access sizes directly in a Herman-friendly map.

$demo-sizes: (
  '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 style argument (in curly-brackets {...}), defaulting to text, 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}

Size Previews

root 18px Pack my box with five dozen liquor jugs.
xlarge 3rem Pack my box with five dozen liquor jugs.

Rulers

/// @sizes demo-sizes {ruler}

Size Previews

root 18px
 
xlarge 3rem
 

Large Rulers

/// @sizes demo-sizes {ruler-large}

Size Previews

root 18px
 
xlarge 3rem
 

Name/Value Only

/// @sizes demo-sizes {output-only}

Size Previews

root 18px
xlarge 3rem

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 herman-add mixin to combine existing maps into the proper structure. See the size/ratio map documentation for details »

 @include herman-add('ratios', 'demo-ratios', $demo-ratios);
 @include herman-add('sizes', 'demo-sizes', $demo-sizes);

If your map needs to be parsed or compiled before export, you can pass additional compilation functions and arguments to herman-add. Once your data is all stored in the $herman map, it can be converted to JSON using herman-export.

Related

Accoutrement-Scale [external]

@mixin herman-add()