[AppBar] Fix background color on dark mode (#26545)

docs/pages/api-docs/app-bar.json

@@ -9,6 +9,7 @@
       },
       "default": "'primary'"
     },
+    "enableColorOnDark": { "type": { "name": "bool" } },
     "position": {
       "type": {
         "name": "enum",

docs/src/modules/components/AppFrame.js

@@ -113,8 +113,6 @@ const styles = (theme) => ({
     },
   },
   appBar: {
-    color: theme.palette.mode === 'light' ? null : '#fff',
-    backgroundColor: theme.palette.mode === 'light' ? null : theme.palette.background.level2,
     transition: theme.transitions.create('width'),
   },
   language: {

docs/src/pages/components/app-bar/app-bar.md

@@ -136,3 +136,27 @@ function HideOnScroll(props) {
   );
 }
 ```
+
+## Enable Color on Dark
+
+From v5 onward, `color` prop has no effect on dark mode according to [material design spec](https://material.io/design/color/dark-theme.html). You can opt out by passing `enableColorOnDark` prop.
+
+```jsx
+// Specific element via prop
+<AppBar enableColorOnDark />
+
+// Affect all AppBars via theme
+<ThemeProvider
+  theme={createTheme({
+    components: {
+      MuiAppBar: {
+        defaultProps: {
+          enableColorOnDark: true,
+        },
+      },
+    },
+  })}
+>
+  <AppBar />
+</ThemeProvider>
+```

docs/src/pages/guides/migration-v4/migration-v4.md

@@ -361,7 +361,12 @@ As the core components use emotion as their style engine, the props used by emot
 
 ### AppBar
 
-- [AppBar] Remove z-index when position static and relative. This avoids the creation of a stacking context and rendering issues.
+- Remove z-index when position static and relative. This avoids the creation of a stacking context and rendering issues.
+- The `color` prop has no longer any effect in dark mode. The app bar uses the background color required by the elevation to follow the [Material Design guidelines](https://material.io/design/color/dark-theme.html). Use `enableColorOnDark` to restore the behavior of v4.
+
+  ```jsx
+  <AppBar enableColorOnDark />
+  ```
 
 ### Alert
 

docs/translations/api-docs/app-bar/app-bar.json

@@ -4,6 +4,7 @@
     "children": "The content of the component.",
     "classes": "Override or extend the styles applied to the component. See <a href=\"#css\">CSS API</a> below for more details.",
     "color": "The color of the component. It supports those theme colors that make sense for this component.",
+    "enableColorOnDark": "If true, the <code>color</code> prop is applied in dark mode.",
     "position": "The positioning type. The behavior of the different options is described <a href=\"https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning\">in the MDN web docs</a>. Note: <code>sticky</code> is not universally supported and will fall back to <code>static</code> when unavailable.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/basics/#the-sx-prop\">`sx` page</a> for more details."
   },

packages/material-ui/src/AppBar/AppBar.d.ts

@@ -20,6 +20,11 @@ export interface AppBarTypeMap<P = {}, D extends React.ElementType = 'header'> {
        * @default 'primary'
        */
       color?: OverridableStringUnion<PropTypes.Color | 'transparent', AppBarPropsColorOverrides>;
+      /**
+       * If true, the `color` prop is applied in dark mode.
+       * @default false
+       */
+      enableColorOnDark?: boolean;
       /**
        * The positioning type. The behavior of the different options is described
        * [in the MDN web docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning).

packages/material-ui/src/AppBar/AppBar.js

@@ -100,17 +100,29 @@ const AppBarRoot = experimentalStyled(Paper, {
       backgroundColor: 'transparent',
       color: 'inherit',
     }),
+    ...(theme.palette.mode === 'dark' &&
+      !styleProps.enableColorOnDark && {
+        backgroundColor: null,
+        color: null,
+      }),
   };
 });
 
 const AppBar = React.forwardRef(function AppBar(inProps, ref) {
   const props = useThemeProps({ props: inProps, name: 'MuiAppBar' });
-  const { className, color = 'primary', position = 'fixed', ...other } = props;
+  const {
+    className,
+    color = 'primary',
+    enableColorOnDark = false,
+    position = 'fixed',
+    ...other
+  } = props;
 
   const styleProps = {
     ...props,
     color,
     position,
+    enableColorOnDark,
   };
 
   const classes = useUtilityClasses(styleProps);
@@ -159,6 +171,11 @@ AppBar.propTypes /* remove-proptypes */ = {
     PropTypes.oneOf(['default', 'inherit', 'primary', 'secondary', 'transparent']),
     PropTypes.string,
   ]),
+  /**
+   * If true, the `color` prop is applied in dark mode.
+   * @default false
+   */
+  enableColorOnDark: PropTypes.bool,
   /**
    * The positioning type. The behavior of the different options is described
    * [in the MDN web docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Positioning).