Module: Colors

The purpose of the colors module is to keep track of combinations of appropriate background and text colors. You'll find it in src/modules/_colors.scss.

The global $colors map

All colors should be registered in the global Sass-map named $colors. For every key in the $colors map, there should be a Sass-list containing one or more color values. The first color value of such a list is the color named by the key. There may be a second color in the list, if so it's a text color to be used on top of a background in the named color.

In the following example there is a primary color along with a corresponding text color, a body background color together with a color for body text, and finally link and visited link colors—which are both text colors by themselves so they don't have any counterparts.

$colors: (
  primary: #47282b #eee8e9,
  body: #fdfdfd #0c0d0c,
  link: #061386,
  visited: #061386
)

Every part of Kingdom that needs some color will generate and register that color unless it's already set in the $colors Sass-map.

Registering colors in $colors

Above your import of your selected Kingdom level, make sure to set the $colors Sass-map with any colors that you care about. You can also use the register-color mixin to which you supply a $name and a list of one or two $color-values, the second being the text color to use on a backround of the first color. If you only supply one color, the mixin will automatically generate a contrasting text color unless $ensure-text-color is set to false.

Debugging $colors

You can check what colors are registered with @debug $colors; anywhere in your Sass.

Applying colors

The colors module provides two mixins for applying a named color within CSS selectors. Both pull color values from the $colors map and they both set properties referencing CSS custom properties, for those browsers that support them. Using the custom properties makes changing the colors dynamically easier, both via javascript and the CSS cascade.

• The mixin apply-color takes a color $name and an optional $property to set—which of course defaults to the color property when not supplied. If you want to apply not the named color itself, but its corresponding text color, just supply $apply-text-color: true as well.
• The mixin apply-background-color takes a color $name that it applies to the background-color property. But it also applies that background color's corresponding text color to the color property, unless $apply-text-color: false is supplied.

Getting a color value in Sass

If you need to pull out a color value from the $colors map, perhaps to transform it or apply it within a shadow declaration you can use function get-color.

Functions for generating and transforming colors

• Function transform-hue returns a color with similar "feel" to the supplied color but shifted into the hue of another color. Basically it keeps the angles between hues in multiples of 30°. For example the default link color is the primary color shifted into the blue spectrum.
• Function ensure-hue-contrast will compare a given color to another color and shift it away in the hue spectrum if they're within 15° of each other. For example the default link color is checked against the primary color that it's derieved from so that if they're both blue, they're at least different hues of blue.
• Function transform-hue-with-contrast combines the two above functions for convenience.
• Function normalize-color will adjust a color to a minimum saturation and so that its not to dark or too light. For example the default caution color is derieved from the primary color, but normalized so that it's not as extreme, should the primary color be that.
• Function text-color-for-background will generate a contrasting text color to use on a given background. Basically it reduces saturation and makes the text color dark if the background is light and vice versa.
• Function background-text-color-pair will append a corresponding text color to the given background color and return them as a list, suitable for insertion into the $colors map.