[docs] Polish migration guide

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

@@ -56,7 +56,6 @@ Bear in mind that the `.MuiAccordionSummary-gutters` class is applied to the com
 ```diff
 -.MuiAccordionSummary-root .MuiAccordionSummary-contentGutters
 +.MuiAccordionSummary-root.MuiAccordionSummary-gutters .MuiAccordionSummary-content
- />
 ```
 
 ```diff
@@ -240,18 +239,18 @@ The AvatarGroup's `slotProps.additionalAvatar` was deprecated in favor of `slotP
 ```diff
  <AvatarGroup
    slotProps={{
--    additionalAvatar: {color: "red"}
-+    surplus: {color: "red"}
+-    additionalAvatar: { color: 'red' },
++    surplus: { color: 'red' },
    }}
- />;
+ >
 ```
 
 ```diff
  MuiAvatarGroup: {
    defaultProps: {
      slotProps: {
--      additionalAvatar: {color: "red"}
-+      surplus: {color: "red"}
+-      additionalAvatar: { color: 'red' },
++      surplus: { color: 'red' },
      },
    },
  },
@@ -264,11 +263,11 @@ The AvatarGroup's `componentsProps` was deprecated in favor of `slotProps`:
 ```diff
  <AvatarGroup
 -  componentsProps={{
--    additionalAvatar: {color: "red"}
+-    additionalAvatar: { color: 'red' },
 +  slotProps={{
-+    surplus: {color: "red"}
++    surplus: { color: 'red' },
    }}
- />;
+ >
 ```
 
 ```diff
@@ -910,9 +909,9 @@ The CSS classes that composed the `circle` CSS class and `variant` prop values w
 Here's how to migrate:
 
 ```diff
-- .MuiCircularProgress-circleDeterminate
+-.MuiCircularProgress-circleDeterminate
 +.MuiCircularProgress-determinate > .MuiCircularProgress-circle
-- .MuiCircularProgress-circleIndeterminate
+-.MuiCircularProgress-circleIndeterminate
 +.MuiCircularProgress-indeterminate > .MuiCircularProgress-circle
 ```
 
@@ -1141,7 +1140,7 @@ The Grid's `wrap` prop was deprecated in favor of `flexWrap` MUI System prop:
  <Grid
 -  wrap="nowrap"
 +  flexWrap="nowrap"
- />;
+ >
 ```
 
 ## Modal
@@ -1160,7 +1159,7 @@ The Modal's `components` prop was deprecated in favor of `slots`:
  <Modal
 -  components={{ Root: CustomRoot, Backdrop: CustomBackdrop }}
 +  slots={{ root: CustomRoot, backdrop: CustomBackdrop }}
- />
+ >
 ```
 
 ### componentsProps
@@ -1171,7 +1170,7 @@ The Modal's `componentsProps` prop was deprecated in favor of `slotProps`:
  <Modal
 -  componentsProps={{ root: { testid: 'root-id' }, backdrop: { testid: 'backdrop-id' } }}
 +  slotProps={{ root: { testid: 'root-id' }, backdrop: { testid: 'backdrop-id' } }}
- />
+ >
 ```
 
 ## OutlinedInput
@@ -1395,7 +1394,8 @@ Here's how to migrate:
 -      [`& .${tabClasses.iconWrapper}`]: {
 +      [`& .${tabClasses.icon}`]: {
          color: 'red',
-        },
+       },
+     },
    },
  },
 ```
@@ -1415,9 +1415,9 @@ The CSS classes that composed the `direction` prop and `icon` prop were removed.
 Here's how to migrate:
 
 ```diff
-- .MuiTableSortLabel-iconDirectionDesc
+-.MuiTableSortLabel-iconDirectionDesc
 +.MuiTableSortLabel-directionDesc > .MuiTableSortLabel-icon
-- .MuiTableSortLabel-iconDirectionAsc
+-.MuiTableSortLabel-iconDirectionAsc
 +.MuiTableSortLabel-directionAsc > .MuiTableSortLabel-icon
 ```
 
@@ -1454,18 +1454,18 @@ All of the TextField's slot props (`*Props`) props were deprecated in favor of e
 
 ```diff
  <TextField
--    InputProps={CustomInputProps}
--    inputProps={CustomHtmlInputProps}
--    SelectProps={CustomSelectProps}
--    InputLabelProps={CustomInputLabelProps}
--    FormHelperTextProps={CustomFormHelperProps}
-+    slotProps={{
-+        input: CustomInputProps
-+        htmlInput: CustomHtmlInputProps
-+        select: CustomSelectProps
-+        inputLabel: CustomInputLabelProps
-+        formHelper: CustomFormHelperProps
-+    }}
+-  InputProps={CustomInputProps}
+-  inputProps={CustomHtmlInputProps}
+-  SelectProps={CustomSelectProps}
+-  InputLabelProps={CustomInputLabelProps}
+-  FormHelperTextProps={CustomFormHelperProps}
++  slotProps={{
++    input: CustomInputProps
++    htmlInput: CustomHtmlInputProps
++    select: CustomSelectProps
++    inputLabel: CustomInputLabelProps
++    formHelper: CustomFormHelperProps
++  }}
  />
 ```
 
@@ -1533,9 +1533,9 @@ The CSS classes that composed the `line` CSS class and `orientation` prop values
 Here's how to migrate:
 
 ```diff
-- .MuiStepConnector-lineHorizontal
+-.MuiStepConnector-lineHorizontal
 +.MuiStepConnector-horizontal > .MuiStepConnector-line
-- .MuiStepConnector-lineVertical
+-.MuiStepConnector-lineVertical
 +.MuiStepConnector-vertical > .MuiStepConnector-line
 ```
 

docs/data/material/migration/migrating-to-v6/migrating-to-pigment-css.md

@@ -6,7 +6,9 @@ Before going through this guide, make sure you have [migrated to Material UI v6
 
 ## Introduction
 
-The default styling engine of Material UI v6 is [Emotion](https://emotion.sh/docs/introduction). It lets you write styles in a CSS-in-JS fashion, which is great for dynamic styles that depend on states and props. However, it has some performance drawbacks when it comes to frequent re-renders because the style recalculation happens on the client-side. It also does not fully support [React Server Components](https://react.dev/reference/rsc/server-components), a new rendering paradigm that renders components ahead of time on the server.
+The default styling engine of Material UI v6 is [Emotion](https://emotion.sh/docs/introduction).
+It lets you write styles in a CSS-in-JS fashion, which is great for dynamic styles that depend on states and props. However, it has some performance drawbacks when it comes to frequent re-renders because the style recalculation happens on the client-side.
+It also does not fully support [React Server Components](https://react.dev/reference/rsc/server-components), a new rendering paradigm that renders components ahead of time on the server.
 
 Pigment CSS aims to solve these problems while keeping the same developer experience of writing styles in a CSS-in-JS fashion.
 It can work alongside Emotion to ease the migration process, but it is recommended to fully migrate to Pigment CSS in the end.
@@ -15,8 +17,8 @@ It can work alongside Emotion to ease the migration process, but it is recommend
 
 Pigment CSS can be used with one of the following frameworks:
 
-- [Next.js App Router](https://nextjs.org/docs/app) with Webpack 5 (Turbo is not supported yet)
 - [Vite](https://vitejs.dev/)
+- [Next.js App Router](https://nextjs.org/docs/app) with Webpack v5 (Turbopack is not supported yet)
 
 ## Installation
 
@@ -102,7 +104,7 @@ Finally, import the stylesheet at the top of the layout file.
  import type { Metadata } from 'next';
  import { Inter } from 'next/font/google';
 
-+ import '@mui/material-pigment-css/styles.css';
++import '@mui/material-pigment-css/styles.css';
 
  export default function RootLayout(props) {
    return (
@@ -155,7 +157,7 @@ Finally, add the Pigment CSS stylesheet to the top of the main file.
 
 ```diff title="src/main.(js|tsx)"
  import * as React from 'react';
-+ import '@mui/material-pigment-css/styles.css';
++import '@mui/material-pigment-css/styles.css';
  import App from './App';
 
  ReactDOM.createRoot(document.getElementById('root')).render(
@@ -171,11 +173,11 @@ Integrating Pigment CSS with Material UI requires you to configure the theme t
 Add the following code to your [Next.js](#nextjs) or [Vite](#vite) config file:
 
 ```diff
-+ import { extendTheme, stringifyTheme } from '@mui/material';
++import { extendTheme, stringifyTheme } from '@mui/material';
 
-+ const pigmentConfig = {
-+   theme: extendTheme(),
-+ };
++const pigmentConfig = {
++  theme: extendTheme(),
++};
 ```
 
 If you don't have a custom theme, you are ready to go. Start a development server by running:
@@ -211,6 +213,7 @@ import Card from '@mui/material/Card';
 
 function App() {
   const [color, setColor] = useState('#000000');
+
   return (
     <Card
       sx={{
@@ -434,8 +437,8 @@ With Pigment CSS, any JSX element can accept the `sx` prop so it is **no** long
 If you have custom components that are using `styled` from `@mui/material/styles`, change the import source to `@mui/material-pigment-css`:
 
 ```diff
-- import { styled } from '@mui/material/styles';
-+ import { styled } from '@mui/material-pigment-css';
+-import { styled } from '@mui/material/styles';
++import { styled } from '@mui/material-pigment-css';
 ```
 
 Then, run the following codemod:
@@ -506,17 +509,17 @@ export default FlashCode;
 To use layout components that are compatible with Pigment CSS, replace the following components with those from the adapter package:
 
 ```diff
-- import Container from '@mui/material/Container';
-+ import Container from '@mui/material-pigment-css/Container';
+-import Container from '@mui/material/Container';
++import Container from '@mui/material-pigment-css/Container';
 
-- import Grid from '@mui/material/Grid';
-+ import Grid from '@mui/material-pigment-css/Grid';
+-import Grid from '@mui/material/Grid';
++import Grid from '@mui/material-pigment-css/Grid';
 
-- import Stack from '@mui/material/Stack';
-+ import Stack from '@mui/material-pigment-css/Stack';
+-import Stack from '@mui/material/Stack';
++import Stack from '@mui/material-pigment-css/Stack';
 
-- import Hidden from '@mui/material/Hidden';
-+ import Hidden from '@mui/material-pigment-css/Hidden';
+-import Hidden from '@mui/material/Hidden';
++import Hidden from '@mui/material-pigment-css/Hidden';
 ```
 
 :::info
@@ -533,16 +536,16 @@ Choose one of the following approaches:
 Replace the `Box` component with the one from the adapter package:
 
 ```diff
-- import Box from '@mui/material/Box';
-+ import Box from '@mui/material-pigment-css/Box';
+-import Box from '@mui/material/Box';
++import Box from '@mui/material-pigment-css/Box';
 ```
 
 ### Use HTML element
 
 Pigment CSS can extract the `sx` prop from any JSX element, so there is no need to use the Box component.
 
 ```diff
-- import Box from '@mui/material/Box';
+-import Box from '@mui/material/Box';
 
  function CustomCard() {
    return (
@@ -554,7 +557,7 @@ Pigment CSS can extract the `sx` prop from any JSX element, so there is no need
 +      <img src="..." style={{ width: 24, height: 24 }}>
 +      ...
 +    </div>
-   )
+   );
  }
 ```
 
@@ -577,8 +580,8 @@ declare global {
 If you are using the `useTheme` hook, replace the import source:
 
 ```diff
-- import { useTheme } from '@mui/material/styles';
-+ import { useTheme } from '@mui/material-pigment-css';
+-import { useTheme } from '@mui/material/styles';
++import { useTheme } from '@mui/material-pigment-css';
 ```
 
 :::info

docs/data/material/migration/migrating-to-v6/migrating-to-v6.md

@@ -51,7 +51,7 @@ The exact versions will be pinned on release from the browserslist query: `"> 0.
 - Edge 121 (up from 91)
 - Firefox 115 (up from 78)
 - Safari 15.4 in both macOS and iOS (up from 14 in macOS and 12.5 in iOS)
-- and more (see [.browserslistrc (`stable` entry)](https://github.com/mui/material-ui/blob/v6.0.0/.browserslistrc#L11))
+- and more (see [.browserslistrc `stable` entry](https://github.com/mui/material-ui/blob/v6.0.0/.browserslistrc#L11))
 
 ### Removed support for IE 11
 
@@ -115,6 +115,7 @@ Expect updates as new breaking changes are introduced.
 
 To align with React 19's removal of UMD builds, Material UI has also removed its UMD bundle.
 This results in a reduction of the `@mui/material` package size by 2.5MB or 25% of the total package size.
+See [Package Phobia](https://packagephobia.com/result?p=@mui/material) for more details.
 
 Instead, using ESM-based CDNs such as [esm.sh](https://esm.sh/) is recommended.
 For alternative installation methods, refer to the [CDN documentation](/material-ui/getting-started/installation/#cdn).
@@ -185,28 +186,28 @@ For the default theme this was:
 In v6, these props are renamed to `size` and `offset`:
 
 ```diff
-  <Grid
--   xs={12}
--   sm={6}
--   xsOffset={2}
--   smOffset={3}
-+   size={{ xs: 12, sm: 6 }}
-+   offset={{ xs: 2, sm: 3 }}
-  />
+ <Grid
+-  xs={12}
+-  sm={6}
+-  xsOffset={2}
+-  smOffset={3}
++  size={{ xs: 12, sm: 6 }}
++  offset={{ xs: 2, sm: 3 }}
+ >
 ```
 
 Note that if the size or offset is the same for all breakpoints, you can use a single value:
 
 ```diff
-- <Grid xs={6} xsOffset={2} >
-+ <Grid size={6} offset={2} >
+-<Grid xs={6} xsOffset={2}>
++<Grid size={6} offset={2}>
 ```
 
 Besides that, the `true` value for the size prop was renamed to `"grow"`:
 
 ```diff
-- <Grid xs />
-+ <Grid size="grow" />
+-<Grid xs>
++<Grid size="grow">
 ```
 
 Use this codemod to migrate your project to the new size and offset props:
@@ -218,8 +219,8 @@ npx @mui/codemod@next v6.0.0/grid-v2-props <path/to/folder>
 If you have custom breakpoints, the change is the same:
 
 ```diff
-- <Grid mobile={12} mobileOffset={2} desktop={6} desktopOffset={4} >
-+ <Grid size={{ mobile: 12, desktop: 6 }} offset={{ mobile: 2, desktop: 4 }} >
+-<Grid mobile={12} mobileOffset={2} desktop={6} desktopOffset={4}>
++<Grid size={{ mobile: 12, desktop: 6 }} offset={{ mobile: 2, desktop: 4 }}>
 ```
 
 Which you can cover with the same codemod by providing the custom breakpoints as an argument:
@@ -238,8 +239,8 @@ In v6, this is fixed, with the Grid being contained inside its parent's padding:
 This removes the need for the `disableEqualOverflow` prop:
 
 ```diff
-- <Grid disableEqualOverflow />
-+ <Grid />
+-<Grid disableEqualOverflow>
++<Grid>
 ```
 
 #### Spacing is no longer considered inside the Grid item's box
@@ -271,8 +272,8 @@ The `CssVarsProvider` and `extendTheme` APIs are now stable.
 If you already use them in v5, you can now drop the experimental prefix.
 
 ```diff
-- import { experimental_extendTheme as extendTheme, Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
-+ import { extendTheme, CssVarsProvider } from '@mui/material/styles';
+-import { experimental_extendTheme as extendTheme, Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
++import { extendTheme, CssVarsProvider } from '@mui/material/styles';
 ```
 
 Check out the [CSS theme variables page](/material-ui/customization/css-theme-variables/overview/) to learn more about it.
@@ -326,8 +327,8 @@ npx @mui/codemod@next v6.0.0/system-props <path/to/folder>
 Or do it manually like the example below:
 
 ```diff
-- <Button mr={2}>...</Button>
-+ <Button sx={{ mr: 2 }}>...</Button>
+-<Button mr={2}>
++<Button sx={{ mr: 2 }}>
 ```
 
 ### Theme component variants