[docs] Update Appearance API docs, add Mermaid diagram support

Update the `Appearance` and `useColorScheme` API reference pages with clearer descriptions, consistent terminology ("color scheme" over "user interface style"), and aligned return value docs between the two pages.

Adds `@docusaurus/theme-mermaid`, and includes a Mermaid flowchart on the Appearance page illustrating the `setColorScheme` override behaviour.

Author: huntie

docs/appearance.md

@@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import con
 import {Appearance} from 'react-native';
 ```
 
-The `Appearance` module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).
+The `Appearance` module exposes information about the user's appearance preferences, such as their preferred system color scheme (light or dark).
 
 #### Developer notes
 
@@ -53,7 +53,26 @@ if (colorScheme === 'dark') {
 }
 ```
 
-Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the [`useColorScheme`](usecolorscheme) React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a `StyleSheet`.
+Although the color scheme is available immediately, this may change when not overridden via `setColorScheme()` (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value.
+
+**Recommended:** Use the [`useColorScheme`](usecolorscheme) hook.
+
+### App-level overriding
+
+`setColorScheme()` overrides the color scheme at the application level — it does not affect the system setting or other applications. Passing `'unspecified'` removes any override, restoring the system preference.
+
+```mermaid
+flowchart TD
+    USC["useColorScheme()"] --> GCS["getColorScheme()"]
+    GCS --> DEC{App override?}
+    DEC -- "NO / reset via setColorScheme('unspecified')" --> SYS["System preference\n'light' or 'dark'"]
+    DEC -- "YES — setColorScheme('light' | 'dark')" --> OVR["'light' or 'dark' (static)"]
+
+    classDef fn fill:#dce8f8,stroke:#4a90d9,color:#1a1a1a
+    classDef out fill:#f0f4f8,stroke:#8faabb,color:#1a1a1a
+    class USC,GCS fn
+    class OVR,SYS out
+```
 
 ---
 
@@ -64,42 +83,37 @@ Although the color scheme is available immediately, this may change (e.g. schedu
 ### `getColorScheme()`
 
 ```tsx
-static getColorScheme(): 'light' | 'dark' | null;
+static getColorScheme(): 'light' | 'dark' | 'unspecified' | null;
 ```
 
-Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via `setColorScheme`) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
+Returns the active color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via `setColorScheme`) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
 
-Supported color schemes:
+Return values:
 
-- `'light'`: The user prefers a light color theme.
-- `'dark'`: The user prefers a dark color theme.
-- `null`: The user has not indicated a preferred color theme.
+- `'light'`: The light color scheme is applied.
+- `'dark'`: The dark color scheme is applied.
+- `'unspecified'`: **_Never returned_** (incorrectly typed).
+- `null`: May be returned if the native Appearance module is not available.
 
-See also: `useColorScheme` hook.
-
-:::note
-`getColorScheme()` will always return `light` when debugging with Chrome.
-:::
+See also: [`useColorScheme`](usecolorscheme) (hook).
 
 ---
 
 ### `setColorScheme()`
 
 ```tsx
-static setColorScheme('light' | 'dark' | null): void;
+static setColorScheme('light' | 'dark' | 'unspecified'): void;
 ```
 
-Force the application to always adopt a light or dark interface style. The default value is `null` which causes the application to inherit the system's interface style. If you assign a different value, the new style applies to the application and all native elements within the application (Alerts, Pickers etc).
+Forces the application to always adopt a light or dark interface style. The change applies to the application and all native elements within it (Alerts, Pickers, etc.).
 
-Supported color schemes:
+This is an app-level override — it does not affect the system's selected interface style or any style set in other applications.
 
-- `light`: Apply light user interface style.
-- `dark`: Apply dark user interface style.
-- null: Follow the system's interface style.
+Supported values:
 
-:::note
-The change will not affect the system's selected interface style or any style set in other applications.
-:::
+- `'light'`: Apply light color scheme.
+- `'dark'`: Apply dark color scheme.
+- `'unspecified'`: Follow the system color scheme (removes any override).
 
 ---
 
