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
$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
$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
keyname for accessing this particular group of colors. Theaddkey should match the key provided to@colors. - The third argument provides the actual map of data
to be added to the
$hermanexport 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.
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%, 'adjust': ('saturation': -80%, 'space': hsl),),
'gray': '#brand-blue' ('adjust': ('saturation': -80%, 'space': hsl),),
'contrast-dark': '#brand-blue' ('shade': 30% #000, 'adjust': ('saturation': -80%, 'space': hsl),),
);
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
@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%, 'adjust': ('saturation': -80%, 'space': hsl),),
'gray': '#brand-blue' ('adjust': ('saturation': -80%, 'space': hsl),),
'black': '#brand-blue' ('shade': 30%, 'adjust': ('saturation': -80%, 'space': hsl),),
);
$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)} */
}/* colors: ("demo-noncolors": ("light-gray": rgb(221.85, 221.85, 221.85), "gray": hsl(195, 5%, 35%), "black": null)) */