[docs] Add a guide for setting dark mode by default

docs/data/joy/customization/dark-mode/DarkModeByDefault.js

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { CssVarsProvider } from '@mui/joy/styles';
+import Sheet from '@mui/joy/Sheet';
+import Chip from '@mui/joy/Chip';
+import Typography from '@mui/joy/Typography';
+
+export default function DarkModeByDefault() {
+  return (
+    <CssVarsProvider
+      defaultMode="dark"
+      // these props are specific to this demo, you might not need them in your app.
+      colorSchemeSelector="#demo_dark-mode-by-default"
+      modeStorageKey="demo_dark-mode-by-default"
+    >
+      <Sheet
+        id="demo_dark-mode-by-default"
+        sx={{ px: 3, py: 1.5, borderRadius: 'sm' }}
+      >
+        <Typography
+          component="div"
+          endDecorator={
+            <Chip variant="outlined" color="primary" size="sm">
+              Default
+            </Chip>
+          }
+          fontSize="lg"
+        >
+          Dark mode
+        </Typography>
+      </Sheet>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/DarkModeByDefault.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { CssVarsProvider } from '@mui/joy/styles';
+import Sheet from '@mui/joy/Sheet';
+import Chip from '@mui/joy/Chip';
+import Typography from '@mui/joy/Typography';
+
+export default function DarkModeByDefault() {
+  return (
+    <CssVarsProvider
+      defaultMode="dark"
+      // these props are specific to this demo, you might not need them in your app.
+      colorSchemeSelector="#demo_dark-mode-by-default"
+      modeStorageKey="demo_dark-mode-by-default"
+    >
+      <Sheet
+        id="demo_dark-mode-by-default"
+        sx={{ px: 3, py: 1.5, borderRadius: 'sm' }}
+      >
+        <Typography
+          component="div"
+          endDecorator={
+            <Chip variant="outlined" color="primary" size="sm">
+              Default
+            </Chip>
+          }
+          fontSize="lg"
+        >
+          Dark mode
+        </Typography>
+      </Sheet>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/IdentifySystemMode.js

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';
+import Typography from '@mui/joy/Typography';
+
+const Identifier = () => {
+  const { systemMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  if (!mounted) {
+    return (
+      <Typography component="div" fontSize="lg" sx={{ opacity: 0 }}>
+        Calculating…
+      </Typography>
+    );
+  }
+  return (
+    <Typography component="div" fontSize="lg">
+      Your system is in{' '}
+      <Typography
+        variant="outlined"
+        fontSize="md"
+        sx={{
+          boxShadow: 'sm',
+          py: 0.25,
+          fontFamily: 'code',
+          bgcolor: 'background.level1',
+        }}
+      >
+        {systemMode}
+      </Typography>{' '}
+      mode.
+    </Typography>
+  );
+};
+
+export default function IdentifySystemMode() {
+  return (
+    <CssVarsProvider
+      defaultMode="system"
+      // these props are specific to this demo, you might not need them in your app.
+      modeStorageKey="demo_identify-system-mode"
+    >
+      <Identifier />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/IdentifySystemMode.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';
+import Typography from '@mui/joy/Typography';
+
+const Identifier = () => {
+  const { systemMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  if (!mounted) {
+    return (
+      <Typography component="div" fontSize="lg" sx={{ opacity: 0 }}>
+        Calculating…
+      </Typography>
+    );
+  }
+  return (
+    <Typography component="div" fontSize="lg">
+      Your system is in{' '}
+      <Typography
+        variant="outlined"
+        fontSize="md"
+        sx={{
+          boxShadow: 'sm',
+          py: 0.25,
+          fontFamily: 'code',
+          bgcolor: 'background.level1',
+        }}
+      >
+        {systemMode}
+      </Typography>{' '}
+      mode.
+    </Typography>
+  );
+};
+
+export default function IdentifySystemMode() {
+  return (
+    <CssVarsProvider
+      defaultMode="system"
+      // these props are specific to this demo, you might not need them in your app.
+      modeStorageKey="demo_identify-system-mode"
+    >
+      <Identifier />
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/dark-mode/IdentifySystemMode.tsx.preview

@@ -0,0 +1,7 @@
+<CssVarsProvider
+  defaultMode="system"
+  // these props are specific to this demo, you might not need them in your app.
+  modeStorageKey="demo_identify-system-mode"
+>
+  <Identifier />
+</CssVarsProvider>

docs/data/joy/guides/applying-dark-mode/ModeToggle.js → docs/data/joy/customization/dark-mode/ModeToggle.js

@@ -6,7 +6,7 @@ import Button from '@mui/joy/Button';
 const useEnhancedEffect =
   typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
 
-function ModeToggle() {
+function ModeSwitcher() {
   const { mode, setMode } = useColorScheme();
   const [mounted, setMounted] = React.useState(false);
 
@@ -28,7 +28,7 @@ function ModeToggle() {
   );
 }
 
-export default function BootstrapVariantTokens() {
+export default function ModeToggle() {
   // the `node` is used for attaching CSS variables to this demo, you might not need it in your application.
   const [node, setNode] = React.useState(null);
   useEnhancedEffect(() => {
@@ -38,9 +38,8 @@ export default function BootstrapVariantTokens() {
   return (
     <CssVarsProvider
       colorSchemeNode={node || null}
-      modeStorageKey="mode-toggle-demo"
-      colorSchemeStorageKey="mode-toggle-demo"
       colorSchemeSelector="#mode-toggle"
+      modeStorageKey="mode-toggle-demo"
     >
       <Box
         id="mode-toggle"
@@ -53,7 +52,7 @@ export default function BootstrapVariantTokens() {
           bgcolor: 'background.body',
         }}
       >
-        <ModeToggle />
+        <ModeSwitcher />
       </Box>
     </CssVarsProvider>
   );

docs/data/joy/customization/dark-mode/ModeToggle.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';
+import Box from '@mui/joy/Box';
+import Button from '@mui/joy/Button';
+
+const useEnhancedEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
+
+function ModeSwitcher() {
+  const { mode, setMode } = useColorScheme();
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return null;
+  }
+  return (
+    <Button
+      variant="outlined"
+      color="neutral"
+      onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}
+    >
+      {mode === 'dark' ? 'Turn light' : 'Turn dark'}
+    </Button>
+  );
+}
+
+export default function ModeToggle() {
+  // the `node` is used for attaching CSS variables to this demo, you might not need it in your application.
+  const [node, setNode] = React.useState<HTMLElement | null>(null);
+  useEnhancedEffect(() => {
+    setNode(document.getElementById('mode-toggle'));
+  }, []);
+
+  return (
+    <CssVarsProvider
+      colorSchemeNode={node || null}
+      colorSchemeSelector="#mode-toggle"
+      modeStorageKey="mode-toggle-demo"
+    >
+      <Box
+        id="mode-toggle"
+        sx={{
+          textAlign: 'center',
+          flexGrow: 1,
+          p: 2,
+          m: -3,
+          borderRadius: 'sm',
+          bgcolor: 'background.body',
+        }}
+      >
+        <ModeSwitcher />
+      </Box>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/guides/applying-dark-mode/applying-dark-mode.md → docs/data/joy/customization/dark-mode/dark-mode.md

@@ -1,8 +1,58 @@
-# Applying dark mode
+# Dark mode
 
-<p class="description">A how-to-guide for applying dark mode to your application with Joy UI.</p>
+<p class="description">Learn about the different methods for having dark mode with Joy UI.</p>
 
-## The mode-toggle component
+## Set as default
+
+To have your app using dark mode as its default mode, add `defaultMode: 'dark'` into your `<CssVarsProvider>` wrapper component.
+
+{{"demo": "DarkModeByDefault.js"}}
+
+For server-side applications, check out the framework setup in the [guide](#server-side-rendering) below and use the same value to the `getInitColorSchemeScript` function.
+
+```js
+getInitColorSchemeScript({ defaultMode: 'dark' });
+```
+
+## Matching device's mode preference
+
+To have your app matching the prefferred mode the user has set on their devide, use `defaultMode: 'system'`.
+
+```jsx
+import { CssVarsProvider } from '@mui/joy/styles';
+
+<CssVarsProvider defaultMode="system">...</CssVarsProvider>;
+```
+
+For server-side applications, check out the framework setup in the [guide](#server-side-rendering) above and provide the same value to the `getInitColorSchemeScript` function.
+
+```js
+getInitColorSchemeScript({ defaultMode: 'system' });
+```
+
+### Identify the system mode
+
+To check if the user's preference is in light or dark mode, use the `useColorScheme` React hook:
+
+```js
+import { useColorScheme } from '@mui/joy/styles';
+
+function SomeComponent() {
+  const { mode, systemMode } = useColorScheme();
+  console.log(mode); // "system"
+  console.log(systemMode); // "light" | "dark" based on the user's preference.
+}
+```
+
+{{"demo": "IdentifySystemMode.js"}}
+
+:::warning
+**Note:** Make sure to use `useColorScheme()` in a component that's inside `<CssVarsProvider>`, otherwise it will throw an error.
+:::
+
+## Creating a mode-toggle component
+
+To allow your user to toggle freely between modes, let's create a mode-toggle button component.
 
 In the example below, we're using a `Button` component that calls `setMode` from the `useColorSchemes()` hook to handle the mode toggling.
 
@@ -30,7 +80,7 @@ function ModeToggle() {
 **Note:** Make sure to use `useColorScheme()` in a component that's inside `<CssVarsProvider>`, otherwise it will throw an error.
 :::
 
-## Server-side rendering
+## Server-side rendering notes
 
 ### Avoid hydration mismatch
 

docs/data/joy/getting-started/tutorial/tutorial.md

@@ -244,7 +244,7 @@ Here are some of the major features introduced:
 
 - [global variants](/joy-ui/main-features/global-variants/)
 - [the `sx` prop](/system/getting-started/the-sx-prop/)
-- [dark mode](/joy-ui/guides/applying-dark-mode/)
+- [dark mode](/joy-ui/customization/dark-mode/)
 
 ## Next steps
 

docs/data/joy/main-features/dark-mode-optimization/dark-mode-optimization.md

@@ -30,7 +30,7 @@ Thanks to Joy UI's built-in support for CSS variables, your app can render all o
 Joy UI provides the `getInitColorSchemeScript()` function to make this flash-free dark mode possible with React frameworks like Next.js, Gatsby, and Remix.
 This function must be placed before the main script so it can apply the correct stylesheet before your components are rendered.
 
-The code snippet below shows how this works with Next.js—see the [Applying dark mode](/joy-ui/guides/applying-dark-mode/) page for more details on usage with other frameworks:
+The code snippet below shows how this works with Next.js—see the [Applying dark mode](/joy-ui/customization/dark-mode/) page for more details on usage with other frameworks:
 
 ```jsx
 import Document, { Html, Head, Main, NextScript } from 'next/document';

docs/data/joy/main-features/dark-mode-optimization/perfect-dark-mode-pt.md

@@ -39,5 +39,5 @@ export default class MyDocument extends Document {
 }
 ```
 
-- Learn [how to apply dark mode](/joy-ui/guides/applying-dark-mode/) in various frameworks by visiting the How To Guides.
+- Learn [how to apply dark mode](/joy-ui/customization/dark-mode/) in various frameworks by visiting the How To Guides.
 - Check out our [RFC on CSS variables support](https://github.com/mui/material-ui/issues/27651) to get the full picture of its implementation in Joy UI.

docs/data/joy/main-features/dark-mode-optimization/perfect-dark-mode-zh.md

@@ -39,5 +39,5 @@ export default class MyDocument extends Document {
 }
 ```
 
-- Learn [how to apply dark mode](/joy-ui/guides/applying-dark-mode/) in various frameworks by visiting the How To Guides.
+- Learn [how to apply dark mode](/joy-ui/customization/dark-mode/) in various frameworks by visiting the How To Guides.
 - Check out our [RFC on CSS variables support](https://github.com/mui/material-ui/issues/27651) to get the full picture of its implementation in Joy UI.

docs/data/joy/pages.ts

@@ -90,6 +90,7 @@ const pages = [
     icon: 'CreateIcon',
     children: [
       { pathname: '/joy-ui/customization/approaches' },
+      { pathname: '/joy-ui/customization/dark-mode' },
       { pathname: '/joy-ui/customization/default-theme' },
       { pathname: '/joy-ui/customization/theme-tokens' },
       { pathname: '/joy-ui/customization/themed-components' },
@@ -101,7 +102,6 @@ const pages = [
     title: 'How To Guides',
     icon: 'VisibilityIcon',
     children: [
-      { pathname: '/joy-ui/guides/applying-dark-mode', title: 'Applying dark mode' },
       {
         pathname: '/joy-ui/guides/using-joy-ui-and-material-ui-together',
         title: 'Joy UI and Material UI together',

docs/pages/joy-ui/guides/applying-dark-mode.js → docs/pages/joy-ui/customization/dark-mode.js

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
-import * as pageProps from 'docs/data/joy/guides/applying-dark-mode/applying-dark-mode.md?@mui/markdown';
+import * as pageProps from 'docs/data/joy/customization/dark-mode/dark-mode.md?@mui/markdown';
 
 export default function Page() {
   return <MarkdownDocs {...pageProps} />;