Herman 5.0.0-beta.0

Documenting colors

Herman provides custom annotations for visualizing color palettes, along with other design tokens. See the sass.jsonFile configuration to ensure that Herman has access to your exported Sass data.

Whether you store colors as individual variables or group them into a map, you can use Herman to document and display color palettes. In the end, Herman will need a map converted to JSON – but we’ll start with individual colors, and build the export from there.

For this demo, we’ve defined two brand colors:

$brand-blue: hsl(195, 85%, 35%);
$brand-pink: hsl(330, 85%, 48%);

$demo-colors

scss 
$demo-colors: (
  'brand-blue': $brand-blue,
  'brand-pink': $brand-pink,
);

Preview color maps as palettes

In order to export our colors to Herman, we’ll want to combine them into a map 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 colors directly in a Herman-friendly map.

Create as many maps as you like to organize different palettes – primary, secondary, button-colors, etc. Each map will be displayed individually, using the @colors annotation:

/// @colors

The @colors annotation accepts an optional one-word key argument, which defaults to name of the code being documented (that is, the name of the variable/function/mixin on the first line after the /// SassDoc documentation). 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.

/// @colors my-colors

By default, our color palettes display name, hex, rgb(a), and hsl(a) for every color. You can change what color values are shown in the SassDoc/Herman configuration using the herman.displayColors option:

herman:
  displayColors:
    - hex
    - hsl

Color Previews

brand-blue hsl(195deg, 85%, 35%)
brand-pink hsl(330deg, 85%, 48%)

Add color-data to $herman

In order to preview the $demo-colors palette, we need to export the data to JSON. That’s a two-step process: first building the export-map, and then creating a sass file to do the actual export. We provide shortcuts to help with both.

Use the add mixin to add individual data maps to the global export map.

 @include add('colors', 'demo-colors', $demo-colors);
  • The first argument tells Herman what type of data is being added – in this case colors. Herman will organize the output JSON into subgroups by type. We use this to our advantage, passing the exported colors to application-js as well as Herman, so colors defined in Sass can be accessed in JavaScript.
  • The second argument sets a key name for accessing this particular group of colors. The add key should match the key provided to @colors.
  • The third argument provides the actual map of data to be added to the $herman export map.

The result is an export map that looks like this:

$herman: (
  'colors': (
    'demo-colors': (
      'brand-blue': hsl(195, 85%, 35%),
      'brand-pink': hsl(330, 85%, 48%),
    ),
  ),
);

You can also build that map by hand, if you prefer.

See the color map documentation for details »

Related

$herman

@mixin add()

Compile and export complex maps

At OddBird, we store our colors in more complex maps, where the values need to be parsed and compiled before they can be exported to Herman. Using accoutrement, our maps look like this:

$demo-noncolors: (
  'light-gray': '#brand-blue' ('tint': 80%, 'desaturate': 80%),
  'gray': '#brand-blue' ('desaturate': 80%),
  'contrast-dark': '#brand-blue' ('shade': 30% #000, 'desaturate': 80%),
);

Our color() function knows how to interpret that syntax and compile actual colors based on our map notation. In order to export real color data to Herman, we want to run every value in our map through the color function before exporting. While Accoutrement has that functionality built in, you can also use the each-key or each-value utilities to pass each map key or value through a given function. Provide a function name (Sass 3.4-), or first-class function (Sass 3.5+) along with any additional arguments required for that function.

Example

scss 
@use 'sass:meta';
@use '~accoutrement/sass/tools';
@use 'utilities';

utilities.$herman: ();
$demo-noncolors: (
  'light-gray': '#brand-blue' ('tint': 80%, 'desaturate': 80%),
  'gray': '#brand-blue' ('desaturate': 80%),
  'black': '#brand-blue' ('shade': 30%, 'desaturate': 80%),
);

$compiled: utilities.each-key(
  $demo-noncolors,
  meta.get-function('color', $module: 'tools'),
);

@include utilities.add(
  'colors', 'demo-noncolors', $compiled,
);

@each $key, $value in utilities.$herman {
/* #{$key}: #{meta.inspect($value)} */
}
css compiled 
/* colors: ("demo-noncolors": ("light-gray": #dedede, "gray": #555b5e, "black": null)) */

Related

Accoutrement [external]

Color Previews

light-gray #dedede hsl(0, 0%, 87%)
gray #555b5e hsl(200, 5%, 35%)
contrast-dark #3b4042 hsl(197, 6%, 25%)