From ecc4e417e4d7a8be4ea39e80f75741dd37db57ff Mon Sep 17 00:00:00 2001
From: Philipp Hugenroth <philipph@spotify.com>
Date: Tue, 13 Jun 2023 13:04:40 +0200
Subject: [PATCH] Improve English & add additional information from feedback

Signed-off-by: Philipp Hugenroth <philipph@spotify.com>
---
 docs/getting-started/app-custom-theme.md | 26 ++++++++++++++----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md
index dff7754852..bbbb878942 100644
--- a/docs/getting-started/app-custom-theme.md
+++ b/docs/getting-started/app-custom-theme.md
@@ -487,25 +487,29 @@ homepage of your app. Read the full guide on the [next page](homepage.md).
 
 ## Migrating to Material UI v5
 
-For supporting Material UI v5 in addition to v4 we introduced a `UnifiedThemeProvider` allowing a step-by-step migration. To use it you have to update your App's `ThemeProvider` in `app/src/App.tsx` like the following:
+To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeProvider`. This allows a step-by-step migration. To use it, you need to update your app's `ThemeProvider` in `app/src/App.tsx` as follows
 
 ```diff
-     Provider: ({ children }) => (
--    <ThemeProvider theme={lightTheme}>
--      <CssBaseline>{children}</CssBaseline>
--    </ThemeProvider>
-+    <UnifiedThemeProvider theme={builtinThemes.light} children={children} />
+     provider: ({ children }) => (
+- <ThemeProvider theme={lightTheme}>.
+- <CssBaseline>{children}</CssBaseline>.
+- </ThemeProvider
++ <UnifiedThemeProvider theme={builtinThemes.light} children={children} />
      ),
 ```
 
-When you are looking for migrating code from v4 to v5 the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) might be a helpful resource. It is worth mentioning that we are still using `@mui/styles` & thereby `jss`. You might stumble accross the migration to `emotion` for `makeStyles` or `withStyles`. It is not required to move to `emotion` yet.
+In addition, the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) is a helpful resource that breaks down the differences between v4 & v5. It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion` yet.
+
+To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)).
+
+For current knonw issues with the MUI v5 migration follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems.
 
 ### Plugins
 
-To migrate your plugin to MUI v5 you can build up on the resources available.
+To migrate your plugin to MUI v5, you can build on the resources available.
 
-1. Run the migration `codemod` for the path of the specific plug: `npx @mui/codemod v5.0.0/preset-safe <path>`
-2. Manual fix imports to align with linting rules & take a look at potential `TODO:` items the `codemod` could not fix.
-3. Remove types & methods from `@backstage/theme`, which are marked as `@deprecated`
+1. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe <path>`.
+2. Manually fix the imports to match the new [linting rules](https://mui.com/material-ui/guides/minimizing-bundle-size). Take a look at possible `TODO:` items the `codemod` could not fix.
+3. Removal of types & methods from `@backstage/theme` which are marked as `@deprecated`.
 
 You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration.