@@ -31,8 +31,9 @@ may be a function of the resolved appearance, which always has a concrete `color
3131authored description and the resolved appearance. ` PartialFlexTokens ` is shape-aware so opaque React Native colors stay
3232leaves. ` tokens.md ` describes the defaults.
3333
34- A base may instead be a ` FlexThemeDescription ` : a complete ` FlexTokenDescription ` in ` tokens ` and an optional
35- ` colorTone ` . Its tokens replace the package defaults for every appearance, and its tone becomes the reference's default
34+ A base may instead be a ` FlexThemeDescription ` : a complete ` FlexTokenDescription ` in ` tokens ` , or a function of the
35+ resolved appearance returning one, and an optional ` colorTone ` . Its tokens replace the package defaults for every
36+ appearance, and its tone becomes the reference's default
3637` appearance.colorTone ` when the ` appearance ` option sets none. A provider's ` appearance ` request still wins, and it
3738changes only the interaction algorithm, not the description's palette. The Flex themes below are descriptions.
3839
@@ -73,7 +74,7 @@ resolves from the provider prop, then the source option, then the selected appea
7374
7475` ThemedRoot ` is a ` View ` wrapped in a ` ThemeProvider ` . With no ` theme ` , it inherits the nearest boundary's source,
7576requested appearance, appearance source, and fallback, overriding only the fields it sets; with no boundary it uses a
76- default ` FlexThemeReference ` . An explicit ` theme ` starts a new configuration. The outermost root also provides
77+ ` FlexThemeReference ` based on ` flexCoolTheme ` . An explicit ` theme ` starts a new configuration. The outermost root also provides
7778` RootContext ` and input-modality tracking; ` RootInputBoundary ` attaches popup or window content to the same scene.
7879User-facing examples are in the repository's
7980[ theming basics] ( https://github.com/microsoft/fluentui-react-native/blob/main/docs/pages/Theming/Basics.md ) .
@@ -92,6 +93,11 @@ legacy boundary for all of them, which keeps deprecated `ThemeLayer` and direct
9293
9394` ThemeState.highContrast ` is deprecated; use ` appearance.contrast ` .
9495
96+ Without a boundary, the first call to either Flex hook initializes one shared default state from ` flexCoolTheme ` , using
97+ React Native ` Appearance.getColorScheme() ` (or light when unavailable). Its tokens, resolved appearance, and style
98+ registry are reused for subsequent calls; it does not subscribe to system changes. Use a provider or ` ThemedRoot ` for
99+ live appearance updates.
100+
95101| Active source | Provider mount | ` useThemeState ` | ` useTheme ` |
96102| ------------- | ---------------------------------- | --------------------------------- | -------------------------------------- |
97103| Legacy | Resolves the authored ` Theme ` only | Projects ` Theme ` to Flex once | Returns the authored ` Theme ` |
@@ -167,13 +173,16 @@ The `themes` entry point also provides the x3 Flex defaults (`tokens.md`) as `Fl
167173
168174| Export | Kind | Contents |
169175| --------------- | ---------------------- | -------------------------------------------------- |
170- | ` flexTheme ` | ` FlexThemeDescription ` | The cool light and dark defaults, with tone ` cool ` |
176+ | ` flexCoolTheme ` | ` FlexThemeDescription ` | The cool light and dark defaults, with tone ` cool ` |
171177| ` flexWarmTheme ` | ` FlexThemeDescription ` | The warm light and dark defaults, with tone ` warm ` |
178+ | ` flexTheme ` | ` FlexThemeDescription ` | Both palettes, selected by resolved ` colorTone ` |
172179
173180Each is a theme description rather than a source: pass it as a ` FlexThemeReference ` base, alone or under recipes. A
174- reference built on ` flexTheme ` or ` flexWarmTheme ` resolves the same tokens as a default ` FlexThemeReference ` requesting
175- that tone. Both descriptions are the shared default objects, so treat them as read-only; author changes as recipes or a
176- new description.
181+ reference built on a fixed theme keeps its palette even if a provider requests another interaction tone. Each fixed
182+ theme loads only its own palette and the tokens both palettes share. ` flexTheme.tokens ` is a resolver that selects the
183+ cool or warm description for the resolved ` appearance.colorTone ` ; changing that provider request changes both the
184+ palette and interaction tone, with normal per-appearance caching. With no tone request it selects cool. Treat these
185+ shared descriptions as read-only; author changes as recipes or a new description.
177186
178187``` ts
179188import { FlexThemeReference } from ' @fluentui-react-native/design' ;
@@ -182,6 +191,9 @@ import { flexWarmTheme } from '@fluentui-react-native/design/themes';
182191const theme = new FlexThemeReference ({ base: flexWarmTheme , appearance: { colorScheme: ' system' } });
183192```
184193
194+ For dynamic palette switching, use ` flexTheme ` as the base and set
195+ ` <ThemeProvider theme={theme} appearance={{ colorTone: 'warm' }}> ` (or ` 'cool' ` ).
196+
185197## Legacy projection and bundle boundary
186198
187199The package root exports only the modern authoring and consumption APIs. It reaches the forward Theme-to-Flex adapter,
0 commit comments