Skip to content

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

License

Notifications You must be signed in to change notification settings

arvindcheenu/Matercolors

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

78 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Matercolors

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.3.0 : Better Accent Generation, renamed keys

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

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

πŸŽ‰ 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
tetradic primary Q1
tetradic secondary Q2
tetradic tertiary Q3

πŸ”§ 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],
    200 : [String],
    ...
    900 : [String], // darkest color in palette
    A100 : [String],  
    A200 : [String],
    A400 : [String],
    A700 : [String],
  },
  // similarly we have for other derived palettes
  complementary : { ... },
  analogous : {
    primary: { ... },
    secondary: { ... },
  },
  triadic : {
    primary: { ... },
    secondary: { ... },
  },
  tetradic : {
    primary: { ... },
    secondary: { ... },
    tertiary: { ... },
  },
}

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
  • 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

πŸ“œ License

MIT