Skip to content

Commit ccb458e

Browse files
authored
allow both cool and warm tokens to be used independently (#4452)
1 parent cd0ede2 commit ccb458e

29 files changed

Lines changed: 793 additions & 530 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@fluentui-react-native/design': patch
3+
---
4+
5+
Add independently bundleable flexCoolTheme and flexWarmTheme descriptions, let flexTheme select its palette from appearance.colorTone, and use flexCoolTheme for no-theme fallbacks.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@fluentui-react-native/design': patch
3+
---
4+
5+
Lazily initialize the fallback Flex theme state once using the current system light or dark appearance, and keep the fallback appearance hooks consistent.

‎apps/bundle-size/scenarios.json‎

Lines changed: 37 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,6 @@
1111
"module": "@fluentui-react-native/components",
1212
"namespace": true
1313
},
14-
{
15-
"name": "design-theme-state",
16-
"module": "@fluentui-react-native/design",
17-
"exports": ["FlexThemeReference", "ThemeProvider", "useThemeState"],
18-
"forbiddenInputPatterns": ["/design/src/fluent/", "/design/src/deprecated/", "/design/src/test/", "/color-lib/compositing."],
19-
"requiredInputPatterns": [
20-
"/design/src/flex/flexThemeReference.",
21-
"/design/src/flex/useThemeState.",
22-
"/design/src/theming/ThemeProvider."
23-
],
24-
"requiredOutputPatterns": ["/color-lib/interaction.", "/design/src/flex/colors/interactionPolicy."]
25-
},
2614
{
2715
"name": "design-themed-root",
2816
"module": "@fluentui-react-native/design",
@@ -153,9 +141,34 @@
153141
"/design/src/test/",
154142
"/color-lib/compositing."
155143
],
156-
"requiredInputPatterns": ["/design/src/flex/defaults/defaultTokens.generated."],
157-
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/", "/design/src/themes/flex/flexWarmTheme."],
158-
"requiredOutputPatterns": ["/design/src/themes/flex/flexTheme.", "/design/src/flex/defaults/defaultTokens.generated."]
144+
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
145+
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/"],
146+
"requiredOutputPatterns": [
147+
"/design/src/themes/flex/flexTheme.",
148+
"/design/src/flex/defaults/coolTokens.generated.",
149+
"/design/src/flex/defaults/warmTokens.generated."
150+
]
151+
},
152+
{
153+
"name": "design-flex-cool-theme",
154+
"module": "@fluentui-react-native/design/themes",
155+
"exports": ["flexCoolTheme"],
156+
"forbiddenInputPatterns": [
157+
"/design/src/fluent/compat/",
158+
"/design/src/deprecated/",
159+
"/design/src/fluent/useTheme.",
160+
"/design/src/test/",
161+
"/color-lib/compositing."
162+
],
163+
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
164+
"forbiddenOutputPatterns": [
165+
"/design/src/fluent/",
166+
"/design/src/themes/fluent/",
167+
"/design/src/themes/flex/flexTheme.",
168+
"/design/src/themes/flex/flexWarmTheme.",
169+
"/design/src/flex/defaults/warmTokens.generated."
170+
],
171+
"requiredOutputPatterns": ["/design/src/themes/flex/flexCoolTheme.", "/design/src/flex/defaults/coolTokens.generated."]
159172
},
160173
{
161174
"name": "design-flex-warm-theme",
@@ -168,9 +181,15 @@
168181
"/design/src/test/",
169182
"/color-lib/compositing."
170183
],
171-
"requiredInputPatterns": ["/design/src/flex/defaults/defaultTokens.generated."],
172-
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/", "/design/src/themes/flex/flexTheme."],
173-
"requiredOutputPatterns": ["/design/src/themes/flex/flexWarmTheme.", "/design/src/flex/defaults/defaultTokens.generated."]
184+
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
185+
"forbiddenOutputPatterns": [
186+
"/design/src/fluent/",
187+
"/design/src/themes/fluent/",
188+
"/design/src/themes/flex/flexTheme.",
189+
"/design/src/themes/flex/flexCoolTheme.",
190+
"/design/src/flex/defaults/coolTokens.generated."
191+
],
192+
"requiredOutputPatterns": ["/design/src/themes/flex/flexWarmTheme.", "/design/src/flex/defaults/warmTokens.generated."]
174193
}
175194
]
176195
}

