Skip to content

Latest commit

 

History

History
285 lines (224 loc) · 5.95 KB

README.md

File metadata and controls

285 lines (224 loc) · 5.95 KB
Raw

color-algorithm

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

Background

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.