@black-saturn/color-algorithm

color-algorithm

A JavaScript function for producing color sets. Used to build Lyft's color system (Spectrum) and power ColorBox.

Background

• Re-Approaching Color by Lyft Design
• Designing a Comprehensive Color System by Linda Dong

Install

npm i @k-vyn/coloralgorithm

Usage

CommonJS

const color = require("@k-vyn/coloralgorithm");
color.generate(props, options?);

ES6

import color from "@k-vyn/coloralgorithm";
color.generate(props, options?);

Props

These must be pass to the function.

interface Props {
  steps: number;
  hue: {
    start: number; // 0 - 359
    end: number; // 0 - 359
    curve: Curve; // See acceptable curves below
  };
  saturation: {
    start: number; // 0 - 1
    end: number; // 0 - 1
    curve: Curve;
    rate: number; // 1 is default
  };
  brightness: {
    start: number; // 0 - 1
    end: number; // 0 - 1
    curve: Curve;
  };
}

Curves

Hue, Saturation, and Luminosity all allow you to specify a curve. The curve manipulates the progression of the steps.

Default curve

These are easing curves that come bundled in. You can see the different progressions on easing.net.

easeIn	easeOut	easeInOut
easeInSine	easeOutSine	easeInOutSine
easeInQuad	easeOutQuad	easeInOutQuad
easeInCubic	easeOutCubic	easeInOutCubic
easeInQuart	easeOutQuart	easeInOutQuart
easeInQuint	easeOutQuint	easeInOutQuint
easeInExpo	easeOutExpo	easeInOutExpo
easeInCirc	easeOutCirc	easeInOutCirc
easeInBack	easeOutBack	easeInOutBack
linear	linear	linear

{
  saturation: {
    start:0,
    end:1,
    curve:"easeInSine",
  },
}

Custom curve

Additionially, a custom curve can be provided. Custom curves are numbered arrays with four 0-1 values. [x1, y1, x2, y2].

{
  saturation: {
    start:0,
    end:1,
    curve:[0.12, 0, 0.39, 0],
  },
}

Options

Configurable options

interface Options {
  minorSteps?: number[];
  lockHex?: string; // hex value
  provideInverted?: boolean;
  lockHexInverted?: string; // hex value
  rotation?: "clockwise" | "counterclockwise" | "cw" | "ccw";
  name?: string;
}

Minor Steps

Provides an additional step in between two steps.

Major steps are whole numbers 0, 1, 2, 3,. Minor steps are decimal numbers .5, 1.5, 2.75.

Note: Always keep minor steps sorted least-to-greatest.

Examples

{
  minorStep:[0],
}

// returns steps - 0, .5, 1...

{
  minorStep:[0, .5],
}
// returns steps - 0, .5, .75, 1...

{
  minorStep:[5, 6],
}
// returns steps - ...50, 55, 60, 65...

Lock Hex

Alters result to provide a hex value as a return value. It works by identifying the closest color in the result by Euclidian distance, and the eases all colors around the hex proportionally.

{
  lockHex: '#999`,
}
// returns colors - ...#999...

Provide Inverted

Provides an additional color set that is inverted. Inversion is provided across Hue, Saturation, and Brightness. Each axis will flip start/end values. It will also reverse the curve, so an EaseIn will become an EaseOut.

Example

{
  provideInverted: true,
}
/// returns [NormalColorSet, InvertedColorSet]

Examples

See Lock Hex. This will lock a hex in the inverted set.

Rotation

This can alter the rotation of the progression of hues. Default rotation will progress hues 0 through 359 and repeat. By setting it progress counterclockwise, you'll reverse the progression order.

Examples

{
  hue: {
    start: 10
    end: 350
  ...
},
{
  rotation: 'clockwise', // default
}
// returns hues ~ 10, 100, 250, 350

{
  hue: {
    start: 10
    end: 350
  ...
},
{
  rotation: 'counterclockwise',
}
// returns hues ~ 10, 5, 0, 350

Name

This is simply time saver. It returns the name in the result. Nothing else.

{
  name: 'red',
}
/// returns result.name = red

Result

The function returns the generated palette as an array of color objects:

type Result = ColorSet[];

type ColorSet = Color[];

type Color = {
  label: number;
  hue: number;
  saturation: number;
  brightness: number;
  isMajor: boolean;
  isLocked: boolean;
  hex: string;
  hsl: number[];
  hsv: number[];
  lab: number[];
  rgbString: string;
  rgbArray: number[];
  rgbaString: string;
  rgbaArray: number[];
};

An example return looks something like this –

const result = [
    {
      inverted: false,
      colors: [
        {
          label: 0
          hue: 10
          saturation: 0.04
          brightness: 1
          isMajor: true
          isLocked: false
          hex: "#fff7f5"
          hsl: [10.000000000000057, 1, 0.98, 1]
          hsv: [10.000000000000085, 0.04000000000000007, 1]
          lab: [97.65498027125287, 2.5409203669395364, 1.8232127862283898]
          rgbString: "255,247,245"
          rgbArray: [255, 247, 245]
          rgbaString: "255,247,245,1"
          rgbaArray: [255, 247, 245, 1]
        } ...
      ]
    },
    {
      inverted: true,
      colors: (13) [
        {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}
      ],
    }
]

Development

This package is built using Rollup, and this package is written in TypeScript and converted to CommonJS using a rollup typescript plugin.

To run locally, you can either run npm run build for a one time build or npm run start to make continous builds.