README

Matercolors

GitHub code size in bytes npm npm npm bundle size (scoped) npm dependencies NPM

A tiny, zero-dependency libary for building harmonious material palettes for any color.

Created with ❤️ by Arvind Srinivasan.

✨ New in v.2.2.10 : Skyrocketing Productivity!

Updated version to match Semantic Versioning Standards.

Removed the residual options that were missed in the latest major version.

Most importantly,direct dot access functionality has been added to the constructor so that one can quickly access the colors they need across palettes.

✨ New in v.2.0 : Lose some features, Gain even more!

shades and accents are completely removed as they were redundant. They are replaced by a makePalette helper function. This freed up some space for new palette generators for building analogous and triadic palettes.

As color conversions can be done by other libraries, these helpers were removed to make API more expressive.

While the package size reduced by 5%, productivity increased by 50%.

🎉 Installation

Use the package manager npm to install matercolors from commandline.

npm i matercolors

Alternatively, you can update your package.json as:

"matercolors": "latest"

✨ New in v.1.2 : Matercolor now works in the browser!

If you want to use it as a CDN instead, you can access it through unpkg!

🚸 Usage

🎨 Palette Constructor

After installing, import and use the library like any ES6 default imports. For example like this:

import Matercolor from 'matercolors'
let Purple = new Matercolor('#6200EE')

Logging Purple gives the output of the constructor with the following organisation.

Matercolor {
  // color keys in constructor for direct dot access 
  this[ckey] = [String]
  // ...where ckey is given by concatenating root keys with palette prefix.
  color: '#6200EE',
  options: { threshold: 128, showContrastText: false },
  palette: [Function] }

As you can see here, ckey is given by concatenating root keys (100 to 900) with palette prefix. The palette name and the corresponding prefix is given in the following table:

| Palette Name | Prefix | |-|-| | primary | `` | | complementary | C | | analogous primary | A | | analogous secondary | A1 | | triadic primary | T | | triadic secondary | T1 |

🔧 Options and Methods

As you can see from the constructor, currently Matercolor offers 2 options for configuration.

Apart from these options, the new Matercolor exposes a single function to generate specific palettes.

makePalette(paletteName : `String`, updateRoot: `Boolean`) returns `Object`

where paletteName can be any one of the following case-sensitive strings: primary, complementary, analogous, firstAnalogous, secondAnalogous, triadic, firstTriadic, secondTriadic.

🏗️ Palette Object Structure

We can the palette output for the Purple color by

Purple.palette

we get an output that follows the following structure.

{
  primary : { // type of palette
    // varies depending on whether 
    50 : [String|{hex : String, contrastText: 'white'|'black'}],
    100 : [String|Object],
    200 : [String|Object],
    ...
    900 : [String|Object], // darkest color in palette
  },
  // similarly we have for other derived palettes
  complementary : { ... },
  analogous : {
    primary: { ... },
    secondary: { ... },
  },
  triadic : {
    primary: { ... },
    secondary: { ... },
  }
}

These outputs can also be used in conjunction with Material UI's createMuiTheme to configure custom palettes.

Usage with `createMuiTheme`

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');
/*
You can still use this though you may not need to now:
let primary = purple.palette.primary;
let secondary = purple.palette.complementary; // complementary palette generated for you!
// similarly use any derived palettes
let analogous = purple.palette.analogous.primary; // choose any of the two color schemes
let triadic = purple.palette.triadic.secondary;    // choose any of the two color schemes
*/
const theme = createMuiTheme({
  palette: {
    primary: {
      main: purple.500,
      light: purple.200,
      dark: purple.700,
    },
    secondary: {
      main: purple.C500,
      light: purple.C200,
      dark: purple.C700,
    },
  },
});

Usage with `colorthief`

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.

🛣️ Roadmap

Generate Primary Palette for any given color
~~Generate Shades for Palette~~
~~Generate Accents for Palette~~
Automatically selects Black or White as Contrast Text
Generate Complementary Palette
Generate Analogous Palette
Generate Triadic Palette
Generate Tetradic Palette
Generate Split Complementary Palette
Update Demo Project to demonstrate Usage

👐 Contributing

Pull requests are welcome. For major changes, please open an issue primary to discuss what you would like to change. Please make sure to create or update tests as appropriate.

🙏 Acknowledgements

📜 License

MIT

Usage no npm install needed!