chore(docs): add more documentation around dark mode

apps/docs/src/app/(main)/(markdown)/(demos)/customization/dark-mode/DarkElevationColors.module.scss

@@ -0,0 +1,49 @@
+@use "sass:map";
+@use "@react-md/core" with (
+  $color-scheme: dark,
+  $dark-elevation-colors: (
+    // this is really `$dark-theme-background-color`
+    0: #121212,
+    1: #1f1f1f,
+    2: #242424,
+    3: #262626,
+    4: #282828,
+    5: #282828,
+    6: #2c2c2c,
+    7: #2c2c2c,
+    8: #2f2f2f,
+    9: #2f2f2f,
+    10: #2f2f2f,
+    11: #2f2f2f,
+    12: #333,
+    13: #333,
+    14: #333,
+    15: #333,
+    16: #353535,
+    17: #353535,
+    18: #353535,
+    19: #353535,
+    20: #353535,
+    21: #353535,
+    22: #353535,
+    23: #353535,
+    24: #383838,
+  )
+);
+
+// NOTE: All the styles below are only required for this demo and should not be
+// used in your code.
+.container {
+  @include core.use-dark-theme-elevation-colors;
+}
+
+@for $i from 1 through 24 {
+  .elevation-#{$i} {
+    @include core.box-shadow($i);
+
+    // the real behavior is just to keep it empty
+    @if not map.get(core.$dark-elevation-colors, $i) {
+      @include core.set-dark-elevation-color($i, transparent);
+    }
+  }
+}

apps/docs/src/app/(main)/(markdown)/(demos)/customization/dark-mode/DarkElevationColors.tsx

@@ -0,0 +1,20 @@
+import { Box } from "@react-md/core/box/Box";
+import { cnb } from "cnbuilder";
+import { type ReactElement } from "react";
+import styles from "./DarkElevationColors.module.scss";
+
+export default function DarkElevationColors(): ReactElement {
+  return (
+    <Box grid className={styles.container}>
+      {Array.from({ length: 25 }, (_, i) => (
+        <Box
+          key={i}
+          justify="center"
+          className={cnb(i > 0 && styles[`elevation-${i}`])}
+        >
+          {i}
+        </Box>
+      ))}
+    </Box>
+  );
+}

apps/docs/src/app/(main)/(markdown)/(demos)/customization/dark-mode/DarkModeColors.tsx

@@ -0,0 +1,71 @@
+import { ColorPreview } from "@react-md/code/ColorPreview";
+import { InlineCode } from "@react-md/code/InlineCode";
+import { tableCell } from "@react-md/core/table/tableCellStyles";
+import { tableHeader } from "@react-md/core/table/tableHeaderStyles";
+import { tableRow } from "@react-md/core/table/tableRowStyles";
+import { table } from "@react-md/core/table/tableStyles";
+import { type ReactElement } from "react";
+
+interface Color {
+  name: string;
+  color: string;
+}
+
+const colors: Color[] = [
+  { color: "#121212", name: "$dark-theme-background-color" },
+  { color: "#424242", name: "$dark-theme-surface-color" },
+  { color: "#D9D9D9", name: "$dark-theme-text-primary-color" },
+  { color: "#B3B3B3", name: "$dark-theme-text-secondary-color" },
+  { color: "#808080", name: "$dark-theme-text-hint-color" },
+  { color: "#808080", name: "$dark-theme-text-disabled-color" },
+  {
+    color: "rgba(255, 255, 255, 0.1)",
+    name: "$dark-surface-hover-background-color",
+  },
+  {
+    color: "rgba(255, 255, 255, 0.12)",
+    name: "$dark-surface-focus-background-color",
+  },
+  {
+    color: "rgba(255, 255, 255, 0.24)",
+    name: "$dark-surface-press-background-color",
+  },
+  {
+    color: "rgba(255, 255, 255, 0.12)",
+    name: "$dark-surface-selected-background-color",
+  },
+  {
+    color: "rgba(255, 255, 255, 0.12)",
+    name: "$dark-surface-ripple-background-color",
+  },
+  { color: "#B3B3B3", name: "$icon-dark-theme-color" },
+];
+
+export function DarkModeColors(): ReactElement {
+  return (
+    <table className={table()}>
+      <thead className={tableHeader()}>
+        <tr className={tableRow({ disableHover: true })}>
+          <th className={tableCell({ header: true, isInTableHeader: true })}>
+            Name
+          </th>
+          <th className={tableCell({ header: true, isInTableHeader: true })}>
+            Color
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        {colors.map(({ name, color }) => (
+          <tr key={name} className={tableRow({})}>
+            <td className={tableCell()}>
+              <InlineCode>{name}</InlineCode>
+            </td>
+            <td className={tableCell()}>
+              <ColorPreview color={color} />
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

apps/docs/src/app/(main)/(markdown)/customization/dark-mode/page.mdx → apps/docs/src/app/(main)/(markdown)/(demos)/customization/dark-mode/page.mdx

@@ -1,3 +1,5 @@
+import { DarkModeColors } from "./DarkModeColors.tsx";
+
 # Dark Mode
 
 There are a few different type of light/dark themes that can be available for a
@@ -25,6 +27,40 @@ styles with the dark theme variants.
 @include core.styles;
 ```
 
+Enabling the dark mode will change all the theme colors to their dark-mode
+variants and exclude any light theme behavior from the generated CSS. The
+default theme colors are:
+
+<DarkModeColors />
+
+## Dark Elevation Colors
+
+When the dark mode is enabled, the surface background color will become lighter
+as the `z-index`/`box-shadow` increases to enable more contrast between
+temporary elements. Here is a list of components in `react-md` and their elevation:
+
+| Name                | Elevation |
+| ------------------- | --------- |
+| `AppBar`            | `2`       |
+| `Card`              | `2`       |
+| `Sheet` (inline)    | `2`       |
+| `StickyTableHeader` | `4`       |
+| `Chip`              | `8`       |
+| `Toast`             | `6`       |
+| `Menu`              | `8`       |
+| `Dialog`            | `16`      |
+| `Sheet` (normal)    | `16`      |
+
+## Configuring Elevation Colors
+
+The different elevation colors can be changed by modifying the
+`$dark-elevation-colors` map. The next demo shows all 25 elevation colors and
+allows the values to be modified to see how they behave.
+
+```demo source="./DarkElevationColors.tsx" disableBox startOnScss forceDarkMode disablePadding
+
+```
+
 # System Mode
 
 If the application should use the dark theme only if the user has set their
@@ -59,7 +95,12 @@ the other color scheme. This example will default to a `light` theme and allow
 the user to configure it to be `dark`.
 
 ```scss
-@use "@react-md/core";
+@use "@react-md/core" with (
+  // If the $color-scheme is not set or set to `light`, the dark elevation
+  // styles are omitted by default to keep the bundle smaller. So when enabling
+  // a toggleable dark mode, force the styles to be created:
+  $disable-dark-elevation: false
+);
 
 @include core.styles;
 
@@ -134,8 +175,8 @@ other color schemes.
   @include core.dark-theme;
 }
 
-.system-theme {
-  @media (prefers-color-scheme: dark) {
+@media (prefers-color-scheme: dark) {
+  .system-theme {
     @include core.dark-theme;
   }
 }