JigSass Tools Color

Define and access named colors in a central palette

Installation

Using npm:

npm i -S jigsass-tools-color

Usage

@import 'path/to/jigsass-tools-color/scss/index';

Start by defining a color palette in the $jigsass-colors map.

You may define adjustment on each color by specifing a color function (or functions) directly in the map:

$jigsass-colors: (
  // Explicit colors
  black: #000,
  primary: #09a5d9,
  secondary: #046380,
  tertiary: #9f1626,
  neutral: #2d2d2d,

  // Adjustments on explicit colors
  light-tertiary: #9f1626 complement,

  // Aliases
  text-link: secondary,

  // Adjustments to existing colors
  gutter-rule: secondary (tint: 3),

  // Multiple adjustments
  headline: primary (shade: 1) complement,
///   )

You can now access colors, using the same [syntax] used for defining them to begin with.

.foo {
   bar: jigsass-color(black (tint: 20%)); // --> #333
}

For consistency, you can define per-color-function adjustment steps (documentation):

$jigsass-adjustment-steps: (
  // Tint will be increamented by 10% at every step
  tint: 10%,
  // Lighten has predefined steps
  lighten: 2% 14% 34% 45%,
  // Used for all color function with no explicitly defined steps
  default: 5%,
);

And then access them in the jigsass-color function and $jigsass-colors map by passing a unitless number to the color functions:

.bar {
  // Tint `black` by two steps
  baz: jigsass-color(black (tint: 2));  // --> #333
}

License: MIT

color

variables

jigsass-colors

$jigsass-colors: () !default;

Description

Color palette definitions.

Type

Map

Map structure

Map keyName Map keyDescription Map keyType Map keyValue

color —none List —none

Map keyName	Map keyDescription	Map keyType	Map keyValue
`color`	—none	`List`	—none
`color.value`	Can be either an explicit color value or a string referencing another color defined in the palette.	`Color` or `String`	—none
`color.adjustments`	A list of color functions to apply. Each item can either be a map with `function-name: args` pairs, or a string for color functions that do not take adjustment arguments (e.g., compliment). Adjustment functions will be executed in the order they are defined, in the following format: `function-name(color.value, args...)`. When a adjustment argument is a unitless number, It will resolve to the corresponding step in `$jigsass-adjustment-steps`.	`List`	—none

color.value

Can be either an explicit color value or a string referencing another color defined in the palette.

Color or String

—

color.adjustments

A list of color functions to apply. Each item can either be a map with function-name: args pairs, or a string for color functions that do not take adjustment arguments (e.g., compliment).

Adjustment functions will be executed in the order they are defined, in the following format: function-name(color.value, args...).

When a adjustment argument is a unitless number, It will resolve to the corresponding step in $jigsass-adjustment-steps.

List

—

Example

$jigsass-color: (
  // Explicit colors
  primary: #09a5d9,
  secondary: #046380,
  tertiary: #9f1626,
  neutral: #2d2d2d,

  // Reference adjustments
  light-tertiary: #9f1626 (tint: 2),

  // Refrences
  text-link: secondary,

  // Reference adjustments
  gutter-rule: secondary (tint: 3),

  // Multiple adjustments
  headline: primary (shade: 1) complement,
)

Used by

[function] jigsass-color
[mixin] jigsass-set-color

See

[variable] jigsass-adjustment-steps

jigsass-adjustment-steps

$jigsass-adjustment-steps: (
  default: 5%
) !default;

Description

Predefined adjustment steps for color functions in the format of 'function-name: steps'.

If the map has a default key, if will be used as the default for color functions which don't have explicitly defined steps

A key associated a Number value, for incremental steps, or with a list of numbers for explicitly defining steps (see example).

Type

Map

Map structure

map keyName	map keyDescription	map keyType	map keyValue
`default`	The default steps used for color functions with no explicitly defined steps.	`Percentage` or `List`	`5%`

Example

$jigsass-adjustment-steps: (
  // Incremental: adjustment increased by 5%
  // at every step (i.e., step 1 = 5%, step 4 = 20%).
  default: 5%,

  // Explicit: step 1 = 25%, step 3 = 75%.
  darken: 25% 50% 75%
);

Used by

[function] _jigsass-get-adjustment-level

functions

jigsass-color

@function jigsass-color($color) { ... }

Description

Get a color from the color palette defined in $jigsass-color using the format described in $jigsass-colors.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$color`	A CSS color or a name of a color from the colors palette, with optional adjustments using the format described in `$jigsass-colors`.	`Color` or `String` or `List`	—none

Returns

Color

Throws

jigsass-color: Cannot use #{$fn} to adjust color. No such

Requires

[function] _jigsass-get-adjustment-level
[variable] jigsass-colors

Used by

[function] jigsass-tint
[function] jigsass-shade

jigsass-tint

@function jigsass-tint($color, $amount) { ... }

Description

Mix a color with white by amount.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$color`	A list with the first item being either an explicit color or a name of a color from the `$jigsass-color` palette. The following, optional, items are adjustments to apply on the color before tinting it, in the format described in `$jigsass-colors`	`Color` or `String` or `List`	—none
`$amount`	The amount of `white` to add to `$color`.	`Precentage`	—none

Returns

Color

Throws

jigsass-tint: $amount must be a number in %s, but it is a #{type-of($amount)}.
jigsass-tint: $amount must be in %s, but it is in #{unit($amount)}.

Requires

[function] jigsass-color

Example

$tinted: jigsass-tint(primary (saturate: 2), 20%);

jigsass-shade

@function jigsass-shade($color, $amount) { ... }

Description

Mix a color with black by amount.

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$color`	A list with the first item being either an explicit color or a name of a color from the `$jigsass-color` palette. The following, optional, items are adjustments to apply on the color before shading it, in the format described in `$jigsass-colors`	`Color` or `String` or `List`	—none
`$amount`	The amount of `black` to add to `$color`.	`Precentage`	—none

Returns

Color

Throws

jigsass-shade: $amount must be a number in %s, but it is a #{type-of($amount)}.
jigsass-shade: $amount must be in %s, but it is in #{unit($amount)}.

Requires

[function] jigsass-color

Example

$shaded: jigsass-shade(primary (desaturate: 2), 20%);

[private] _jigsass-get-adjustment-level

@function _jigsass-get-adjustment-level($function, $adjustments) { ... }

Description

A helper to get color adjustment levels based on steps defined in $jigsass-adjustment-steps

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$function`	A color function to resolve adjustment steps for	`String`	—none
`$adjustments`	A unitless number for the number of steps to resolve, a percentage, or a list of those.	`Number` or `List`	—none

Returns

Number or List —

An adjustment level in percentage, or a list of them.

Throws

_jigsass-get-adjustment-steps: No adjustment steps could be found

Requires

[variable] jigsass-adjustment-steps

Used by

[function] jigsass-color

mixins

jigsass-set-color

@mixin jigsass-set-color($name, $values) { ... }

Description

Add or overwrite a color in the color palette

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$name`	The name of the new color	`String`	—none
`$values`	color values in the format described in `$jigsass-colors`.	`String` or `Color` or `List`	—none

Requires

[variable] jigsass-colors

Example

// Explicit
@include jigsass-set-color(quaternary, #f0f);

// Reference an existing color
@include jigsass-set-color(quaternary, primary);

// Adjust an existing color
@include jigsass-set-color(quaternary, primary compliment (tint: 1));