Adapt theming documentation

Author: fzaninotto

docs/Admin.md

@@ -425,7 +425,7 @@ const App = () => (
 
 ## `darkTheme`
 
-If you want to support light and dark mode, you can provide a `darkTheme` in addition to the `theme` prop. The `darkTheme` will be used when the user's browser is in dark mode, or when the user manually switches to dark mode using [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
+If you want to support both light and dark mode, you can provide a `darkTheme` in addition to the `theme` prop. The `darkTheme` will be used when the user's browser is in dark mode, or when the user manually switches to dark mode using [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
 
 ![Dark mode](./img/dark-theme.png)
 
@@ -776,16 +776,16 @@ Check the [Preferences documentation](./Store.md) for more details.
 
 ## `theme`
 
-Material UI supports [theming](https://mui.com/material-ui/customization/theming/). This lets you customize the look and feel of an admin by overriding fonts, colors, and spacing. You can provide a custom Material UI theme by using the `theme` prop:
+Material UI supports [theming](https://mui.com/material-ui/customization/theming/). This lets you customize the look and feel of an admin by overriding fonts, colors, and spacing. You can provide a custom Material UI theme by using the `theme` prop.
+
+For instance, to use a dark theme by default:
 
 ```jsx
 import { defaultTheme } from 'react-admin';
 
 const theme = {
     ...defaultTheme,
-    palette: {
-        mode: 'dark', // Switching the dark mode on is a single property value change.
-    },
+    palette: { mode: 'dark' },
 };
 
 const App = () => (
@@ -797,6 +797,8 @@ const App = () => (
 
 ![Dark theme](./img/dark-theme.png)
 
+If you want to support both a light and a dark theme, check out [the `<Admin darkTheme>` prop](#darktheme). 
+
 For more details on predefined themes and custom themes, refer to [the Theming chapter](./Theming.md#global-theme-overrides) of the react-admin documentation.
 
 ## `title`

docs/Theming.md

@@ -243,7 +243,7 @@ Note that you don't need to call `createTheme` yourself. React-admin will do it
 
 Again, to guess the name of the subclass to use (like `.RaDatagrid-headerCell` above) for customizing a component, you can use the developer tools of your browser, or check the react-admin documentation for individual components (e.g. the [Datagrid CSS documentation](./Datagrid.md#sx-css-api)).
 
-You can use this technique to override not only styles, but also default for components. That's how react-admin applies the `filled` variant to all `TextField` components. So for instance, to change the variant to `outlined`, create a custom theme as follows:
+You can use this technique to override not only styles, but also defaults for components. That's how react-admin applies the `filled` variant to all `TextField` components. So for instance, to change the variant to `outlined`, create a custom theme as follows:
 
 ```jsx
 import { defaultTheme } from 'react-admin';
@@ -367,58 +367,88 @@ const App = () => (
 
 ## Letting Users Choose The Theme
 
-The `<ToggleThemeButton>` component lets users switch from light to dark mode, and persists that choice by leveraging the [store](./Store.md).
+It's a common practice to support both a light theme and a dark theme in an application, and let users choose which one they prefer. 
+
+React-admin's `<Admin>` component accepts a `darkTheme` mode in addition to the `theme` prop. 
+
+```jsx
+import { Admin, defaultTheme } from 'react-admin';
+
+const lightTheme = defaultTheme;
+const darkTheme = { ...defaultTheme, palette: { mode: 'dark' } };
+
+const App = () => (
+    <Admin
+        dataProvider={...}
+        theme={lightTheme}
+        darkTheme={darkTheme}
+    >
+        // ...
+    </Admin>
+);
+```
+
+With this setup, the default application theme will depend on the user's system settings. If the user has chosen a dark mode in their OS, react-admin will use the dark theme. Otherwise, it will use the light theme.
+
+In addition, you can let users switch from one theme to the other: [the `<ToggleThemeButton>` component](./ToggleThemeButton.md) lets users switch from light to dark mode, and persists that choice by leveraging the [store](./Store.md).
 
 <video controls autoplay muted loop>
   <source src="./img/ToggleThemeButton.webm" type="video/webm"/>
   Your browser does not support the video tag.
 </video>
 
-
-You can add the `<ToggleThemeButton>` to a custom App Bar:
+Add the `<ToggleThemeButton>` to a custom App Bar:
 
 ```jsx
+// in src/MyLayout.jsx
 import * as React from 'react';
-import { defaultTheme, Layout, AppBar, ToggleThemeButton, TitlePortal } from 'react-admin';
-import { createTheme, Box, Typography } from '@mui/material';
-
-const darkTheme = createTheme({
-    palette: { mode: 'dark' },
-});
+import { Layout, AppBar, ToggleThemeButton, TitlePortal } from 'react-admin';
+import { Box, Typography } from '@mui/material';
 
 const MyAppBar = () => (
     <AppBar>
         <TitlePortal />
-        <ToggleThemeButton lightTheme={defaultTheme} darkTheme={darkTheme} />
+        <ToggleThemeButton />
     </AppBar>
 );
 
 const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
 ```
 
+Then, pass the custom layout to the `<Admin>` component:
+
+```jsx
+import { Admin, defaultTheme } from 'react-admin';
+
+const lightTheme = defaultTheme;
+const darkTheme = { ...defaultTheme, palette: { mode: 'dark' } };
+
+const App = () => (
+    <Admin
+        dataProvider={...}
+        theme={lightTheme}
+        darkTheme={darkTheme}
+        layout={MyLayout}
+    >
+        // ...
+    </Admin>
+);
+```
+
 ## Changing the Theme Programmatically
 
-React-admin provides the `useTheme` hook to read and update the theme programmatically. It uses the same syntax as `useState`.
-Its used internally by `ToggleThemeButton` component.
+React-admin provides the `useTheme` hook to read and update the theme programmatically. It uses the same syntax as `useState`. Its used internally by [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
 
 ```jsx
 import { defaultTheme, useTheme } from 'react-admin';
 import { Button } from '@mui/material';
 
-const lightTheme = defaultTheme;
-const darkTheme = {
-    ...defaultTheme,
-    palette: {
-        mode: 'dark',
-    },
-};
-
 const ThemeToggler = () => {
     const [theme, setTheme] = useTheme();
 
     return (
-        <Button onClick={() => setTheme(theme.palette.mode === 'dark' ? lightTheme : darkTheme)}>
-            {theme.palette.mode === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'}
+        <Button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+            {theme === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'}
         </Button>
     );
 }