cdonohue / polychrome Goto Github PK

View Code? Open in Web Editor NEW

287.0 11.0 0.0 387 KB

🎨 Easy color manipulation in ~2kb (gzipped)

License: MIT License

JavaScript 44.65% TypeScript 55.35%

color palette css-color color-manipulation tiny css-in-js immutable

polychrome's Introduction

`polychrome`

A small ~2kB (gzipped) library for parsing and manipulating colors

Installation

feel free to replace yarn add with npm install

$> yarn add polychrome

Usage

// using ES6 modules
import polychrome from "polychrome";

// using CommonJS modules
const polychrome = require("polychrome");

// Make a polychrome color from hex, rgb(a), and hsl(a) strings
const red = polychrome("#F00");

// Get a string representation of a polychrome color in other formats
red.rgb() // "rgb(255,0,0)"

// Manipulate polychrome colors
const darkerRed = red.darken(20); // (pass in an integer percentage)
darkerRed.hsl() // "hsl(0,100%,40%)"

// Chain polychrome methods together before outputting
polychrome("#F00").darken(20).fadeOut(60).rgb() // "rgba(204,0,0,0.4)"

Polychrome Object

polychrome(colorString)

colorString can be a hex (3 or 6 digit), rgb(a), or hsl(a) string. Returns a polychrome object.

A polychrome object consists of the following properties:

rHex - 2 character hex string representation of the red color channel
gHex - 2 character hex string representation of the green color channel
bHex - 2 character hex string representation of the blue color channel
r - value of the red color channel [0 - 255]
g - value of the green color channel [0 - 255]
b - value of the blue color channel [0 - 255]
h - hue of the color [0 - 360]
s - saturation of the color [0 - 100]
l - lightness of the color [0 - 100]
luma - luma value of the color [0 - 255]

In addition to the above properties, the following methods are available to a polychrome for outputting CSS color strings:

.hex() - returns a 6-digit hexadecimal CSS compatible color string
```
polychrome("rgb(0, 0, 0)").hex() // "#000000"
```

.rgb() - returns an rgb(a) CSS compatible color string

// rgba will be used if an alpha value exists
polychrome("#000").rgb()           // "rgb(0,0,0)"
polychrome("#000").fadeOut(60).rgb() // "rgba(0,0,0,.4)"

.hsl() - returns an hsl(a) CSS compatible color string

// hsla will be used if an alpha value exists
polychrome("#000").hsl()           // "hsl(0,0%,0%)"
polychrome("#000").fadeOut(60).hsl() // "hsla(0,0%,0%,.4)"

Alpha

.setAlpha(value)

Returns a polychrome with an alpha value absolutely set to value. No change occurs if value is omitted.
.fadeIn(percentage)

Returns a polychrome faded in by percentage. Default 50 if no percentage is passed in.
.fadeOut(percentage)

Returns a polychrome faded out by percentage. Default 50 if no percentage is passed in.

Contrast

.contrast(dark, light)

