[material-ui] Stabilize CssVarsProvider and extendTheme

[siriwatknp]

Changes

• Add stable APIs without experimental prefix and replace all the usages in the repo
• Add warning to experimental APIs
• Move docs from "experimental" section to "customization" (I'd like to keep the structure the same in this PR, I have a plan to improve the content in a separate PR)

---

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

[mui-bot]

Netlify deploy preview

• docs/data/joy/integrations/material-ui/material-ui.md
• docs/data/material/customization/css-theme-variables/configuration.md
• docs/data/material/customization/css-theme-variables/overview.md
• docs/data/material/customization/css-theme-variables/usage/usage.md
• docs/data/material/customization/theming/theming.md

@material-ui/core: parsed: +0.10% , gzip: +0.10%

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 42f36af

[mnajdova]

Left few small comments, from technical point of view it looks good 👍

[samuelsycamore]

I don't love this path name: /material/customization/foobar/customization just looks weird to me with customization repeated. I'm not sure which one really needs to be replaced but it seems like this doc file name is the simpler choice.

[danilo-leal]

+1 here, too — maybe this page could be called "Customizing CSS theme variables"? Then, drop the hyphen on the title!

[siriwatknp]

I changed to "configuration", is it better?

[DiegoAndai]

Same as Marija, technical changes look good to me

Good job carrying this through the finish line 🚀

[DiegoAndai]

@siriwatknp this closes #41070 right?

[danilo-leal]

🚢 it!

[oliviertassinari]

What do you think about renaming extendTheme() to createCssVarsTheme(), so it's clear when compared to createTheme() what it is?

At this point, there is no reason not to move CSS variables all-in. Keeping a hybrid mode brings no value beyond allowing people to migrate. But even then it can very likely be done with barely any breaking changes. I mean, why would there be any? So I would deprecate createTheme() for createLegacyTheme() to free the namespace. And try to rename to createCssVarsTheme() to createTheme().

On the Pigment CSS, side, I think that we could already rename to createTheme(): mui/pigment-css#131.

---

On a different topic, looking at the source, I'm confused about the architecture. I would propose we create 7 issues, one for each:

• 1.

  material-ui/packages/mui-material/src/styles/ThemeProvider.js

  Line 12 in 1ee901b

  themeId={scopedTheme ? THEME_ID : undefined}

Why don't we straight forward the theme id? Why do we check if the theme exists before forwarding it? I mean, wouldn't it be simpler and more predictable to have themeId={THEME_ID} here and in all the other places?

• 2. Why do we have argument mutations?

material-ui/packages/mui-system/src/cssVars/createCssVarsProvider.js

Line 189 in 1ee901b

themeProp.defaultColorScheme = resolvedDefaultColorScheme;

#41446 (comment)

Couldn't we remove those?

• 3. Why is there all of these concerns attached to the theme:

• colorSchemeSelector

• attribute

• getSelector The "getSelector" API feels strange pigment-css#128 point 1.

• generateThemeVars

• generateStyleSheets

• generateSpacing [system] Add spacing theme token to be used in theme.spacing() #40224 (comment)

Could we remove all of this? Place them into a dedicated structure, or as arguments to the theme creator.

• 4. Why do we have a colorSchemeSelector, attribute API in the first place when we have getSelector(). Isn't it a straight duplicate? Point 1 in The "getSelector" API feels strange pigment-css#128: couldn't we replace all of this with getColorSchemeSelector?

• 5. Why is generateStyleSheets created when creating the extendTheme and not created by the CssVarProvider component?

• 6. Why is generateThemeVars created when creating the extendTheme, not used to create the vars, but then used to recreate the vars again in CssVarProvider. Can we only do it once and in extendTheme?

• 7. Why is resolveTheme called like this when it doesn't resolve the Theme ID but transfers the theme. Also, I don't understand why this exists in the first place. Shouldn't it be done in extendTheme, so theme.typography has correct values?