Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/design-flex-palette-loading.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/design': patch
---

Add independently bundleable flexCoolTheme and flexWarmTheme descriptions, let flexTheme select its palette from appearance.colorTone, and use flexCoolTheme for no-theme fallbacks.
5 changes: 5 additions & 0 deletions .changeset/design-system-default-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/design': patch
---

Lazily initialize the fallback Flex theme state once using the current system light or dark appearance, and keep the fallback appearance hooks consistent.
55 changes: 37 additions & 18 deletions apps/bundle-size/scenarios.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,6 @@
"module": "@fluentui-react-native/components",
"namespace": true
},
{
"name": "design-theme-state",
"module": "@fluentui-react-native/design",
"exports": ["FlexThemeReference", "ThemeProvider", "useThemeState"],
"forbiddenInputPatterns": ["/design/src/fluent/", "/design/src/deprecated/", "/design/src/test/", "/color-lib/compositing."],
"requiredInputPatterns": [
"/design/src/flex/flexThemeReference.",
"/design/src/flex/useThemeState.",
"/design/src/theming/ThemeProvider."
],
"requiredOutputPatterns": ["/color-lib/interaction.", "/design/src/flex/colors/interactionPolicy."]
},
{
"name": "design-themed-root",
"module": "@fluentui-react-native/design",
Expand Down Expand Up @@ -153,9 +141,34 @@
"/design/src/test/",
"/color-lib/compositing."
],
"requiredInputPatterns": ["/design/src/flex/defaults/defaultTokens.generated."],
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/", "/design/src/themes/flex/flexWarmTheme."],
"requiredOutputPatterns": ["/design/src/themes/flex/flexTheme.", "/design/src/flex/defaults/defaultTokens.generated."]
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/"],
"requiredOutputPatterns": [
"/design/src/themes/flex/flexTheme.",
"/design/src/flex/defaults/coolTokens.generated.",
"/design/src/flex/defaults/warmTokens.generated."
]
},
{
"name": "design-flex-cool-theme",
"module": "@fluentui-react-native/design/themes",
"exports": ["flexCoolTheme"],
"forbiddenInputPatterns": [
"/design/src/fluent/compat/",
"/design/src/deprecated/",
"/design/src/fluent/useTheme.",
"/design/src/test/",
"/color-lib/compositing."
],
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
"forbiddenOutputPatterns": [
"/design/src/fluent/",
"/design/src/themes/fluent/",
"/design/src/themes/flex/flexTheme.",
"/design/src/themes/flex/flexWarmTheme.",
"/design/src/flex/defaults/warmTokens.generated."
],
"requiredOutputPatterns": ["/design/src/themes/flex/flexCoolTheme.", "/design/src/flex/defaults/coolTokens.generated."]
},
{
"name": "design-flex-warm-theme",
Expand All @@ -168,9 +181,15 @@
"/design/src/test/",
"/color-lib/compositing."
],
"requiredInputPatterns": ["/design/src/flex/defaults/defaultTokens.generated."],
"forbiddenOutputPatterns": ["/design/src/fluent/", "/design/src/themes/fluent/", "/design/src/themes/flex/flexTheme."],
"requiredOutputPatterns": ["/design/src/themes/flex/flexWarmTheme.", "/design/src/flex/defaults/defaultTokens.generated."]
"requiredInputPatterns": ["/design/src/flex/defaults/sharedTokens.generated."],
"forbiddenOutputPatterns": [
"/design/src/fluent/",
"/design/src/themes/fluent/",
"/design/src/themes/flex/flexTheme.",
"/design/src/themes/flex/flexCoolTheme.",
"/design/src/flex/defaults/coolTokens.generated."
],
"requiredOutputPatterns": ["/design/src/themes/flex/flexWarmTheme.", "/design/src/flex/defaults/warmTokens.generated."]
}
]
}
8 changes: 5 additions & 3 deletions packages/agentic/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,9 @@ export const App = () => (
Use `fluentLightTheme` or `fluentDarkTheme` when you need one fixed `Theme` object, or `fluentHcTheme` to always use
high contrast.

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

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

Without an explicit theme or inherited boundary, `ThemedRoot` and the theme hooks use `flexCoolTheme`.

## Documentation

| Topic | Covers |
Expand Down
5 changes: 3 additions & 2 deletions packages/agentic/design/references/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,9 @@ committed; change their inputs and regenerate rather than editing them.
- Keep `src/themes/` a consumer of generated tokens. `src/themes/fluent/` may reach `ThemeReference`, the generated
Fluent tokens, and the generated global tokens, but never `src/flex/`, `src/color-lib/`, `useTheme`,
`src/fluent/compat/`, or `src/deprecated/`, and it authors no color value that the generated alias colors lack.
`src/themes/flex/` exposes the x3 default descriptions unchanged and never reaches `src/fluent/` or
`color-lib/compositing`. The tests under `src/themes/`, the import-boundary test, and the `design-fluent-*` and
`src/themes/flex/` exposes the fixed x3 default descriptions unchanged and an adaptive description that selects one
by resolved color tone. Each fixed theme must not reach the other palette's generated module. These themes never reach
`src/fluent/` or `color-lib/compositing`. The tests under `src/themes/`, the import-boundary test, and the `design-fluent-*` and
`design-flex-*` bundle-size scenarios guard this.
- Never mutate author-owned theme inputs; caches are external and keyed by source, revision, and resolved appearance.
- Keep color resolution lazy: resolving tokens, reading rest, merging, and copying the color map must not run the
Expand Down
31 changes: 16 additions & 15 deletions packages/agentic/design/references/entry-points.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,20 @@ owner_paths:
The package is `sideEffects: false` and exposes explicit subpaths so consumers load only the graph they use. Export
public symbols by name from each entry point; do not add barrel re-exports.

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

The `apps/bundle-size` `design-*` scenarios guard these boundaries. Input patterns check the import graph and output
patterns check the modules a tree-shaken bundle retains. Every design scenario except the color-library one forbids
Expand All @@ -34,7 +34,8 @@ legacy-source scenario also forbids a retained `FlexThemeReference`. Only the le
`color-lib/` or `flex/` module. The Fluent theme scenarios forbid `useTheme` and the compatibility modules from the
import graph and any retained `flex/`, `color-lib/`, or Flex theme module, and a bundle that imports only
`fluentLightTheme` retains no other theme and no `ThemeReference`, while one that imports only `fluentHcTheme` retains
only the high-contrast themes. The Flex theme scenarios require the x3 defaults and forbid `fluent/` and
only the high-contrast themes. The fixed Flex theme scenarios reject the other palette's generated data in retained
output; the dynamic `flexTheme` scenario requires both palettes. The Flex theme scenarios require the x3 defaults and forbid `fluent/` and
`color-lib/compositing`. The color-library scenario requires its algorithms, and the legacy-projection scenario requires
the projection, the Fluent theme selection, and the generated Fluent tokens it projects onto. Every scenario also
requires a module it is expected to load, so a moved file cannot make a forbidden pattern pass vacuously.
Expand Down
26 changes: 19 additions & 7 deletions packages/agentic/design/references/theming.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@ may be a function of the resolved appearance, which always has a concrete `color
authored description and the resolved appearance. `PartialFlexTokens` is shape-aware so opaque React Native colors stay
leaves. `tokens.md` describes the defaults.

A base may instead be a `FlexThemeDescription`: a complete `FlexTokenDescription` in `tokens` and an optional
`colorTone`. Its tokens replace the package defaults for every appearance, and its tone becomes the reference's default
A base may instead be a `FlexThemeDescription`: a complete `FlexTokenDescription` in `tokens`, or a function of the
resolved appearance returning one, and an optional `colorTone`. Its tokens replace the package defaults for every
appearance, and its tone becomes the reference's default
`appearance.colorTone` when the `appearance` option sets none. A provider's `appearance` request still wins, and it
changes only the interaction algorithm, not the description's palette. The Flex themes below are descriptions.

Expand Down Expand Up @@ -73,7 +74,7 @@ resolves from the provider prop, then the source option, then the selected appea

`ThemedRoot` is a `View` wrapped in a `ThemeProvider`. With no `theme`, it inherits the nearest boundary's source,
requested appearance, appearance source, and fallback, overriding only the fields it sets; with no boundary it uses a
default `FlexThemeReference`. An explicit `theme` starts a new configuration. The outermost root also provides
`FlexThemeReference` based on `flexCoolTheme`. An explicit `theme` starts a new configuration. The outermost root also provides
`RootContext` and input-modality tracking; `RootInputBoundary` attaches popup or window content to the same scene.
User-facing examples are in the repository's
[theming basics](https://github.com/microsoft/fluentui-react-native/blob/main/docs/pages/Theming/Basics.md).
Expand All @@ -92,6 +93,11 @@ legacy boundary for all of them, which keeps deprecated `ThemeLayer` and direct

`ThemeState.highContrast` is deprecated; use `appearance.contrast`.

Without a boundary, the first call to either Flex hook initializes one shared default state from `flexCoolTheme`, using
React Native `Appearance.getColorScheme()` (or light when unavailable). Its tokens, resolved appearance, and style
registry are reused for subsequent calls; it does not subscribe to system changes. Use a provider or `ThemedRoot` for
live appearance updates.

| Active source | Provider mount | `useThemeState` | `useTheme` |
| ------------- | ---------------------------------- | --------------------------------- | -------------------------------------- |
| Legacy | Resolves the authored `Theme` only | Projects `Theme` to Flex once | Returns the authored `Theme` |
Expand Down Expand Up @@ -167,13 +173,16 @@ The `themes` entry point also provides the x3 Flex defaults (`tokens.md`) as `Fl

| Export | Kind | Contents |
| --------------- | ---------------------- | -------------------------------------------------- |
| `flexTheme` | `FlexThemeDescription` | The cool light and dark defaults, with tone `cool` |
| `flexCoolTheme` | `FlexThemeDescription` | The cool light and dark defaults, with tone `cool` |
| `flexWarmTheme` | `FlexThemeDescription` | The warm light and dark defaults, with tone `warm` |
| `flexTheme` | `FlexThemeDescription` | Both palettes, selected by resolved `colorTone` |

Each is a theme description rather than a source: pass it as a `FlexThemeReference` base, alone or under recipes. A
reference built on `flexTheme` or `flexWarmTheme` resolves the same tokens as a default `FlexThemeReference` requesting
that tone. Both descriptions are the shared default objects, so treat them as read-only; author changes as recipes or a
new description.
reference built on a fixed theme keeps its palette even if a provider requests another interaction tone. Each fixed
theme loads only its own palette and the tokens both palettes share. `flexTheme.tokens` is a resolver that selects the
cool or warm description for the resolved `appearance.colorTone`; changing that provider request changes both the
palette and interaction tone, with normal per-appearance caching. With no tone request it selects cool. Treat these
shared descriptions as read-only; author changes as recipes or a new description.

```ts
import { FlexThemeReference } from '@fluentui-react-native/design';
Expand All @@ -182,6 +191,9 @@ import { flexWarmTheme } from '@fluentui-react-native/design/themes';
const theme = new FlexThemeReference({ base: flexWarmTheme, appearance: { colorScheme: 'system' } });
```

For dynamic palette switching, use `flexTheme` as the base and set
`<ThemeProvider theme={theme} appearance={{ colorTone: 'warm' }}>` (or `'cool'`).

## Legacy projection and bundle boundary

The package root exports only the modern authoring and consumption APIs. It reaches the forward Theme-to-Flex adapter,
Expand Down
11 changes: 7 additions & 4 deletions packages/agentic/design/references/tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,12 @@ objects that the declarations spread. The emitted key order is therefore not mea

## Default tokens

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

Regenerate both files from the pinned snapshots, or verify that they are current:
Regenerate the token files and coverage ledger from the pinned snapshots, or verify that they are current:

```sh
yarn workspace @fluentui-react-native/design gen:flex-defaults
Expand Down
Loading
Loading