[colorManipulator][docs] Document the color helpers

[petermikitsh]

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

[oliviertassinari]

At work, we are often using these helpers by tapping into the private API 🤷‍♂️. Keeping the module within a reasonable size is critical for Material-UI. In the long run, I think that moving the styles folder into a @material-ui/styles package can make sense (if we need different release lifecycle/dependencies). Should we close the issue as a duplicate of #10789? Also, I have seen some people (few) using the docs search to find more information on the color helpers without success.

@mbrookes What about keeping it where it is now?

[petermikitsh]

I would prefer to be able to use the color manipulator functions without having to download the entire core library. I think it would be sensible to create a @material-ui/styles package.

[oliviertassinari]

without having to download the entire core library.

@petermikitsh We are working on improving that overhead, but I understand the motivation: https://packagephobia.now.sh/result?p=%40material-ui%2Fcore .

@mbrookes What do you think of a @material-ui/styles package?

[mbrookes]

@oliviertassinari sure, why not. What else would you include?

Yes, it's a dupe of #10789.

[petermikitsh]

@oliviertassinari Besides what we've discussed here already (e.g., moving the styles directory into a separate module), is there anything else you'd like to see in a PR that could close this issue and #10789?

[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!

[oliviertassinari]

I would add polished to the list of libraries to benchmark against. I agree, setAlpha > fade. What do you think of rgba as a name suggestion?

[mbrookes]

polished added. Interesting that two other the libraries use fade in the function name, and that polished uses "fade" in the description fo rgba, so maybe it isn't currently so far off after all.

The only issue with rgba() is the potential for confusion with CSS rgba(), which has a different syntax.

[oliviertassinari]

I would add CSS, Post CSS, SASS and Less in the benchmark list. We handle the same problem https://alligator.io/css/color-function/.