[docs][material] Improve documentation about adding custom colors

[DiegoAndai]

• I have followed (at least) the PR section of the contributing guide.

Closes: #29595

Summary

Improve documentation regarding adding new colors using a color object:

• Clearly indicate that for custom colors the light, dark, and contrastText tokens are required and not calculated automatically, which differs from default colors.
• Add an example of how to use the augmentColor function to augment custom colors.
• Fix examples so custom colors have all the required tokens

Note

I also wanted to improve the warning/error that users would get when using a component that requires light, dark, or contrastText (see the Chip's contrastText issue: #37676). But after a second thought, it seemed very cumbersome and overhead to do given the small use case for which the warning would be helpful.

If you disagree and think it would be worth it, I would love to discuss approaches to adding the warning 😊 cc: @mui/core

[mui-bot]

Netlify deploy preview

• docs/data/material/components/buttons/buttons-pt.md
• docs/data/material/components/buttons/buttons-zh.md
• docs/data/material/components/buttons/buttons.md
• docs/data/material/customization/palette/palette.md

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against 1019e20

[samuelsycamore]

Great addition @DiegoAndai ! My comments here are mostly about style and structure.

[DiegoAndai]

After @samuelsycamore's feedback, I started reworking some examples and concluded that the palette docs needed a reorganization. Related information was scattered and the structure wasn't easy-to-follow. Here are the changes I introduced:

• Add color tokens section
• Separate default colors and custom colors sections, turn examples into live demos rather than static code and have one atomic example for each piece of information rather than big examples
• Add explanation and examples for contrast threshold, tonal offset, and adding new color tokens
• Link non-palette colors to custom variables docs, as the information was duplicated

I was very cautious of not removing anything, but rather reorganizing. Everything that was there is still there, except for the non-palette colors explanation as that was redirected to custom variables.

Notes

• I recommend checking the deploy preview first when reviewing and comparing it to the actual palette docs
• The buttons and mui-core-v5 blog changes were due to the removal of the #adding-new-colors section, and were redirected to the #custom-colors section
• I Disabled formatedTSDemos for the palette page. I did it because it was forcing the preview of the examples to be the examples returned JSX, but for these examples, the theme creation section of the code is the important information.

[mj12albert]

@DiegoAndai The demos look great!

I noticed that the text lists the colors in the order main, light, dark, but the actual demo code the order is light, main, dark – maybe it would be clearest to label the little color chips as well ~

[samuelsycamore]

Sorry it took me so long to get to this @DiegoAndai ! This is a major improvement for sure. The vast majority of my suggestions here are for copy editing, style, and grammar. We should make sure that the hierarchy of headers and subheaders makes sense in the final draft.

[DiegoAndai]

Hey @samuelsycamore and @mj12albert! thanks for the feedback, I implemented it and it's ready for your re-review

@samuelsycamore regarding this comment, maybe we could just list the colors and then link to Material's Color System for the explanations?

[samuelsycamore]

@samuelsycamore regarding this comment, maybe we could just list the colors and then link to Material's Color System for the explanations?

That sounds good to me. Go for it! 🤝

[DiegoAndai]

@samuelsycamore I reworded the color's descriptions to be shorter and added a link to Material's Color System, let me know what you think 😊

[mj12albert]

Looks great!

[samuelsycamore]

LGTM! 🚀