[docs] Palette Object

[randomValue]

We really love to work with Material UI, never the less we are having big trouble understanding all the colors in theme-pallets, and where they are used.

For example:

1. we know the primary dark is used for button hovered state. but what else is it used for?
2. We have actions like hover, active, pressed etc. We only could find the hover and active state. it would be great to know, why the focus state is not used for buttons.
3. Where are the text object entries colors primary, secondary, disabled, hint used?
   We would really appreciate if the docs would explain all the object entries.

Thank you very much

[MikeRawding]

There is definitely a lack of documentation about how light primary and dark variants of colors are used in Material-UI. Some of the community seems to incorrectly believe these variants are used for "light mode" and "dark mode" including this video which is linked from the documentation https://youtu.be/Q4o0GmfNpJc?t=210

[oliviertassinari]

@MikeRawding I'm not sure what we can do to fix this confusion. The objective is to have the components use the palette with as little hidden transformations as possible.

[MikeRawding]

@oliviertassinari here are a few things we could do that might help.

1. Add a sentence somewhere on the customization/color or customization/palette page explaining that some components, like button, consume multiple variants of the selected color. This would help make it clear that palette.primary.dark is used even if palette.type === 'light'.
2. Have the creator of the video linked above add text stating that their explanation of dark mode is incorrect. Seems reasonable to ask for this accuracy since his content is being linked from the official documentation.
3. customization/palette/#dark-mode makes it look like an app that supports light and dark mode would have just one theme and toggle palette.type. This makes it seem like dark mode variants of pallet object must be somewhere in the single theme. However, for an app to really have a light and dark mode, the app would need to have two themes with different palettes. In fact, when I toggle the docs into dark mode I see that theme.palette.primary changes.