[core] Improve instructions for the @material-ui/styles migration

docs/src/pages.ts

@@ -242,14 +242,6 @@ const pages: readonly MuiPage[] = [
       { pathname: '/system/styled', title: 'styled' },
     ],
   },
-  {
-    pathname: '/styles',
-    children: [
-      { pathname: '/styles/basics' },
-      { pathname: '/styles/advanced' },
-      { pathname: '/styles/api', title: 'API' },
-    ],
-  },
   {
     pathname: '/customization',
     children: [
@@ -298,6 +290,14 @@ const pages: readonly MuiPage[] = [
       { pathname: '/guides/flow' },
     ],
   },
+  {
+    pathname: '/styles',
+    children: [
+      { pathname: '/styles/basics' },
+      { pathname: '/styles/advanced' },
+      { pathname: '/styles/api', title: 'API' },
+    ],
+  },
   {
     pathname: 'https://material-ui.com/store/',
     title: 'Premium themes',

docs/src/pages/styles/advanced/advanced.md

@@ -2,6 +2,8 @@
 
 <p class="description">This section covers more advanced usage of @material-ui/core/styles.</p>
 
+> **Note**: `@material-ui/styles` is the _**legacy**_ styling solution for Material-UI. It is deprecated in v5. It depends on [JSS](https://cssinjs.org/) as a styling solution, which is not used in the `@material-ui/core` anymore. If you don't want to have both emotion & JSS in your bundle, please refer to the [`@material-ui/system`](/system/basics/) documentation which is the recommended alternative.
+
 ## Theming
 
 Add a `ThemeProvider` to the top level of your app to pass a theme down the React component tree. Then, you can access the theme object in style functions.

docs/src/pages/styles/basics/basics.md

@@ -2,6 +2,8 @@
 
 <p class="description">You can use Material-UI's styling solution in your app, whether or not you are using Material-UI components.</p>
 
+> **Note**: `@material-ui/styles` is the _**legacy**_ styling solution for Material-UI. It will be deprecated in v5. It depends on JSS as a styling solution, which is not used in the `@material-ui/core` anymore. If you would not like to have both emotion & JSS in your bundle, please refer to the [`@material-ui/system`](/system/basics/) documentation which is the recommended alternative.
+
 Material-UI aims to provide a strong foundation for building dynamic UIs.
 For the sake of simplicity, **we expose the styling solution used in Material-UI components** as the `@material-ui/styles` package.
 You can use it, but you don't have to, since Material-UI is also [interoperable with](/guides/interoperability/) all the other major styling solutions.
@@ -25,16 +27,16 @@ Material-UI's styling solution is inspired by many other styling libraries such
 
 ## Installation
 
-> `@material-ui/styles` is re-exported as `@material-ui/core/styles` - you only need to install it if you wish to use it independently from Material-UI.
-
 To install and save in your `package.json` dependencies, run:
 
+<!-- #default-branch-switch -->
+
 ```sh
 // with npm
-npm install @material-ui/styles
+npm install @material-ui/styles@next
 
 // with yarn
-yarn add @material-ui/styles
+yarn add @material-ui/styles@next
 ```
 
 ## Getting started
@@ -212,7 +214,7 @@ const useStyles = makeStyles((theme) => ({
 
 ## Using the theme context
 
-Starting from v5, Material-UI no longer uses JSS as its default styling solution. If you still want to use the utilities exported by `@material-ui/styles`, you will need to provide the `theme` as part of the context. For this, you can use the `ThemeProvider` component available in `@material-ui/styles`, or, if you are already using `@material-ui/core`, you should use the one exported from `@material-ui/core/styles` so that the same `theme` is available for components from '@material-ui/core'.
+Starting from v5, Material-UI no longer uses JSS as its default styling solution. If you still want to use the utilities exported by `@material-ui/styles` and they depend on the `theme`, you will need to provide the `theme` as part of the context. For this, you can use the `ThemeProvider` component available in `@material-ui/styles`, or, if you are already using `@material-ui/core`, you should use the one exported from `@material-ui/core/styles` so that the same `theme` is available for components from '@material-ui/core'.
 
 ```jsx
 import { makeStyles } from '@material-ui/styles';

packages/material-ui/src/styles/index.d.ts

@@ -75,3 +75,7 @@ export interface StyledComponentProps<ClassKey extends string = string> {
    */
   classes?: Partial<ClassNameMap<ClassKey>>;
 }
+
+export { default as makeStyles } from './makeStyles';
+export { default as withStyles } from './withStyles';
+export { default as withTheme } from './withTheme';

packages/material-ui/src/styles/index.js

@@ -24,3 +24,8 @@ export { default as styled } from './styled';
 export { default as experimentalStyled } from './styled';
 export { default as ThemeProvider } from './ThemeProvider';
 export { StyledEngineProvider } from '@material-ui/system';
+// The legacy utilities from @material-ui/styles
+// These are just empty functions that throws when invoked
+export { default as makeStyles } from './makeStyles';
+export { default as withStyles } from './withStyles';
+export { default as withTheme } from './withTheme';

packages/material-ui/src/styles/makeStyles.d.ts

@@ -0,0 +1 @@
+export default function makeStyles(stylesCreator: any, options?: object): never;

packages/material-ui/src/styles/makeStyles.js

@@ -0,0 +1,9 @@
+import MuiError from '@material-ui/utils/macros/MuiError.macro';
+
+export default function makeStyles(stylesCreator, options) {
+  throw new MuiError(
+    'Material-UI: makeStyles is not longer exported from @material-ui/core/styles.\n' +
+      'You have to import it from @material-ui/styles.\n' +
+      'See https://material-ui.com/r/migration-v4/#material-ui-core-styles for more details.',
+  );
+}

packages/material-ui/src/styles/withStyles.d.ts

@@ -0,0 +1 @@
+export default function withStyles(stylesCreator: any, options?: object): never;

packages/material-ui/src/styles/withStyles.js

@@ -0,0 +1,9 @@
+import MuiError from '@material-ui/utils/macros/MuiError.macro';
+
+export default function withStyles(stylesCreator, options) {
+  throw new MuiError(
+    'Material-UI: withStyles is not longer exported from @material-ui/core/styles.\n' +
+      'You have to import it from @material-ui/styles.\n' +
+      'See https://material-ui.com/r/migration-v4/#material-ui-core-styles for more details.',
+  );
+}

packages/material-ui/src/styles/withTheme.d.ts

@@ -0,0 +1 @@
+export default function withTheme(Component: any): never;

packages/material-ui/src/styles/withTheme.js

@@ -0,0 +1,9 @@
+import MuiError from '@material-ui/utils/macros/MuiError.macro';
+
+export default function withTheme(Component) {
+  throw new MuiError(
+    'Material-UI: withTheme is not longer exported from @material-ui/core/styles.\n' +
+      'You have to import it from @material-ui/styles.\n' +
+      'See https://material-ui.com/r/migration-v4/#material-ui-core-styles for more details.',
+  );
+}