[docs] Update Appearance API docs, add Mermaid diagram support#5060
Merged
Conversation
|
@huntie is attempting to deploy a commit to the Meta Open Source Team on Vercel. A member of the Team first needs to authorize it. |
huntie
commented
Apr 26, 2026
| - `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). |
Member
Author
There was a problem hiding this comment.
This is actually the motivation for this change — discovered mismatched manual TS types in React Native vs the source code. Intend to remove 'unspecified' entirely in the near future.
✅ Deploy Preview for react-native ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Simek
reviewed
Apr 27, 2026
Comment on lines
+619
to
+624
| mermaid: { | ||
| theme: { | ||
| light: 'neutral', | ||
| dark: 'dark', | ||
| }, | ||
| }, |
Collaborator
There was a problem hiding this comment.
Let's use the default website font family ("Optimistic Display",system-ui,-apple-system,sans-serif) for the Mermaid diagrams:
Collaborator
|
Looks good, thanks for updates and adding a Mermaid setup! 👍 Besides the comment above I have one more appearance request - can we center the diagram on the page? It looks like we can add |
huntie
force-pushed
the
appearance-docs-update
branch
from
d33e33e to
bc6469d
Compare
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.
huntie
force-pushed
the
appearance-docs-update
branch
from
bc6469d to
cd8b326
Compare
Member
Author
|
Latest push:
|
Simek
approved these changes
May 3, 2026
Simek
left a comment
Simek
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for the updates, LGTM! 👍
huntie
added a commit
to huntie/react-native
that referenced
this pull request
May 5, 2026
…6686) Summary: Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise. **Motivation** `'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value. After this change: - `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`) - `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'` Paired with docs updates: - react/react-native-website#5060 - react/react-native-website#5069 **History of this API** - The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652). - When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers. - D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant. Changelog: [General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change) Differential Revision: D102527387
huntie
added a commit
to huntie/react-native
that referenced
this pull request
May 6, 2026
Summary:
Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise.
**Motivation**
`'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value.
After this change:
- `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`)
- `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'`
Paired with docs updates:
- react/react-native-website#5060
- react/react-native-website#5069
**History of this API**
- The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652).
- When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers.
- D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant.
Changelog:
[General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change)
Differential Revision: D102527387
huntie
added a commit
to huntie/react-native
that referenced
this pull request
May 6, 2026
Summary:
Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise.
**Motivation**
`'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value.
After this change:
- `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`)
- `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'`
Paired with docs updates:
- react/react-native-website#5060
- react/react-native-website#5069
**History of this API**
- The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652).
- When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers.
- D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant.
Changelog:
[General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change)
Reviewed By: cipolleschi
Differential Revision: D102527387
huntie
added a commit
to huntie/react-native
that referenced
this pull request
May 6, 2026
Summary:
Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise.
**Motivation**
`'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value.
After this change:
- `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`)
- `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'`
Paired with docs updates:
- react/react-native-website#5060
- react/react-native-website#5069
**History of this API**
- The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652).
- When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers.
- D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant.
Changelog:
[General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change)
Reviewed By: cipolleschi
Differential Revision: D102527387
meta-codesync Bot
pushed a commit
to react/react-native
that referenced
this pull request
May 7, 2026
Summary: Pull Request resolved: #56686 Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise. **Motivation** `'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value. After this change: - `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`) - `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'` Paired with docs updates: - react/react-native-website#5060 - react/react-native-website#5069 **History of this API** - The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652). - When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers. - D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant. Changelog: [General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change) Reviewed By: cipolleschi Differential Revision: D102527387 fbshipit-source-id: 3fc19add59450cb07b9d0a962c63c4fa208faa63
meta-codesync Bot
pushed a commit
to react/react-native
that referenced
this pull request
May 7, 2026
Summary: NOTE: 👋🏻 **This is an RFC**, additional and separate to the previous 2 diffs. Looking for feedback :) Proposes an API tweak to `Appearance.setColorScheme()` to make it more idiomatic/understandable. - Aligns with the CSS `color-scheme` property vocabulary, where `auto` means "defer to the system preference". - Replaces the ambiguous `unspecified` (now deprecated), which gave no indication of the resulting behaviour. See also: - History of this API + return type narrowing in D102527387. - Extended docs + diagram in react/react-native-website#5060. **Alternative names considered** - `'reset'` - Implies reversing a change, not deferring to system - `'inherit'` - Weak — CSS inherit is element→parent, not app→OS Changelog: [General][Deprecated] - `Appearance.setColorScheme('unspecified')` is deprecated, use `'auto'` instead. Reviewed By: cipolleschi Differential Revision: D103841988 fbshipit-source-id: 474d0925ce9ee0ab79f87d0ff9ae86ae56ceb0aa
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Update the
AppearanceanduseColorSchemeAPI 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 thesetColorSchemeoverride behaviour.