This is a bit of documentation I wrote for a Sass mixin that outputs utility classes based on a map of values.
While our colors and other values should come from our design tokens (which only contain colors and font families and line height at the moment), there are many instances where either the design does not match or we haven’t created the token yet, so there is a need to create new utilities on a case by case basis, outside of what’s provided in tokens. The basic-utility-generator is good for that!
We also have a token-utility-generator that perhaps I will share another time. On to the docs!
Basic Utility Generator
The basic utility generator will generate utility classes based on a map of values. See the source here.
@mixin basic-utility-generator(
$property (string),
$values (list),
$map-containing-values (map)
);Setting Up Values
Before building UI, it is recommended to assemble all color values that do not fit into tokens (example tokens for ArtNews), in a Sass map in src/scss/00-settings/colors.scss.
Here is an example of handling color values that do not fit exactly into tokens – color-magenta is totally outside of tokens, color-brand-primary-faded is a modification of a token.
$colors-map: (
'color-magenta': #913769,
'color-brand-primary-faded': lighten( map-get( $TOKENS-MAP, color-brand-primary ), 20% )
);The name of the output class will be u-$KEY, so it is recommended to include the property name in the key of the map for readability.
Each map should consist only of values relevant to a specific property e.g. color-magenta should not be in a $background-colors-map, but background-color-magenta: map-get( color-magenta, colors-map ) is an acceptable entry.
Using the generator
Make sure the variables file is included in src/scss/setup.scss, and then add the following to the utility file to use the generator:
// In src/scss/03-utilities/u-color.common.async.scss
@import 'setup';
@include basic-utility-generator( 'color', (
'color-magenta',
'color-brand-primary-faded',
), $colors-map );
This will output the utilities u-color-magenta and u-color-brand-primary-faded.
See this doc in the wild on the in-progress Larva wiki. I would love to use a tool like SassDoc for something like this. We are currently working out a way to statically host the Twig pattern library so that those docs can be read outside of their READMEs (example), and a sister site for Sass/CSS docs that fits into that architecture is definitely on the roadmap.
How do you eat an elephant? One bite at a time (thanks for that, Liz!).
#ShareYourDocs