@@ -111,4 +125,4 @@ static addChangeListener(
 ): NativeEventSubscription;
 ```
 
-Add an event handler that is fired when appearance preferences change.
+Add an event handler that is fired when appearance preferences change. On iOS and Android, the `colorScheme` value in the callback is always `'light'` or `'dark'`.

docs/usecolorscheme.md

@@ -7,13 +7,14 @@ title: useColorScheme
 import {useColorScheme} from 'react-native';
 ```
 
-The `useColorScheme` React hook provides and subscribes to color scheme updates from the [`Appearance`](appearance) module. The return value indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
+The `useColorScheme` React hook provides and subscribes to color scheme updates from the [`Appearance`](appearance) module. The return value indicates the active color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via [`setColorScheme`](appearance#setcolorscheme)) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
 
-### Supported color schemes
+### Return values
 
-- `"light"`: The user prefers a light color theme.
-- `"dark"`: The user prefers a dark color theme.
-- `null`: The user has not indicated a preferred color theme.
+- `'light'`: The light color scheme is applied.
+- `'dark'`: The dark color scheme is applied.
+- `'unspecified'`: **_Never returned_** (incorrectly typed).
+- `null`: May be returned if the native Appearance module is not available.
 
 ---
 

website/docusaurus.config.ts

@@ -70,6 +70,10 @@ const isDeployPreview =
   (!!process.env.VERCEL && process.env.VERCEL_ENV === 'preview');
 
 const config: Config = {
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
   future: {
     // Turns Docusaurus v4 future flags on to make it easier to upgrade later
     v4: true,
@@ -613,6 +617,16 @@ const config: Config = {
       {name: 'twitter:site', content: '@reactnative'},
       {name: 'mobile-web-app-capable', content: 'yes'},
     ],
+    mermaid: {
+      theme: {
+        light: 'neutral',
+        dark: 'dark',
+      },
+      options: {
+        fontFamily:
+          '"Optimistic Display", system-ui, -apple-system, sans-serif',
+      },
+    },
   } satisfies Preset.ThemeConfig,
 };
 

website/package.json

@@ -55,6 +55,7 @@
     "@docusaurus/plugin-google-gtag": "3.10.0",
     "@docusaurus/plugin-pwa": "3.10.0",
     "@docusaurus/preset-classic": "3.10.0",
+    "@docusaurus/theme-mermaid": "3.10.0",
     "docusaurus-plugin-sass": "^0.2.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

website/src/css/customTheme.scss

@@ -511,6 +511,10 @@ hr {
     }
   }
 
+  .docusaurus-mermaid-container {
+    text-align: center;
+  }
+
   .docusaurus-highlight-code-line {
     background-color: var(--light);
   }

website/versioned_docs/version-0.85/appearance.md

@@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import con
 import {Appearance} from 'react-native';
 ```
 
-The `Appearance` module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).
+The `Appearance` module exposes information about the user's appearance preferences, such as their preferred system color scheme (light or dark).
 
 #### Developer notes
 
@@ -53,7 +53,26 @@ if (colorScheme === 'dark') {
 }
 ```
 
-Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the [`useColorScheme`](usecolorscheme) React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a `StyleSheet`.
+Although the color scheme is available immediately, this may change when not overridden via `setColorScheme()` (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value.
+
+**Recommended:** Use the [`useColorScheme`](usecolorscheme) hook.
+
+### App-level overriding
+
+`setColorScheme()` overrides the color scheme at the application level — it does not affect the system setting or other applications. Passing `'unspecified'` removes any override, restoring the system preference.
+
+```mermaid
+flowchart TD
+    USC["useColorScheme()"] --> GCS["getColorScheme()"]
+    GCS --> DEC{App override?}
+    DEC -- "NO / reset via setColorScheme('unspecified')" --> SYS["System preference\n'light' or 'dark'"]
+    DEC -- "YES — setColorScheme('light' | 'dark')" --> OVR["'light' or 'dark' (static)"]
+
+    classDef fn fill:#dce8f8,stroke:#4a90d9,color:#1a1a1a
+    classDef out fill:#f0f4f8,stroke:#8faabb,color:#1a1a1a
+    class USC,GCS fn
+    class OVR,SYS out
+```
 
 ---
 
@@ -64,42 +83,37 @@ Although the color scheme is available immediately, this may change (e.g. schedu
 ### `getColorScheme()`
 
 ```tsx
-static getColorScheme(): 'light' | 'dark' | null;
+static getColorScheme(): 'light' | 'dark' | 'unspecified' | null;
 ```
 
-Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via `setColorScheme`) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
+Returns the active color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via `setColorScheme`) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
 
-Supported color schemes:
+Return values:
 
-- `'light'`: The user prefers a light color theme.
-- `'dark'`: The user prefers a dark color theme.
-- `null`: The user has not indicated a preferred color theme.
+- `'light'`: The light color scheme is applied.
+- `'dark'`: The dark color scheme is applied.
+- `'unspecified'`: **_Never returned_** (incorrectly typed).
+- `null`: May be returned if the native Appearance module is not available.
 
-See also: `useColorScheme` hook.
-
-:::note
-`getColorScheme()` will always return `light` when debugging with Chrome.
-:::
+See also: [`useColorScheme`](usecolorscheme) (hook).
 
 ---
 
 ### `setColorScheme()`
 
 ```tsx
-static setColorScheme('light' | 'dark' | null): void;
+static setColorScheme('light' | 'dark' | 'unspecified'): void;
 ```
 
-Force the application to always adopt a light or dark interface style. The default value is `null` which causes the application to inherit the system's interface style. If you assign a different value, the new style applies to the application and all native elements within the application (Alerts, Pickers etc).
+Forces the application to always adopt a light or dark interface style. The change applies to the application and all native elements within it (Alerts, Pickers, etc.).
 
-Supported color schemes:
+This is an app-level override — it does not affect the system's selected interface style or any style set in other applications.
 
-- `light`: Apply light user interface style.
-- `dark`: Apply dark user interface style.
-- null: Follow the system's interface style.
+Supported values:
 
-:::note
-The change will not affect the system's selected interface style or any style set in other applications.
-:::
+- `'light'`: Apply light color scheme.
+- `'dark'`: Apply dark color scheme.
+- `'unspecified'`: Follow the system color scheme (removes any override).
 
 ---
 
@@ -111,4 +125,4 @@ static addChangeListener(
 ): NativeEventSubscription;
 ```
 
-Add an event handler that is fired when appearance preferences change.
+Add an event handler that is fired when appearance preferences change. On iOS and Android, the `colorScheme` value in the callback is always `'light'` or `'dark'`.

website/versioned_docs/version-0.85/usecolorscheme.md

@@ -7,13 +7,14 @@ title: useColorScheme
 import {useColorScheme} from 'react-native';
 ```
 
-The `useColorScheme` React hook provides and subscribes to color scheme updates from the [`Appearance`](appearance) module. The return value indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
+The `useColorScheme` React hook provides and subscribes to color scheme updates from the [`Appearance`](appearance) module. The return value indicates the active color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings or application-level selected user interface style via [`setColorScheme`](appearance#setcolorscheme)) or on a schedule (e.g. light and dark themes that follow the day/night cycle).
 
-### Supported color schemes
+### Return values
 
-- `"light"`: The user prefers a light color theme.
-- `"dark"`: The user prefers a dark color theme.
-- `null`: The user has not indicated a preferred color theme.
+- `'light'`: The light color scheme is applied.
+- `'dark'`: The dark color scheme is applied.
+- `'unspecified'`: **_Never returned_** (incorrectly typed).
+- `null`: May be returned if the native Appearance module is not available.
 
 ---