color-algorithm

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

Upgrading to v2.0.0

v2.0.0 introduces input validation with helpful error messages. This is a breaking change if your code was passing invalid inputs that previously failed silently.

What Changed

• Invalid inputs now throw ColorAlgorithmError instead of producing undefined behavior
• New exports: ColorAlgorithmError, ErrorCodes, and TypeScript types

Migration

If your code was already passing valid inputs, no changes needed. If you were relying on silent failures, wrap calls in try/catch:

import { generate, ColorAlgorithmError } from "@k-vyn/coloralgorithm";

try {
  const palette = generate(props);
} catch (e) {
  if (e instanceof ColorAlgorithmError) {
    console.error(e.code, e.message);
  }
}

Background

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

Install

npm i @k-vyn/coloralgorithm

Usage

ES Modules (Recommended)

import { generate } from "@k-vyn/coloralgorithm";

const palette = generate(props, options);

With TypeScript Types

import { generate, ColorAlgorithmError, ErrorCodes } from "@k-vyn/coloralgorithm";
import type { ColorProps, ColorOptions, ColorResults } from "@k-vyn/coloralgorithm";

const props: ColorProps = {
  steps: 11,
  hue: { start: 220, end: 240, curve: "easeOutQuad" },
  saturation: { start: 0.08, end: 1, rate: 1, curve: "easeOutQuad" },
  brightness: { start: 1, end: 0.2, curve: "easeInQuart" },
};

const palette: ColorResults = generate(props, { name: "Blue" });

CommonJS

const { generate } = require("@k-vyn/coloralgorithm");
generate(props, options);

Props

These must be passed to the function. Invalid values will throw ColorAlgorithmError.

interface Props {
  steps: number;      // >= 2 (integer)
  hue: {
    start: number;    // 0 - 360
    end: number;      // 0 - 360
    curve: Curve;     // See acceptable curves below
  };
  saturation: {
    start: number;    // 0 - 1
    end: number;      // 0 - 1
    curve: Curve;
    rate: number;     // > 0 (default: 1)
  };
  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

Additionally, 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

{
  minorSteps:[0],
}

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

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

{
  minorSteps:[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 ColorResults = {
  inverted: boolean;
  name: string | undefined;
  colors: Color[];
}[];

type Color = {
  step: 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: [
        {
          step: 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) [
        {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}
      ],
    }
]

Error Handling

v2.0.0+ validates all inputs and throws ColorAlgorithmError for invalid values.

import { generate, ColorAlgorithmError, ErrorCodes } from "@k-vyn/coloralgorithm";

try {
  const palette = generate(props);
} catch (e) {
  if (e instanceof ColorAlgorithmError) {
    switch (e.code) {
      case ErrorCodes.INVALID_STEPS:
        console.error("Steps must be >= 2");
        break;
      case ErrorCodes.INVALID_HEX:
        console.error("Invalid hex color format");
        break;
      default:
        console.error(e.message);
    }
  }
}

Error Codes

| Code | Description | |------|-------------| | INVALID_STEPS | steps must be an integer >= 2 | | INVALID_HUE | hue.start/end must be 0-360 | | INVALID_SATURATION | saturation.start/end must be 0-1 | | INVALID_BRIGHTNESS | brightness.start/end must be 0-1 | | INVALID_RATE | saturation.rate must be > 0 | | INVALID_CURVE | Unknown curve name or invalid curve array | | INVALID_HEX | lockHex must be valid hex (#RGB or #RRGGBB) | | INVALID_MINOR_STEPS | minorSteps must be array of numbers | | MISSING_PROPS | props is required |

Development

This package is built using Rollup and TypeScript.

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