Checks luma value of polychrome and returns dark or light polychrome depending on the contrast level. If a contrast ratio of at least 4.5:1 is not met, the dark/light colors will be darkened / lightened until a valid ratio is met.
```
polychrome("#000").contrast().rgb() // "rgb(255,255,255)"

polychrome("#DDD").contrast("#333", "#EEE").hex() // "#333333"
```
dark and light can be a String or polychrome. They default to black (#000) and white (#FFF) if params are not passed in.

Hue

.setHue(value)

Returns a polychrome with a hue value absolutely set to value. No change occurs if value is omitted.
.spin(degrees)

Returns a polychrome with a hue value rotated degrees. Can be a positive or negative degree value. When bounds of [0 - 360] are reached, hue will continue in a circular fashion until it has been spun the full amount.
.complimentary()

Returns a polychrome with a hue value rotated 180 degrees. Shorthand for .spin(180).

Lightness

.setLightness(value)

Returns a polychrome with a lightness value absolutely set to value. No change occurs if value is omitted.
.lighten(percentage)

Returns a polychrome lightened by percentage. Default 10 if no percentage is passed in.
.darken(percentage)

Returns a polychrome darkened by percentage. Default 10 if no percentage is passed in.

Mix

.mix(otherColor)

Returns a polychrome mixed with otherColor. otherColor can be another polychrome or a color string that will be parsed.
.tint()

Returns a polychrome mixed with white (#FFFFFF). Shorthand for .mix("#FFFFFF").
.shade()

Returns a polychrome mixed with black (#000000). Shorthand for .mix("#000000").

Saturation

.setSaturation(value)

Returns a polychrome with a saturation value absolutely set to value. No change occurs if value is omitted.
.saturate(percentage)

Returns a polychrome saturated by percentage. Default 10 if no percentage is passed in.
.desaturate(percentage)

Returns a polychrome desaturated by percentage. Default 10 if no percentage is passed in.
.grayscale()

Returns a polychrome with saturation set to 0. Shorthand for .setSaturation(0).

License

MIT License 2017 © Chad Donohue

polychrome's People

Contributors

Stargazers

Watchers

polychrome's Issues

Add support of HSV (HSB)

Hello!

Thanks for module, it looks like a fine addition for custom function passed to node-sass!

However, I see that it supports right now only HSL model and allows to get L (lightness).

Are there any plans to add support of HSV (or also known as HSB) model, where last value represents not lightness, but brightness? This model used, for instance, in Adobe products.

You can read a bit more details here: sass/sass#2192

What we want to achieve in result is ability to convert HSV model to HSL, so that Sass could be provided with HSV-based color adjust function.

Supply type definitions

Look into supplying definitions within package.json so that IDEs/editors can supply autocompletion.

Add ability to spin color hue

polychrome.spin(60) should return a polychrome with it's hue rotated 60 degrees

Also, maybe add a complimentary() method that is a shorthand for spin(180)

Add support for setting absolute alpha transparency

Currently, .fadeOut() and .fadeIn() will alter a polychrome's alpha value relative to it's current value.

Provide a .setAlpha() method that will set the alpha channel to an absolute value.

Add ability to mix colors

Chain a mix method that will take a color string or another polychrome and return the resulting polychrome of those mixed colors.

Also, provide shorthand methods shade and tint for mixing with white and black.

Add method to absolutely set saturation

Similar to #2, but for saturation of the color.

Basically, just move saturate and desaturate into one file with a setSaturation method and export all three.

Add method to absolutely set lightness

Similar to #2, but for lightness of the color.

Basically, just move darken and lighten into one file with a setLightness method and export all three.

Relocate tests to be next to interface

Split out tests to be next to the interface that they are testing. Also, this might be a good time to try some other test runners like jest or tape.

Use Jest

Transition from mocha to jest and refactor tests to be in their own files ~~alongside the implementations~~ in a __tests__ directory

Add comments for constants and formulas

Based on #11 (comment), there should be some comments explaining where formulas and constants are coming from and what they have to do with the end result.

Enhance contrast method to check for validity

The w3c contrast requirement is 4.5 : 1

https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/G18

Get the relative luminance of the contrast and base colors
Calculate the contrast ratio. If it does not pass, then recursively darken or lighten by 1% until the correct ratio is achieved.

Convert `js` files to `ts`

Rename file extensions and add appropriate steps to build process.

Try alternate build systems

Compare building with the following build tools:

Rollup
Webpack
Parcel

Use Prettier

https://github.com/prettier/prettier#usage

Add `prettier`

Along with formatting for local development, this should include the addition of a precommit format as well.

Look into using Butternut for minifying

https://butternut.now.sh

Contrast method fails for some colors

https://runkit.com/cdonohue/599dca37c848f6001260c77f

Add `sideEffects` to support Tree-Shaking?

Just a little request to have the package.json option sideEffects added, which allows bundlers to perform tree-shaking on a library, effectively reducing the code size - if set to false, that is.

Update documentation

Now that quite a bit more functionality has been added, section out the api documentation into categories for each modifier group (hue, saturation, mix, etc)

Allow for threshold in contrast method

Use functionality similar to http://lesscss.org/functions/#color-operations-contrast

Spread modifiers on polychrome object

Rather than importing everything to the make.js file, abstract all of these methods to a /modifiers directory and spread them all.

This would condense the make.js file a bit and hopefully make it easier to understand, especially now that there are a lot of modifier methods.

The good thing is, each of these modifiers follow the same pattern (pass in the color, then other args)

Rework the contrast method

The contrast method currently does the following:

Checks the baseColor luma value to determine if it is a dark or light color
Uses that decision to pick the dark or light contrast colors passed in (black and white are defaults)
Checks to see if the contrast ratio is at least 4.5 or greater
If we don't have a valid contrast ratio, darken/lighten the contrast color by 1 and try again

Example: You call .contrast() on a polychrome object that registers as dark because of it's luma value, but when compared to white, it has a contrast ratio of 4.0. This would lead to infinite recursion if a previous PR hadn't taken care of checking to see if we are already at the outer bounds of the color spectrum (black and white).

Instead, maybe both light and dark color ratios can be compared, and we go off of the greater contrast ratio if not yet 4.5? I think this might be more reliable than checking the luma value in the first place.

Convert `js` files to `ts`

There are some benefits for an end user consuming a library that has typescript definitions. Since more and more editors are supporting these, convert the codebase to typescript and verify the gzipped size doesn't change much.

Error when using contrast method

Reproducable steps:

https://runkit.com/cdonohue/599674de662ad800124adcf9

I'm guessing the contrast method fails on the following line of code:

https://github.com/cdonohue/polychrome/blob/master/src/contrast.js#L9