A tiny, zero-dependency libary for building harmonious material palettes for any color.
Created with ❤️ by Arvind Srinivasan.
Use the package manager npm to install matercolors from commandline.
⚠️ Please Note!
It is recommended to use the latest version as v1.0.1 had a bug introduced during linting. It has been resolved in v1.0.2.
npm i matercolorsAlternatively, you can update your package.json as:
"matercolors": "^1.0.2"...aand thats it! Now lets' dive right in!
After installing, import and use the library like any ES6 default imports. For example like this:
import Matercolor from 'matercolors'
let PurplePalette = new Matercolor('#6200EE')Logging PurplePalette gives the output of the constructor with the following organisation.
Matercolor {
color: '#6200EE',
options: { threshold: 128, light: 200, main: 500, dark: 700 },
palette: [Function] }As you can see from the constructor, currently Matercolor offers 4 options for configuration.
| Options | Type | Default | What it does |
|---|---|---|---|
light |
Number |
200 |
Assigns light to the palette object with given key |
main |
Number |
500 |
Assigns main to the palette object with given key |
dark |
Number |
700 |
Assigns dark to the palette object with given key |
threshold |
Number |
128 |
Sets the Contrast threshold for the foreground text |
The following methods are available as of version 1.0.0.
| Method | Type | What it returns |
|---|---|---|
.palette() |
Getter |
A Material Palette Object with Text Contrast Values for the given color |
.shades(paletteType) |
Getter |
Light, Main and Dark shades for a selected palette type |
.accents(paletteType) |
Getter |
Accent Color Palette for a selected palette type |
Logging the palette output for the PurplePalette color by
PurplePalette.palette()
we get an output that follows the following structure.
{
primary : { // type of palette
50 : { // lightest color in palette
hex : String, // Valid Hex Color Code
rgb : {r: Number, g: Number, b: Number, string: String}
hsl : {h: Number, s: Number, l: Number, string: String},
cymk : {c: Number, y: Number, m: Number, k: Number, string: String},
contrastText: 'white'|'black' },
100 : [Object],
200 : [Object],
...
900 : [Object], // darkest color in palette
// Accents
A100 : [Object],
A200 : [Object],
A400 : [Object],
A700 : [Object],
}
secondary : { // type of palette
50 : [Object]
100 : [Object],
200 : [Object],
...
900 : [Object], // darkest color in palette
// Accents
A100 : [Object],
A200 : [Object],
A400 : [Object],
A700 : [Object],
}
// ...More coming soon
}All the other functions are simply helpers to access specific parts of the complete palette.
If we do not change the defaults, getting the shades of the above color is as simple as
PurplePalette.shades("primary") // where primary is a palette typewhich returns the light, main and dark variants of the color (see below). The choice of these palettes can be configured through tweaking the options.
{
"light": {
"hex": "#b894f6",
"rgb": {
"r": 184,
"g": 148,
"b": 246,
"string": "rgb(184,148,246)"
},
"hsl": {
"h": 262,
"s": 84.5,
"l": 77.3,
"string": "hsl(262,84.5%,77.3%)"
},
"cymk": {
"c": 25.2033,
"y": 0,
"m": 39.8374,
"k": 3.5294,
"string": "cymk(25.2033%,0%,39.8374%,3.5294%)"
},
"contrastText": "black"
},
"main": {
"hex": "#6200ee",
"rgb": {
"r": 98,
"g": 0,
"b": 238,
"string": "rgb(98,0,238)"
},
"hsl": {
"h": 265,
"s": 100,
"l": 46.7,
"string": "hsl(265,100%,46.7%)"
},
"cymk": {
"c": 58.8235,
"y": 0,
"m": 100,
"k": 6.6667,
"string": "cymk(58.8235%,0%,100%,6.6667%)"
},
"contrastText": "white"
},
"dark": {
"hex": "#3f00e0",
"rgb": {
"r": 63,
"g": 0,
"b": 224,
"string": "rgb(63,0,224)"
},
"hsl": {
"h": 257,
"s": 100,
"l": 43.9,
"string": "hsl(257,100%,43.9%)"
},
"cymk": {
"c": 71.875,
"y": 0,
"m": 100,
"k": 12.1569,
"string": "cymk(71.875%,0%,100%,12.1569%)"
},
"contrastText": "white"
}
}Similarly, for extracting the accents from the palette object, we can use:
PurplePalette.accents("primary") // where primary is a palette typewhich, for the given color, generates the output:
{
"A100": {
"hex": "#b388ff",
"rgb": {
"r": 179,
"g": 136,
"b": 255,
"string": "rgb(179,136,255)"
},
"hsl": {
"h": 262,
"s": 100,
"l": 76.7,
"string": "hsl(262,100%,76.7%)"
},
"cymk": {
"c": 29.8039,
"y": 0,
"m": 46.6667,
"k": 0,
"string": "cymk(29.8039%,0%,46.6667%,0%)"
},
"contrastText": "black"
},
"A200": {
"hex": "#7c4dff",
"rgb": {
"r": 124,
"g": 77,
"b": 255,
"string": "rgb(124,77,255)"
},
"hsl": {
"h": 256,
"s": 100,
"l": 65.1,
"string": "hsl(256,100%,65.1%)"
},
"cymk": {
"c": 51.3725,
"y": 0,
"m": 69.8039,
"k": 0,
"string": "cymk(51.3725%,0%,69.8039%,0%)"
},
"contrastText": "white"
},
"A400": {
"hex": "#6420ff",
"rgb": {
"r": 100,
"g": 32,
"b": 255,
"string": "rgb(100,32,255)"
},
"hsl": {
"h": 258,
"s": 100,
"l": 56.3,
"string": "hsl(258,100%,56.3%)"
},
"cymk": {
"c": 60.7843,
"y": 0,
"m": 87.451,
"k": 0,
"string": "cymk(60.7843%,0%,87.451%,0%)"
},
"contrastText": "white"
},
"A700": {
"hex": "#6200ee",
"rgb": {
"r": 98,
"g": 0,
"b": 238,
"string": "rgb(98,0,238)"
},
"hsl": {
"h": 265,
"s": 100,
"l": 46.7,
"string": "hsl(265,100%,46.7%)"
},
"cymk": {
"c": 58.8235,
"y": 0,
"m": 100,
"k": 6.6667,
"string": "cymk(58.8235%,0%,100%,6.6667%)"
},
"contrastText": "white"
}
}Similar outputs are generated for the secondary palette type.
These outputs can also be used in conjunction with Material UI's createMuiTheme to configure custom palettes. For a better understanding on how to use, you can checkout the demo.
The following snippet shows an example usage with createMuiTheme() using the shades() function:
import Matercolor from 'matercolors';
import { createMuiTheme } from '@material-ui/core/styles';
let purple = new Matercolor('#6200EE');
let primary = purple.shades("primary");
let secondary = purple.shades("secondary"); // complementary palette generated for you!
const theme = createMuiTheme({
palette: {
primary: {
main: primary.main.hex,
light: primary.light.hex,
dark: primary.dark.hex,
},
secondary: {
main: secondary.main.hex,
light: secondary.light.hex,
dark: secondary.dark.hex,
},
},
});Want you could create a full-fledged theme that matches your logo?
After installing colorthief (npm i colorthief) you can use the following code snippet as reference.
const Matercolor = require('matercolors');
const ColorThief = require('colorthief');
const imageName = 'my-awesome-logo.png'; // path to your image file
const numberOfColors = 5; // change the number to as many colors as you want
let brandPalette = [];
const rgbToHex = (rgb) => '#' + rgb.map(x => {
const hex = x.toString(16)
return hex.length === 1 ? '0' + hex : hex
}).join('')
const img = resolve(process.cwd(), imageName);
ColorThief.getPalette(img, numberOfColors)
.then(palette => {
for (let i=0, len=palette.length; i < len; i++) {
let color = new Matercolor(rgbToHex(palette[i])).palette()
brandPalette.push(color);
}
console.log(JSON.stringify(brandPalette, null, 2));
})
.catch(err => { console.log(err) })This code will log the Matercolor Palette Objects for every dominant color extracted from the image in a pretty format.
- Generate Primary Palette for any given color
- Generate Accents for Palette
- Get Contrast Colors for Foreground Text
- Added Demo Project to demonstrate Usage
- Generate Complementary Palette
- Generate Analogous Palette
- Generate Triadic Palette
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to create or update tests as appropriate.