✨ 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 object access 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%.

✨ New in v.3.0 : Better Accent Generation, renamed keys

accents are reintroduced with better color generation. Renamed shortcodes to make room for accent keys.

🎉 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 and A100,A200,A400,A700) with palette prefix. The palette name and the corresponding prefix is given in the following table:

| Palette Name | Prefix | |-|-| | primary | `` | | complementary | C | | analogous primary | A1 | | analogous secondary | A2 | | triadic primary | T1 | | triadic secondary | T2 |

🔧 Options and Methods

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

| Options | Type | Default | What it does | |-|-|-|-| | threshold |Number| 128 | Sets the Contrast threshold for the foreground text | | showContrastText |Boolean| false | Shows contrast text colour for each color in the palette |

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

• [x] Generate Primary Palette for any given color
• [x] ~~Generate Shades for Palette~~
• [x] ~~Generate Accents for Palette~~
• [x] Automatically selects Black or White as Contrast Text
• [x] Generate Complementary Palette
• [x] Generate Analogous Palette
• [x] Generate Triadic Palette
• [x] Add Direct Dot Access to Constructor
• [ ] 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

• edelstone/material-palette-generator
• mbitson/mcg

📜 License

MIT