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

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

@@ -0,0 +1,41 @@
+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';
+
+const useEnhancedEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
+
+export default function ButtonThemes() {
+  // the `node` is used for attaching CSS variables to this demo, you might not need it in your app.
+  const [node, setNode] = React.useState(null);
+  useEnhancedEffect(() => {
+    setNode(document.getElementById('dark-mode-by-default'));
+  }, []);
+
+  return (
+    <CssVarsProvider
+      defaultMode="dark"
+      // these props are specific to this demo, you might not need them in your app.
+      colorSchemeNode={node || null}
+      colorSchemeSelector="#dark-mode-by-default"
+      modeStorageKey="dark-mode-by-default"
+      colorSchemeStorageKey="dark-mode-by-default"
+    >
+      <Sheet id="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/guides/applying-dark-mode/applying-dark-mode.md → docs/data/joy/customization/dark-mode/dark-mode.md

@@ -1,6 +1,18 @@
-# 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 dark mode in Joy UI</p>
+
+## Dark mode by default
+
+To have dark mode as a default for your app, set `defaultMode: 'dark'`.
+
+{{"demo": "DarkModeByDefault.js"}}
+
+For server-side applications, check out the framework setup in the [guide](#server-side-rendering) below and provide the same value to the `getInitColorSchemeScript` function.
+
+```js
+getInitColorSchemeScript({ defaultMode: 'dark' });
+```
 
 ## The mode-toggle component
 
@@ -105,3 +117,38 @@ export function onRenderBody({ setPreBodyComponents }) {
   setPreBodyComponents([getInitColorSchemeScript()]);
 }
 ```
+
+## System preference
+
+To have the color mode based on the user's preference, set `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 actual 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() {
+  // Calculated from the prefers-color-scheme media query (https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).
+  const { mode, systemMode } = useColorScheme();
+  console.log(mode); // "system"
+  console.log(systemMode); // "light" | "dark" based on the user's preference.
+}
+```
+
+:::warning
+**Note:** Make sure to use `useColorScheme()` in a component that's inside `<CssVarsProvider>`, otherwise it will throw an error.
+:::

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

@@ -89,6 +89,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' },
@@ -100,7 +101,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} />;

docs/public/_redirects

@@ -389,7 +389,7 @@ https://v4.material-ui.com/* https://v4.mui.com/:splat 301!
 /base/api/trap-focus/ /base/api/focus-trap/ 301
 /material-ui/experimental-api/css-variables/ /material-ui/experimental-api/css-theme-variables/overview/ 301
 /joy-ui/main-features/perfect-dark-mode/ /joy-ui/main-features/dark-mode-optimization/ 301
-
+/joy-ui/guides/applying-dark-mode/ /joy-ui/customization/dark-mode/ 301
 # 2023
 
 # Proxies