‎packages/agentic/design/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,9 @@ export const App = () => (
4646
Use `fluentLightTheme` or `fluentDarkTheme` when you need one fixed `Theme` object, or `fluentHcTheme` to always use
4747
high contrast.
4848

49-
The same entry point ships the x3 Flex defaults as `flexTheme` (cool) and `flexWarmTheme` (warm). Each is a
50-
`FlexThemeDescription` covering light and dark; use one as a `FlexThemeReference` base to start from that palette and
51-
tone:
49+
The same entry point ships the x3 Flex defaults as `flexCoolTheme` and `flexWarmTheme`, independently bundleable
50+
descriptions covering light and dark. `flexTheme` includes both and switches palettes with `appearance.colorTone`.
51+
Use one as a `FlexThemeReference` base:
5252

5353
```tsx
5454
import { FlexThemeReference } from '@fluentui-react-native/design';
@@ -57,6 +57,8 @@ import { flexWarmTheme } from '@fluentui-react-native/design/themes';
5757
const theme = new FlexThemeReference({ base: flexWarmTheme, appearance: { colorScheme: 'system' } });
5858
```
5959

60+
Without an explicit theme or inherited boundary, `ThemedRoot` and the theme hooks use `flexCoolTheme`.
61+
6062
## Documentation
6163

6264
| Topic | Covers |

‎packages/agentic/design/references/contributing.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,9 @@ committed; change their inputs and regenerate rather than editing them.
5151
- Keep `src/themes/` a consumer of generated tokens. `src/themes/fluent/` may reach `ThemeReference`, the generated
5252
Fluent tokens, and the generated global tokens, but never `src/flex/`, `src/color-lib/`, `useTheme`,
5353
`src/fluent/compat/`, or `src/deprecated/`, and it authors no color value that the generated alias colors lack.
54-
`src/themes/flex/` exposes the x3 default descriptions unchanged and never reaches `src/fluent/` or
55-
`color-lib/compositing`. The tests under `src/themes/`, the import-boundary test, and the `design-fluent-*` and
54+
`src/themes/flex/` exposes the fixed x3 default descriptions unchanged and an adaptive description that selects one
55+
by resolved color tone. Each fixed theme must not reach the other palette's generated module. These themes never reach
56+
`src/fluent/` or `color-lib/compositing`. The tests under `src/themes/`, the import-boundary test, and the `design-fluent-*` and
5657
`design-flex-*` bundle-size scenarios guard this.
5758
- Never mutate author-owned theme inputs; caches are external and keyed by source, revision, and resolved appearance.
5859
- Keep color resolution lazy: resolving tokens, reading rest, merging, and copying the color map must not run the

‎packages/agentic/design/references/entry-points.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,20 @@ owner_paths:
1010
The package is `sideEffects: false` and exposes explicit subpaths so consumers load only the graph they use. Export
1111
public symbols by name from each entry point; do not add barrel re-exports.
1212

13-
| Subpath | Contents |
14-
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
15-
| `.` (root) | Modern theming (`ThemeProvider`, `ThemedRoot`, `FlexThemeReference`, hooks), Flex token types |
16-
| `./theming` | The complete modern and legacy theming API, including `ThemeReference` and `useTheme` |
17-
| `./theming/legacy-source` | `ThemeReference` without the legacy consumption graph |
18-
| `./theming/compat` | `themeFromFlexTokens`, which projects Flex tokens onto the Fluent theme for the appearance |
19-
| `./themes` | Ready-made themes: `fluentLightTheme`, `fluentDarkTheme`, `fluentHcTheme`, `fluentTheme`, `flexTheme`, and `flexWarmTheme` |
20-
| `./tokens/global` | Generated platform global token constants |
21-
| `./color-lib` | Raw color parsing, conversion, compositing, and interaction algorithms; see `color-lib.md` |
22-
| `./styling` | State and color style factories; see `styling.md` |
23-
| `./styling/stylesheet` | The legacy `themedStyleSheet` helper |
24-
| `./styling/tokens` | Legacy token-to-style builders |
25-
| `./testing` | Test-only fixtures and validation; see `testing.md` |
26-
| `./deprecated` | Fluent 2 token JSON loaders and pipeline mappers, restricted to existing consumers; see [below](#deprecated-entry-point) |
13+
| Subpath | Contents |
14+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| `.` (root) | Modern theming (`ThemeProvider`, `ThemedRoot`, `FlexThemeReference`, hooks), Flex token types |
16+
| `./theming` | The complete modern and legacy theming API, including `ThemeReference` and `useTheme` |
17+
| `./theming/legacy-source` | `ThemeReference` without the legacy consumption graph |
18+
| `./theming/compat` | `themeFromFlexTokens`, which projects Flex tokens onto the Fluent theme for the appearance |
19+
| `./themes` | Ready-made themes: `fluentLightTheme`, `fluentDarkTheme`, `fluentHcTheme`, `fluentTheme`, `flexTheme`, `flexCoolTheme`, and `flexWarmTheme` |
20+
| `./tokens/global` | Generated platform global token constants |
21+
| `./color-lib` | Raw color parsing, conversion, compositing, and interaction algorithms; see `color-lib.md` |
22+
| `./styling` | State and color style factories; see `styling.md` |
23+
| `./styling/stylesheet` | The legacy `themedStyleSheet` helper |
24+
| `./styling/tokens` | Legacy token-to-style builders |
25+
| `./testing` | Test-only fixtures and validation; see `testing.md` |
26+
| `./deprecated` | Fluent 2 token JSON loaders and pipeline mappers, restricted to existing consumers; see [below](#deprecated-entry-point) |
2727

2828
The `apps/bundle-size` `design-*` scenarios guard these boundaries. Input patterns check the import graph and output
2929
patterns check the modules a tree-shaken bundle retains. Every design scenario except the color-library one forbids
@@ -34,7 +34,8 @@ legacy-source scenario also forbids a retained `FlexThemeReference`. Only the le
3434
`color-lib/` or `flex/` module. The Fluent theme scenarios forbid `useTheme` and the compatibility modules from the
3535
import graph and any retained `flex/`, `color-lib/`, or Flex theme module, and a bundle that imports only
3636
`fluentLightTheme` retains no other theme and no `ThemeReference`, while one that imports only `fluentHcTheme` retains
37-
only the high-contrast themes. The Flex theme scenarios require the x3 defaults and forbid `fluent/` and
37+
only the high-contrast themes. The fixed Flex theme scenarios reject the other palette's generated data in retained
38+
output; the dynamic `flexTheme` scenario requires both palettes. The Flex theme scenarios require the x3 defaults and forbid `fluent/` and
3839
`color-lib/compositing`. The color-library scenario requires its algorithms, and the legacy-projection scenario requires
3940
the projection, the Fluent theme selection, and the generated Fluent tokens it projects onto. Every scenario also
4041
requires a module it is expected to load, so a moved file cannot make a forbidden pattern pass vacuously.

‎packages/agentic/design/references/theming.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@ may be a function of the resolved appearance, which always has a concrete `color
3131
authored description and the resolved appearance. `PartialFlexTokens` is shape-aware so opaque React Native colors stay
3232
leaves. `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
3738
changes 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,
7576
requested 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.
7879
User-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

173180
Each 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
179188
import { FlexThemeReference } from '@fluentui-react-native/design';
@@ -182,6 +191,9 @@ import { flexWarmTheme } from '@fluentui-react-native/design/themes';
182191
const 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

187199
The package root exports only the modern authoring and consumption APIs. It reaches the forward Theme-to-Flex adapter,

‎packages/agentic/design/references/tokens.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,12 @@ objects that the declarations spread. The emitted key order is therefore not mea
7070

7171
## Default tokens
7272

73-
`src/flex/defaults/defaultTokens.generated.ts` holds the cool and warm x3 defaults, and `defaultTokens.ts` normalizes
74-
them. `FlexThemeReference` merges the default for the resolved `colorTone` under its base and recipes, and the `themes`
75-
entry point exposes the two defaults as `flexTheme` and `flexWarmTheme` (`theming.md`). The x3 sources
73+
`src/flex/defaults/sharedTokens.generated.ts` holds only entries identical in both palettes.
74+
`coolTokens.generated.ts` and `warmTokens.generated.ts` add each palette's entries without importing the other.
75+
`defaultTokens.ts` exposes the normalized defaults for existing internal consumers and test fixtures.
76+
`FlexThemeReference` merges the default for the resolved `colorTone` under its base and recipes, unless a complete
77+
description replaces it. The `themes` entry point exposes isolated `flexCoolTheme` and `flexWarmTheme` descriptions
78+
and an adaptive `flexTheme` description (`theming.md`). The x3 sources
7679
define no high-contrast or elevated values, so those appearances use the light or dark default. Defaults do not
7780
otherwise vary by contrast or interface level; see `remaining-work.md`. Tests that assert default values should read
7881
them from `defaultFlexTokens` in the `testing` entry point rather than repeating literals.
@@ -85,7 +88,7 @@ values, whether each interaction state is computed or explicit, and any native a
8588
16 density-independent pixels, durations to milliseconds, `cubic-bezier()` to tuples, variable font weights to native
8689
static weights, and relative `oklch` shadow alphas to `#rrggbbaa`. Opaque colors are emitted as `#rrggbb`.
8790

88-
Regenerate both files from the pinned snapshots, or verify that they are current:
91+
Regenerate the token files and coverage ledger from the pinned snapshots, or verify that they are current:
8992

9093
```sh
9194
yarn workspace @fluentui-react-native/design gen:flex-defaults

0 commit comments

Comments
 (0)