Herman 6.0.1

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

$custom-property-colors

scss
$custom-property-colors: (
  'link': var(--herman-brand-blue),
  'link-action': var(--herman-brand-pink),
);

CSS custom properties

At OddBird, we convert color tokens into CSS custom properties using Accoutrement. These color values stored as custom properties can also be previewed as palettes.

In the $custom-property-colors map, we have created two new tokens, link and link-action, based on tokens stored in the $demo-colors map.

The values in the $demo-colors map have been converted to CSS custom properties (with an added herman- prefix) using Accoutrement’s colors--() mixin.

To display color values stored as custom properties, the custom properties must be declared on html, body, or :root in the stylesheet set as the herman.customPreviewCSS configuration option. If that option is not set, the herman.customCSS stylesheet will be used instead. Custom properties are read in the order they are defined in the stylesheet, so later properties will override earlier properties with the same name.

When displaying colors defined as CSS custom properties, the color name and variable name are displayed, but the herman.displayColors option is not used.

Color Previews

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

@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 'pkg:accoutrement' as tools;
// To import from Herman installed via npm,
// replace the following 'utilities' import with:
// @use 'pkg:sassdoc-theme-herman' as herman;
@use 'utilities' as herman;

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

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

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

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

Related

Accoutrement [external]

Color Previews