[YevheniiKotyrlo]

Problem

On main, colorScheme.set() moves this library's observable and nothing else:

• useColorScheme() and every store built on Appearance.addChangeListener keep the old scheme. An app calling the setter therefore renders its dark: classes on one scheme and its prop-valued colours on the other.
• The class layer reads the raw observable, which holds null after a follow-the-system request. prefers-color-scheme: light and dark then both fail while colorScheme.get() reports a scheme, and the element falls through to its unconditional rule.

Solution

• set() hands the request to Appearance.setColorScheme, which holds it on the platform, so it moves every reader the way the documented Appearance.setColorScheme does. The class layer follows the scheme Appearance reports and announces none of its own.
• Without an Appearance native module, as in a jest suite, nothing else holds a scheme, so set() keeps it here, as on main. Whether the module exists is read once at import, where Appearance.getColorScheme() answers null only without it, so a request still reaches the platform after app code hands Appearance back with null, which 0.82 and later cache as it came.
• colorScheme.get() and prefers-color-scheme resolve the value through resolveColorScheme: one that names no scheme answers light, as MQ5 §12.5 answers no preference.
• react-native-css/jest's reset, resetBetweenTests() in src/jest/reset.ts, starts each test from the scheme Appearance reports.

Tests

• color-scheme-appearance.test.tsx runs the installed React Native 0.86 Appearance over a device double that applies an override after the call returns and sends appearanceChanged only when its scheme moves, as iOS and Android do: iOS applying one turn's overrides together, Android each in turn, each with a light and a dark system scheme. It covers:
  • each request handed to Appearance, with no event of the library's own
  • the class layer and colorScheme.get() keeping the scheme in force until the platform applies a request, then every layer taking it
  • a hand-back through null and through "unspecified"
  • a request and its hand-back before the platform applies either, and requests in separate tasks
  • a request for the scheme in force, and a scheme set through Appearance itself
  • an element mounted before the platform applies a request
  • an OS change, with and without a request overriding it
  • a reported value that names no scheme
  • a request after app code hands Appearance back with null
• color-scheme-without-appearance-module.test.tsx: without a native module, set() holds the scheme and a hand-back resolves light on both layers.
• color-scheme-jest-reset.test.tsx: the jest helper's reset puts back the scheme Appearance reports after a test changed it.
• On main, 38 of the 49 cases fail; all pass here.

Verification

Every ci.yml job passes on this head merged into main with #477's harness fix: lint, typecheck, the tests (1396 passed), both builds, the web export, nothing unstaged and commitlint, and the iOS dev build on macOS 27.0.1 with Xcode 27.0, where CI pins 26.6.

Device evidence, before and after: #415 (comment)

Known limits

• The class layer and colorScheme.get() follow the scheme the platform reports, so right after set() they keep the scheme in force until the platform applies the request. React Native 0.82 to 0.87 cache the request in Appearance.getColorScheme() at the call, so an Appearance subscriber that renders before the report reads the request.
• Where the platform never reports the scheme it applied, the class layer keeps the previous one: an Android activity that does not handle uiMode itself, a ReactFragment host, and an iOS app that sets the scheme while in the background, until React Native reports every scheme it applies.
• React Native 0.82.0 to 0.83.4, 0.84.0 and 0.84.1 cache a follow-the-system request verbatim. If an app hands the scheme back through Appearance before this library loads, the class layer answers light until the platform next reports a scheme; and where set(null) moves no scheme, Appearance.getColorScheme() answers 'unspecified' until then, which react/react-native#54993 fixed in 0.83.5 and 0.85.
• This is native. On web, colorScheme.set throws on main, since react-native-web 0.21's Appearance has no setColorScheme; fix(web): set the color scheme on the root element, plus coverage #428 puts the scheme on the root element there.

Merge order

• fix: evaluate range pairs, and answer a condition the runtime cannot decide with unknown #426 moves the media evaluator's prefers-color-scheme lookup into one feature lookup. Whichever lands second resolves the scheme there.
• feat(native): evaluate prefers-reduced-motion so motion-reduce / motion-safe work on native #388 adds prefers-reduced-motion beside the prefers-color-scheme case, and its own resetBetweenTests() in src/jest/reset.ts, which resets the scheme through the public colorScheme. Whichever lands second keeps both resets' lines in one function, the held scheme reset as this PR resets it, since the public set() now asks Appearance and would leave the class layer as it was.
• fix(native): share reactivity state across a dual-package split #427 moves colorScheme into reactivity's pinned process-global state. Whichever lands second reads hasAppearanceModule where that state is created, since a second copy of the module can load after app code hands Appearance back with null.
• fix: own the color scheme union, so the package compiles on react-native 0.81 #429 adds setAppearanceColorScheme, the write that type-checks across the peer range, and a color-scheme.test.tsx case whose native-module double never reports a scheme. Whichever lands second has set() write through it and that double report the scheme it applies.
• fix(native): honour inherits: false on registered custom properties #412 and fix(native): measure em against the font size each element computes #498 add lines to the reset this PR moves into src/jest/reset.ts, and fix(types): type CSS custom properties against what both platforms honour #423, fix(native): a custom property with no value produces no key #431, fix(native): answer :dir() per element, and compile every spelling of it #459, fix(compiler): read a media query's em and rem against the font size rem inlines #494 and fix(web): take the variable name the native variable hooks take #496 change lines beside this PR's in the same files, so whichever lands second resolves them.

[YevheniiKotyrlo]

Outdated: this compared the August heads of #415 and #429. #415 is now re-written onto main (react-native 0.86), and #429 no longer merges into main cleanly.

The original note

Cross-referencing #415 and #429 — they merge with zero conflicts and the result does not compile. Flagging it now, because nothing will warn whoever lands the second one.

git merge-tree --write-tree reports no conflict at all. Running tsc --noEmit on that merged tree gives exactly one error, repo-wide:

src/native/api.tsx(83,31): error TS2345: Argument of type 'ColorSchemeName' is not
  assignable to parameter of type '…Appearance").ColorSchemeName'.
  Type '"unspecified"' is not assignable to type 'ColorSchemeName'.

The two halves are each correct alone:

• fix: own the color scheme union, so the package compiles on react-native 0.81 #429 replaces react-native's ColorSchemeName with this package's own union, which adds "unspecified", and introduces a setAppearanceColorScheme seam in src/color-scheme.ts — routing src/web/api.tsx through it.
• fix(native): make colorScheme.set move every reader of the scheme #415 adds Appearance.setColorScheme(value) at src/native/api.tsx:83, typed by whichever ColorSchemeName is in scope.

On the merge, #429's wider union reaches a call react-native 0.81 types as 'light' | 'dark' | null | undefined, and "unspecified" is not a member.

Neither PR can pre-empt this, which is why it is a note rather than a fix on one of them. #415 cannot import src/color-scheme.ts — that file does not exist on main or on its branch. #429 has no Appearance.setColorScheme call in src/native/api.tsx to route, because on its branch that file has no setter.

The resolution is one line at merge time: route the native setter through the same seam the web one already uses, rather than calling Appearance directly.

// src/native/api.tsx
import { setAppearanceColorScheme } from "../color-scheme";
…
setAppearanceColorScheme(value);   // instead of Appearance.setColorScheme(value)

Measured: that takes the merged tree from one error to zero. The seam exists precisely because the one member the supported react-native range declares incompatibly is the "follow the system" write, so this is what it was built for.

Worth pairing with a compile-level guard, since the failure is a type error rather than a behaviour: the merged tree must typecheck. A runtime twin already exists on #429 at src/__tests__/native/color-scheme.test.tsx:74-76, which drives colorScheme.set("unspecified").

[YevheniiKotyrlo]

Outdated: this compared the August heads of #415 and #429. #415 is now re-written onto main (react-native 0.86), and #429 no longer merges into main cleanly.

The original note

Following up on the cross-reference above with two measured additions, one of which is a trap worth naming explicitly.

An inline cast at the call site compiles, and is the wrong resolution

The obvious shortcut for the merge break is to widen the argument in place rather than route through the seam:

Appearance.setColorScheme(value as Parameters<typeof Appearance.setColorScheme>[0]);

That does take the merged tree to zero type errors, on both react-native ends of the peer range. It is still wrong, because it silences both arms of a union that disagrees for a reason:

0.81.5  Appearance.js   NativeAppearance.setColorScheme(colorScheme ?? 'unspecified');
0.82.0  Appearance.js   NativeAppearance.setColorScheme(colorScheme);

Up to 0.81.5 a nullish request is coerced to "unspecified" before it reaches the native module. From 0.82.0 the coercion is gone and the argument is stored and forwarded verbatim. colorScheme is exported from react-native-css/runtime, and #429 deliberately widens the public ColorScheme.set to accept whichever spelling the installed version emits — so with a cast in place, colorScheme.set(null) puts null into Appearance's cache and hands null to the native module on ≥0.82.

That is the failure #415's own comment forbids in the same function: "Announcing it would put a value in Appearance's cache that no reader can render." setAppearanceColorScheme exists precisely to prevent it, so the seam is the resolution and the cast routes around it.

The boundary is 0.82.0, not 0.86

Measured across every react-native in the Yarn cache, by extracting Libraries/Utilities/Appearance.d.ts from each:

0.81.2 / 0.81.4 / 0.81.5   type ColorSchemeName = 'light' | 'dark' | null | undefined;
0.82.0 … 0.86.0            type ColorSchemeName = 'light' | 'dark' | 'unspecified';

The type narrowing and the loss of the ?? 'unspecified' coercion land in the same release. #429 already names 0.82 on its own surface; #415 said 0.86 in four comments and now names 0.82 too, so the two branches no longer disagree about one boundary when they meet.

One nuance worth recording for whoever touches this next, because it is easy to collapse into the same number: there is a third state later in the range, where setColorScheme resolves "unspecified" against the OS before storing it, rather than storing it verbatim. It is present in 0.85.3 and absent in 0.84.1. I have not placed it more tightly than (0.84.1, 0.85.3], so nothing above names it as a version.

A latent one, for #415

#415's three new colour-scheme test files do not type-check against ≥0.82 — colorScheme.set(null) and friends, where null is no longer in ColorSchemeName. That includes color-scheme-appearance-rn-0-86.test.tsx, which models 0.86 while being written against 0.81's type surface. It is latent for both PRs because neither bumps devDependencies.react-native past 0.81.4, so CI never exercises the surface either PR exists to support — which is itself worth a look on #429.

[YevheniiKotyrlo]

Device evidence — before / after

UNFIXED — The two readings disagree — the class layer moved and Appearance never heard about it.

FIXED — The class-layer reading and the Appearance reading agree, and the swatch matches both.

before — 3.1.0-rc.0	after — with this PR

Android 16 emulator (API 36, GLES on the host GPU), 1140×2400 @ 480dpi, both frames from one run. before is the published 3.1.0-rc.0 plus what my test app needs from my other patches to run: the native and native-internal subpath exports, PR 459, cascade-layer ranking, and a shim that compiles a class-qualified :root inert. after adds the rest of my open PRs, this one included. One of them shows on every screen: PR 417 narrows a var()-valued font-family to one family, so the after sets its text in the theme's face where the before falls back to the platform's.