[material-ui] Stabilize CssVarsProvider and extendTheme

apps/pigment-css-next-app/next.config.js

@@ -1,7 +1,7 @@
 /* eslint-env node */
 // eslint-ignore-next-line import/no-unresolved
 const { withPigment } = require('@pigment-css/nextjs-plugin');
-const { experimental_extendTheme: extendTheme } = require('@mui/material/styles');
+const { extendTheme } = require('@mui/material/styles');
 
 /**
  * @typedef {import('@pigment-css/nextjs-plugin').PigmentOptions} PigmentOptions

apps/pigment-css-vite-app/src/augment.ts

@@ -1,9 +1,9 @@
-import type { experimental_extendTheme } from '@mui/material/styles';
+import type { extendTheme } from '@mui/material/styles';
 import '@pigment-css/react/theme';
 
 declare module '@pigment-css/react/theme' {
   export interface ThemeArgs {
-    theme: ReturnType<typeof experimental_extendTheme> & {
+    theme: ReturnType<typeof extendTheme> & {
       applyDarkStyles<T>(obj: T): Record<string, T>;
     };
   }

apps/pigment-css-vite-app/src/extend-zero.ts

@@ -1,8 +1,8 @@
-import type { experimental_extendTheme } from '@mui/material/styles';
+import type { extendTheme } from '@mui/material/styles';
 
 declare module '@pigment-css/react/theme' {
   interface ThemeArgs {
-    theme: ReturnType<typeof experimental_extendTheme> & {
+    theme: ReturnType<typeof extendTheme> & {
       applyDarkStyles<T>(obj: T): Record<string, T>;
     };
   }

apps/pigment-css-vite-app/vite.config.ts

@@ -3,7 +3,7 @@ import { defineConfig, splitVendorChunkPlugin } from 'vite';
 import reactPlugin from '@vitejs/plugin-react';
 import Pages from 'vite-plugin-pages';
 import { pigment } from '@pigment-css/vite-plugin';
-import { experimental_extendTheme as extendTheme } from '@mui/material/styles';
+import { extendTheme } from '@mui/material/styles';
 
 const theme = extendTheme({
   getSelector: function getSelector(colorScheme, css) {

docs/data/joy/integrations/material-ui/material-ui.md

@@ -29,8 +29,8 @@ Render Joy UI's `CssVarsProvider` inside Material UI's provider and use `THEME
 
 ```js
 import {
-  experimental_extendTheme as materialExtendTheme,
-  Experimental_CssVarsProvider as MaterialCssVarsProvider,
+  extendTheme as materialExtendTheme,
+  CssVarsProvider as MaterialCssVarsProvider,
   THEME_ID as MATERIAL_THEME_ID,
 } from '@mui/material/styles';
 import { CssVarsProvider as JoyCssVarsProvider } from '@mui/joy/styles';

docs/data/material/experimental-api/css-theme-variables/customization.md → docs/data/material/customization/css-theme-variables/configuration.md

@@ -1,16 +1,13 @@
-# CSS theme variables - Customization
+# CSS theme variables - Configuration
 
-<p class="description">A guide for customizing CSS theme variables in Material UI.</p>
+<p class="description">A guide for configuring CSS theme variables in Material UI.</p>
 
 ## Theming
 
-`experimental_extendTheme` is an API that extends the default theme. It returns a theme that can only be used by the `Experimental_CssVarsProvider`.
+`extendTheme` is an API that extends the default theme. It returns a theme that can only be used by the `CssVarsProvider`.
 
 ```js
-import {
-  Experimental_CssVarsProvider as CssVarsProvider,
-  experimental_extendTheme as extendTheme,
-} from '@mui/material/styles';
+import { CssVarsProvider, extendTheme } from '@mui/material/styles';
 
 const theme = extendTheme();
 // ...custom theme
@@ -181,7 +178,7 @@ Or use `var()` to refer to the CSS variable directly:
 ```
 
 :::warning
-If you're using a [custom prefix](/material-ui/experimental-api/css-theme-variables/customization/#changing-variable-prefixes), make sure to replace the default `--mui`.
+If you're using a [custom prefix](/material-ui/customization/css-theme-variables/configuration/#changing-variable-prefixes), make sure to replace the default `--mui`.
 :::
 
 ### TypeScript
@@ -289,7 +286,7 @@ function App() {
 }
 ```
 
-For a server-side application, provide the same value to [`getInitColorSchemeScript()`](/material-ui/experimental-api/css-theme-variables/usage/#server-side-rendering):
+For a server-side application, provide the same value to [`getInitColorSchemeScript()`](/material-ui/customization/css-theme-variables/usage/#server-side-rendering):
 
 ```js
 getInitColorSchemeScript({

docs/data/material/experimental-api/css-theme-variables/overview.md → docs/data/material/customization/css-theme-variables/overview.md

@@ -11,8 +11,15 @@ If this is your first time encountering CSS variables, you should check out [the
 
 ## Introduction
 
-CSS theme variable support is a new feature in Material UI added in [`v5.6.0`](https://github.com/mui/material-ui/releases/tag/v5.6.0) (but not enabled by default). It tells Material UI components to use the generated CSS theme variables instead of raw values. This provides significant improvements in developer experience related to theming and customization.
-With these variables, you can inject a theme into your app's stylesheet _at build time_ to apply the user's selected settings before the whole app is rendered.
+CSS theme variables replace raw values in Material UI components for a better developer experience because, in the browser dev tool, you will see which theme token is used as a value.
+
+In addition with these variables, you can inject a theme into your app's stylesheet _at build time_ to apply the user's selected settings before the whole app is rendered.
+
+:::info
+The `CssVarsProvider` is built on top of the [`ThemeProvider`](/material-ui/customization/theming/#themeprovider) with extra features like CSS variable generation, storage synchronization, unlimited color schemes, and more.
+
+If you have an existing theme, you can migrate to CSS theme variables by following the [migration guide](/material-ui/migration/migration-css-theme-variables/).
+:::
 
 ## Advantages
 
@@ -60,7 +67,7 @@ const darkTheme = createTheme({
 **CSS theme variables**: Light and dark colors are consolidated into a theme.
 
 ```js
-import { experimental_extendTheme as extendTheme } from '@mui/material/styles';
+import { extendTheme } from '@mui/material/styles';
 
 // `extendTheme` is a new API
 const theme = extendTheme({
@@ -117,6 +124,6 @@ extendTheme({
 
 ## What's next
 
-- To start a new project with CSS theme variables, check out the [basic usage guide](/material-ui/experimental-api/css-theme-variables/usage/).
-- For an existing Material UI project, check out the [migration guide](/material-ui/experimental-api/css-theme-variables/migration/).
-- For theming and customization, check out the [how-to guide](/material-ui/experimental-api/css-theme-variables/customization/).
+- To start a new project with CSS theme variables, check out the [basic usage guide](/material-ui/customization/css-theme-variables/usage/).
+- For an existing Material UI project, check out the [migration guide](/material-ui/migration/migration-css-theme-variables/).
+- For theming and customization, check out the [how-to guide](/material-ui/customization/css-theme-variables/configuration/).

docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.js → docs/data/material/customization/css-theme-variables/usage/CssVarsBasic.js

@@ -1,8 +1,5 @@
 import * as React from 'react';
-import {
-  experimental_extendTheme as extendTheme,
-  Experimental_CssVarsProvider as CssVarsProvider,
-} from '@mui/material/styles';
+import { extendTheme, CssVarsProvider } from '@mui/material/styles';
 import Button from '@mui/material/Button';
 
 const theme = extendTheme({

docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx → docs/data/material/customization/css-theme-variables/usage/CssVarsBasic.tsx

@@ -1,8 +1,5 @@
 import * as React from 'react';
-import {
-  experimental_extendTheme as extendTheme,
-  Experimental_CssVarsProvider as CssVarsProvider,
-} from '@mui/material/styles';
+import { extendTheme, CssVarsProvider } from '@mui/material/styles';
 import Button from '@mui/material/Button';
 
 const theme = extendTheme({

docs/data/material/experimental-api/css-theme-variables/usage/usage.md → docs/data/material/customization/css-theme-variables/usage/usage.md

@@ -1,11 +1,11 @@
 # CSS theme variables - Usage
 
-<p class="description">Learn how to use the experimental APIs to adopt CSS theme variables.</p>
+<p class="description">Learn how to adopt CSS theme variables.</p>
 
 ## Getting started
 
-The CSS variables API relies on a new experimental provider for the theme called `Experimental_CssVarsProvider` to inject styles into Material UI components.
-In addition to providing the theme in the inner React context, this new provider also generates CSS variables out of all tokens in the theme that are not functions, and makes them available in the context as well.
+The CSS variables API relies on a provider called `CssVarsProvider` to inject styles into Material UI components.
+`CssVarsProvider` generates CSS variables out of all tokens in the theme that are serializable, and makes them available in the React context along with the theme itself via [`ThemeProvider`](/material-ui/customization/theming/#theme-provider).
 
 Once the `App` renders on the screen, you will see the CSS theme variables in the HTML `:root` stylesheet.
 The variables are flattened and prefixed with `--mui` by default:
@@ -27,17 +27,16 @@ The following demo uses `--md-demo` as a prefix for the variables:
 
 :::info
 The `CssVarsProvider` is built on top of the [`ThemeProvider`](/material-ui/customization/theming/#themeprovider) with extra features like CSS variable generation, storage synchronization, unlimited color schemes, and more.
+
+If you have an existing theme, you can migrate to CSS theme variables by following the [migration guide](/material-ui/migration/migration-css-theme-variables/).
 :::
 
 ## Toggle between light and dark mode
 
 The `useColorScheme` hook lets you read and update the user-selected mode:
 
 ```jsx
-import {
-  Experimental_CssVarsProvider as CssVarsProvider,
-  useColorScheme,
-} from '@mui/material/styles';
+import { CssVarsProvider, useColorScheme } from '@mui/material/styles';
 
 // ModeSwitcher is an example interface for toggling between modes.
 // Material UI does not provide the toggle interface—you have to build it yourself.
@@ -111,7 +110,7 @@ The structure of this object is nearly identical to the theme structure, the onl
   ```
 
   :::warning
-  If you have set up a [custom prefix](/material-ui/experimental-api/css-theme-variables/customization/#changing-variable-prefixes), make sure to replace the default `--mui`.
+  If you have set up a [custom prefix](/material-ui/customization/css-theme-variables/configuration/#changing-variable-prefixes), make sure to replace the default `--mui`.
   :::
 
 ## Server-side rendering

docs/data/material/customization/theming/theming.md

@@ -10,7 +10,7 @@ To promote greater consistency between apps, light and dark theme types are avai
 
 ## Theme provider
 
-If you wish to customize the theme, you need to use the `ThemeProvider` component in order to inject a theme into your application.
+Use `ThemeProvider` or [`CssVarsProvider`](#css-variables-provider) to inject a custom theme into your application.
 However, this is optional; Material UI components come with a default theme.
 
 `ThemeProvider` relies on the [context feature of React](https://react.dev/learn/passing-data-deeply-with-context) to pass the theme down to the components, so you need to make sure that `ThemeProvider` is a parent of the components you are trying to customize.
@@ -45,7 +45,8 @@ const theme = createTheme({
 ```
 
 :::warning
-`vars` is a private field for [CSS theme variables](/material-ui/experimental-api/css-theme-variables/overview/). It will throw an error if you try to pass a value to it:
+`vars` is an autogenerated field for [CSS theme variables](/material-ui/customization/css-theme-variables/overview/).
+It will throw an error if you try to pass a value to it:
 
 ```jsx
 createTheme({
@@ -114,6 +115,13 @@ You can extend the outer theme by providing a function:
 
 {{"demo": "ThemeNestingExtend.js"}}
 
+## CSS variables provider
+
+The `CssVarsProvider` is built on top of the `ThemeProvider` with extra features like theme CSS variables generation, built-in color scheme synchronization with the user's system preference, and more.
+The `CssVarsProvider` is built on top of the `ThemeProvider` with extra features like theme CSS variables generation, built-in color scheme synchronization, user's system preference, and more.
+
+To start using the `CssVarsProvider`, check out the [basic usage guide](/material-ui/customization/css-theme-variables/usage/). If you are using the `ThemeProvider`, read the [migration guide](/material-ui/migration/migration-css-theme-variables/).
+
 ## API
 
 ### `createTheme(options, ...args) => theme`

docs/data/material/design-resources/material-ui-sync/material-ui-sync.md

@@ -237,16 +237,13 @@ You can also check out the Storybook preview to test the Material UI version of
 ## Using the generated theme
 
 :::warning
-Themes generated by Sync must be used with Material UI's [`CssVarsProvider`](/material-ui/experimental-api/css-theme-variables/migration/)—the default [`ThemeProvider`](/material-ui/customization/theming/#theme-provider) is not supported.
+Themes generated by Sync must be used with Material UI's [`CssVarsProvider`](/material-ui/migration/migration-css-theme-variables/)—the [`ThemeProvider`](/material-ui/customization/theming/#theme-provider) is not supported.
 :::
 
 Here's an example of how to add a Sync-generated theme to your codebase:
 
 ```tsx title="_app.tsx"
-import {
-  experimental_extendTheme as extendTheme,
-  Experimental_CssVarsProvider as CssVarsProvider,
-} from '@mui/material/styles';
+import { extendTheme, CssVarsProvider } from '@mui/material/styles';
 
 export default function MyApp({ Component, pageProps }) {
   const theme = extendTheme({