[docs] Document the color helpers

• This is not a v0.x issue.
• I have searched the issues of this repository and believe that this is not a duplicate.

Expected Behavior

I’ve done a comparison of various JS color utility libraries. I found that @material-ui/core/es/styles/colorManipulator.js offers the smallest bundle size of all options I could find. Here’s a comparison to other libraries (all numbers are minified; second number is minified + gzipped):

• colorManipulator.js // 3.02kb, 1.25 gzipped
• kewler // 7.24kb, 2.7kb gzipped
• spectra // 10.5kb, 3.38kb gzipped
• tinycolor2 // 15.2kb, 5.28kb gzipped
• color // 23.1kb, 7.83kb gzipped
• chroma-js // 39.8, 15.9kb gzipped

Current Behavior

@oliviertassinari has stated that the color manipulator is a private API. He also openly asked if there were better open-source alternatives to the private implementation. In my view, there is no better alternative. colorManipulator.js offers basically identical functionality to all of the other libraries, and does it in the fewest amount of bytes.

Context

Color Manipulation is a very generic problem, this library has the best solution, but it is a private API. I think it could be easily publishable as a separate entity within the mono-repo structure. It’s already fully unit tested, so there could be no disagreement that it would be in a good state to make publicly accessible.

[mnajdova]

Going back to the original problem stated 😃 Now that these helpers are part of the @material-ui/system, we can go ahead and add a new page in the docs under System to document them.

[mbrookes]

colorManipulator.js offers basically identical functionality to all of the other libraries, and does it in the fewest amount of bytes

Not strictly true - all offer varying degrees of additional functionality; somewhat proportional to their size. The exception is colorManipulator’s emphasize, however, since this is the application of lighten and darken according the result of getLuminance, it could be achieved with most libraries.

colorManipulator provides the minimal subset needed for Material-UI. Still, if that’s good enough for others, we should still make it a public API, as this (and other) issues suggest.

I thought it would be helpful to benchmark the function (or method) names that are used for equivalents to colorManipulator’s functions, particularly for fade, which I have always found awkwardly named (fade can make a color less “faded”!).

Note that some of these functions take a relative value, e.g. lighten(color, 0.5) -> color 50% lighter than it was. While others are absolute: fade(color, 0.5) -> color with alpha set to 50%.

Library	Lighten	Darken	Darken light / lighten dark	Opacity	Get luminance	Get contrast ratio
Material-UI	lighten	darken	emphasize	fade	getLuminance	getContrastRatio
Kewler	lightness (+%)	lightness (-%)	N/A	N/A	N/A	N/A
Spectra	lighten	darken	N/A	fadeIn fadeOut	luma	N/A
tinycolor2	lighten	darken	N/A	setAlpha	getLuminance	readability
color	lighten	darken	N/A	fade opaquer	luminosity	contrast
chroma	brighten	darken	N/A	alpha	luminance	contrast
polished	lighten	darken	N/A	rgba	getLuminance	N/A
CSS 4 color-mod proposal (removed)	lightness	blackness	contrast	alpha	N/A	N/A

My preference for fade is to follow tinycolor2’s setAlpha, as it is descriptive, and mirrors the get of getLuminance and getContrastRatio.

I don’t have a strong preference for an alternative name emphasize, however I don’t think that the current name is accurate or descriptive. Suggestions welcome!