[material-ui] Allow nested theme creation with vars (#45368)

docs/public/static/error-codes.json

@@ -18,6 +18,6 @@
   "17": "MUI: Expected valid input target. Did you use a custom `slots.input` and forget to forward refs? See https://mui.com/r/input-component-ref-interface for more info.",
   "18": "MUI: The provided shorthand %s is invalid. The format should be `@<breakpoint | number>` or `@<breakpoint | number>/<container>`.\nFor example, `@sm` or `@600` or `@40rem/sidebar`.",
   "19": "MUI: The `experimental_sx` has been moved to `theme.unstable_sx`.For more details, see https://github.com/mui/material-ui/pull/35150.",
-  "20": "MUI: `vars` is a private field used for CSS variables support.\nPlease use another name.",
+  "20": "MUI: `vars` is a private field used for CSS variables support.\nPlease use another name or follow the [docs](https://mui.com/material-ui/customization/css-theme-variables/usage/) to enable the feature.",
   "21": "MUI: The `colorSchemes.%s` option is either missing or invalid."
 }

packages/mui-material/src/styles/createTheme.test.js

@@ -535,11 +535,42 @@ describe('createTheme', () => {
     } catch (error) {
       expect(error.message).to.equal(
         'MUI: `vars` is a private field used for CSS variables support.\n' +
-          'Please use another name.',
+          'Please use another name or follow the [docs](https://mui.com/material-ui/customization/css-theme-variables/usage/) to enable the feature.',
       );
     }
   });
 
+  it('should not throw for nested theme that includes `vars` node', () => {
+    const outerTheme = createTheme({
+      cssVariables: true,
+      palette: {
+        secondary: {
+          main: deepOrange[500],
+        },
+      },
+    });
+
+    expect(() =>
+      render(
+        <ThemeProvider theme={outerTheme}>
+          <ThemeProvider
+            theme={(theme) => {
+              return createTheme({
+                ...theme,
+                palette: {
+                  ...theme.palette,
+                  primary: {
+                    main: green[500],
+                  },
+                },
+              });
+            }}
+          />
+        </ThemeProvider>,
+      ),
+    ).not.to.throw();
+  });
+
   it('should create a new object', () => {
     const defaultTheme = createTheme({
       cssVariables: {

packages/mui-material/src/styles/createThemeNoVars.js

@@ -24,10 +24,16 @@ function createThemeNoVars(options = {}, ...args) {
     ...other
   } = options;
 
-  if (options.vars) {
+  if (
+    options.vars &&
+    // The error should throw only for the root theme creation because user is not allowed to use a custom node `vars`.
+    // `generateThemeVars` is the closest identifier for checking that the `options` is a result of `createTheme` with CSS variables so that user can create new theme for nested ThemeProvider.
+    options.generateThemeVars === undefined
+  ) {
     throw /* minify-error */ new Error(
       'MUI: `vars` is a private field used for CSS variables support.\n' +
-        'Please use another name.',
+        // #host-reference
+        'Please use another name or follow the [docs](https://mui.com/material-ui/customization/css-theme-variables/usage/) to enable the feature.',
     );
   }