[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"
+      // the props below are specific to this demo, you might not need them in your app.
+      colorSchemeSelector="#demo_dark-mode-by-default" // the selector to apply CSS theme variables stylesheet.
+      modeStorageKey="demo_dark-mode-by-default" // the local storage key to use
+    >
+      <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"
+      // the props below are specific to this demo, you might not need them in your app.
+      colorSchemeSelector="#demo_dark-mode-by-default" // the selector to apply CSS theme variables stylesheet.
+      modeStorageKey="demo_dark-mode-by-default" // the local storage key to use
+    >
+      <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"
+      // The props below are specific to this demo, you might not need them in your app.
+      modeStorageKey="demo_identify-system-mode" // the local storage key to use.
+    >
+      <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"
+      // The props below are specific to this demo, you might not need them in your app.
+      modeStorageKey="demo_identify-system-mode" // the local storage key to use.
+    >
+      <Identifier />
+    </CssVarsProvider>
+  );
+}

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

@@ -0,0 +1,7 @@
+<CssVarsProvider
+  defaultMode="system"
+  // The props below are specific to this demo, you might not need them in your app.
+  modeStorageKey="demo_identify-system-mode" // the local storage key to use.
+>
+  <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(() => {
@@ -37,10 +37,10 @@ export default function BootstrapVariantTokens() {
 
   return (
     <CssVarsProvider
-      colorSchemeNode={node || null}
-      modeStorageKey="mode-toggle-demo"
-      colorSchemeStorageKey="mode-toggle-demo"
-      colorSchemeSelector="#mode-toggle"
+      // the props below are specific to this demo, you might not need them in your app.
+      colorSchemeNode={node || null} // the element to apply [data-joy-color-scheme] attribute.
+      colorSchemeSelector="#mode-toggle" // the selector to apply the CSS theme variables stylesheet.
+      modeStorageKey="mode-toggle-demo" // the local storage key to use.
     >
       <Box
         id="mode-toggle"
@@ -53,7 +53,7 @@ export default function BootstrapVariantTokens() {
           bgcolor: 'background.body',
         }}
       >
-        <ModeToggle />
+        <ModeSwitcher />
       </Box>
     </CssVarsProvider>
   );

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

@@ -0,0 +1,60 @@
+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
+      // the props below are specific to this demo, you might not need them in your app.
+      colorSchemeNode={node || null} // the element to apply [data-joy-color-scheme] attribute.
+      colorSchemeSelector="#mode-toggle" // the selector to apply the CSS theme variables stylesheet.
+      modeStorageKey="mode-toggle-demo" // the local storage key to use.
+    >
+      <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 applying dark mode to a Joy UI app.</p>
 
-## The mode-toggle component
+## Set as default
+
+To set dark mode as the default for your app, add `defaultMode: 'dark'` to your `<CssVarsProvider>` wrapper component:
+
+{{"demo": "DarkModeByDefault.js"}}
+
+For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `getInitColorSchemeScript` function:
+
+```js
+getInitColorSchemeScript({ defaultMode: 'dark' });
+```
+
+## Matching device's preference
+
+Use `defaultMode: 'system'` to set your app's default mode to match the user's chosen preference on their device.
+
+```jsx
+import { CssVarsProvider } from '@mui/joy/styles';
+
+<CssVarsProvider defaultMode="system">...</CssVarsProvider>;
+```
+
+For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `getInitColorSchemeScript` function:
+
+```js
+getInitColorSchemeScript({ defaultMode: 'system' });
+```
+
+### Identify the system mode
+
+Use the `useColorScheme` React hook to check if the user's preference is in light or dark mode:
+
+```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
+The `useColorScheme()` hook only works with components nested inside of `<CssVarsProvider>`—otherwise it will throw an error.
+:::
+
+## Creating a mode-toggle component
+
+You can create a toggle component to give users the option to select between modes.
 
 In the example below, we're using a `Button` component that calls `setMode` from the `useColorSchemes()` hook to handle the mode toggling.
 
@@ -27,10 +77,10 @@ function ModeToggle() {
 {{"demo": "ModeToggle.js"}}
 
 :::warning
-**Note:** Make sure to use `useColorScheme()` in a component that's inside `<CssVarsProvider>`, otherwise it will throw an error.
+The `useColorScheme()` hook only works with components nested inside of `<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.