Repository navigation
Description
Goal
Make @fluentui-react-native/design the modern theming contract: source-backed
defaults, structured appearance, predictable identity and lazy compatibility,
with documented authoring and independently qualified platform behavior.
Status - 2026-11-09
In progress: 12 direct sub-issues, 6 completed and 6 open.
Repository reconciliation against main at
666e3298393be3156d01c3772a5cda0fd390b705.
This replaces the August status; source inspection and merged evidence are not a new native qualification run.
Delivered
- Add appearance-aware Flex theme sources #4295 established Flex-first and legacy-source authoring, one provider,
structured requested/resolved appearance, and revision/appearance-keyed caches. - Add runtime color utilities and contrast validation #4297 delivered runtime color utilities and contrast validation, closing Theming: Runtime Color Utilities #4268
and Theming: Contrast Audit Submodule #4262. They are not pending implementation. - Design: rework Flex tokens, add Fluent themes, and move Fluent 2 token JSON behind design/deprecated #4429 reworked Flex colors into rest-first
InteractiveColorvalues, generated
source-backed Flex defaults and platform Fluent themes, and isolated Fluent 2
runtime JSON loaders behinddesign/deprecated. - Design: isolate Flex palettes and resolve system-aware defaults #4452 added independently bundleable
flexCoolThemeandflexWarmTheme,
shared/cool/warm generated modules, adaptiveflexTheme, and system-aware
provider-free initialization. A provider orThemedRootremains necessary for
live appearance updates. - Storybook now has Theme, Scheme (including System), Contrast, and Tone axes;
its chrome stays Flex while the story may use Flex or Fluent. - Package-owned theming, tokens, colors, entry-point, testing, and migration
references exist. Compatibility fingerprints and source-parity checks exist,
but are not the complete platform/appearance snapshot matrix.
Work items
| Status | Issue | Current outcome or remaining work |
|---|---|---|
| Open | #4261 Apple theme | The existing Apple package still authors a legacy Theme. Review the macOS specification, author the Flex theme, preserve native colors/materials, and qualify it on macOS. |
| Done | #4262 Contrast audit | Delivered by #4297; optional auditing and native-color limitations are documented. |
| Open, substantial progress | #4263 Default values codegen | Generated defaults and palette isolation landed. Reconcile prebuild versus the separate Flex generator, remaining appearance-specific defaults, and the original fine-grained tree-shaking/dedup acceptance with measured evidence. |
| Done | #4264 Dynamic theme building | Delivered by #4295 and extended by #4429/#4452. |
| Done | #4265 High-contrast source consolidation | Shared source processing delivered; native color conventions remain platform-specific. |
| Done | #4266 Mapping drift and upstream pin | Offline mapping/source integrity and authorized drift workflows delivered by #4287. |
| Done | #4267 Package consolidation | Design owns the modern contract; deprecated consumers remain an explicit retirement task, not a second modern API. |
| Done | #4268 Runtime color utilities | Delivered by #4297; lazy interaction derivation is now integrated with Flex resolution. |
| Open, implementation present | #4269 Storybook appearance | Qualify the current axis-based toolbar and live system changes on native hosts; replace historical separate-context and flat-button acceptance with the shipped unified provider model. |
| Open, partial | #4270 System appearance | Structured sources are present; Office current-state/structured-field guarantees, theme-name fallback removal, and deprecated caller migration remain. |
| Open, partial | #4271 Snapshot parity | Add readable resolved-value coverage across the supported platform/appearance matrix; fingerprints, generated-output checks, and source comparisons are useful but different gates. |
| Open, partial | #4272 Documentation | Package references exist; the public Theming guides and theming package index still need Flex-first migration, shim/deprecation, and current API corrections. |
Exit criteria
Beta
- One modern design contract and unified provider support Flex and legacy sources.
- Modern consumers use
useThemeState().tokens; compatibility conversion remains lazy. - Mapping integrity and pinned-source drift procedures exist.
- Flex defaults are generated, with isolated cool/warm descriptions.
- Storybook exposes Flex/Fluent and structured appearance controls.
- Resolve the remaining Theming: Default Values Codegen #4263 build, appearance, and reviewed codegen acceptance.
- Complete structured Office appearance recovery and retire name inference (Theming: Better System Appearance Handling #4270).
- Establish reviewed resolved-value snapshot parity (Theming: Theme Snapshot Parity #4271).
- Record native toolbar/system-change evidence for the current Storybook UI (Theming: Storybook Appearance Integration #4269).
- Finish public authoring and migration guidance (Theming: Theming Documentation Refresh #4272).
Production
- Runtime color and contrast utilities have explicit import boundaries.
- Approve and qualify the Apple/macOS Flex theme (Theming: Apple Theme #4261).
- Approve missing Flex high-contrast/elevated values and Fluent elevated selection;
never invent them from ordinary light/dark palettes. - Retire remaining deprecated token-data consumers through a compatible migration.
- Qualify native shadows/motion and source-specific adaptations when consumed.
- Promote package-cost comparisons into required reviewed budgets with Infrastructure workstream #4275.
Implementation completion does not prove accessibility, visual parity, every
appearance, or every consuming native host.
Current contract and sequencing
Read design guidance
and remaining work.
The old useFlexTokens, flat color fields, and separate Flex context proposals
are obsolete. Modern colors expose rest, hover, and pressed; requested
and resolved scheme/contrast/interface level remain distinct, with color tone
as an authored axis.
- Finish Theming: Default Values Codegen #4263 and Theming: Better System Appearance Handling #4270 without blocking independent documentation, snapshots
of already-supported sets, or Apple specification review. - Record unsupported/fallback appearances explicitly in Theming: Theme Snapshot Parity #4271, rather than
treating light/dark fallback values as a qualified high-contrast theme. - Qualify Theming: Storybook Appearance Integration #4269 and finish Theming: Theming Documentation Refresh #4272 against the current APIs, not their August proposals.
- Keep component adoption/readiness in Components workstream #4274 and shared CI/bundle enforcement in Infrastructure workstream #4275.
Evidence and validation limits
- Merged PRs: Enforce Flex mapping drift checks #4287, Add appearance-aware Flex theme sources #4295, Add runtime color utilities and contrast validation #4297, Design: rework Flex tokens, add Fluent themes, and move Fluent 2 token JSON behind design/deprecated #4429, Design: isolate Flex palettes and resolve system-aware defaults #4452.
- Token provenance and generators
- Current theming contract
- Storybook theme host
- Bundle scenarios
This refresh inspected source, committed tests, merged PR evidence, and live
issue relationships. Package/build/native tests were not run for this
issue-only reconciliation; previous PR results retain their original revision
and platform limits.
Historical workstream scope and acceptance (retained; the reconciled status above is current)
Goal
Make @fluentui-react-native/design the single modern theming contract for
agentic Fluent UI React Native components. Themes should be authored from Flex
tokens or legacy Fluent values, resolve appearance consistently across
platforms, preserve compatibility without forcing legacy code into modern
bundles, and have generated, reviewable defaults.
Status
In progress. Four of twelve direct work items are closed; eight remain open.
PR #4295
completed the central theme-source and appearance architecture:
- Added
FlexThemeReference, structured requested/resolved appearance axes, and
stable theme-state/token identity keyed by source revision and appearance. - Reworked
ThemeProvideraround one external-store source contract for nested
Flex and legacy themes without mutating author-owned values. - Made
useThemeState().tokensthe sole modern consumption path and removed the
temporaryuseFlexTokensAPI. - Kept legacy
ThemeReference,ThemeProvider,ThemeContext, anduseTheme
behavior compatible through lazy conversion boundaries. - Added schema-v2 forward and reverse token mappings with explicit collisions,
fallbacks, transforms, and omissions. - Migrated default, Android, Apple, Windows, macOS, iOS, and Win32 theme handling
to the structured appearance model. - Added macOS, Windows, and Win32 bundle scenarios proving that modern Flex and
modern legacy-source paths exclude reverse compatibility payloads.
This closes dynamic theme building
(#4264).
Package consolidation
(#4267),
high-contrast source consolidation
(#4265), and
mapping drift enforcement
(#4266,
PR #4287)
are also closed.
PR #4295 partially completes system appearance handling
(#4270).
The remaining Win32 Office native contract has no synchronous current-state
getter, so an appearance change while no consumer is subscribed cannot be
recovered until another native event. Host-theme string inference remains a
transitional fallback.
What is left
- Generate Flex defaults from token sources, including reviewed
cross-appearance de-duplication
(#4263). - Finish Theming: Better System Appearance Handling #4270 by resolving the Win32 Office current-state contract and remove
transitional inference when structured native state is reliable. - Add reviewed resolved-token snapshots for every supported platform and
appearance (#4271). - Integrate dynamic system appearance and Flex-authored themes into Storybook
(#4269). - Refresh design and migration documentation around the approved modern and
compatibility paths
(#4272). - Build and validate the specification-backed Apple/macOS Flex theme
(#4261). - Add tree-shakeable runtime color derivation and contrast-audit submodules
(#4268,
#4262).
Work items
| Status | Issue | Outcome or remaining work |
|---|---|---|
| Open | #4261 - Apple Theme | Build a Flex-contract macOS theme and validate it against the approved design source. |
| Open | #4262 - Contrast audit submodule | Add optional auditing, approved pairings, native-color diagnostics, and bundle isolation. |
| Open | #4263 - Default values codegen | Replace hand-authored Flex defaults with generated and de-duplicated values. |
| Done | #4264 - Dynamic theme building | Flex-first and legacy-source authoring merged in PR #4295. |
| Done | #4265 - High-contrast source consolidation | Shared processing landed while preserving platform-native color naming. |
| Done | #4266 - Mapping drift and upstream pin | Offline consistency checks, source pin, and drift reporting merged in PR #4287. |
| Done | #4267 - Package consolidation | The design package owns the modern public contract; remaining packages are compatibility or platform layers. |
| Open | #4268 - Runtime color utilities | Port verified x3 interaction derivation into an optional submodule. |
| Open | #4269 - Storybook appearance integration | Add dynamic appearance controls, Flex-authored theme coverage, and token-driven chrome. |
| Open, partial | #4270 - System appearance handling | Structured appearance is merged; Win32 Office current-state recovery remains. |
| Open | #4271 - Theme snapshot parity | Review and gate resolved token sets for each supported appearance/platform. |
| Open | #4272 - Theming documentation refresh | Document modern authoring, compatibility, migration, appearance, and update workflows. |
Beta exit criteria
-
@fluentui-react-native/designowns the modern theme construction,
appearance, Flex-token, and styling contract. - A theme can be authored directly from Flex tokens and consumed without
first constructing a legacy FluentTheme. -
useThemeState().tokensis the sole modern token path; legacy theme
construction and reverse conversion are lazy compatibility capabilities. - Mapping consistency is CI-enforced and the x3 source revision has an
offline-safe pin, drift report, and update workflow. - High-contrast source processing is consolidated without changing
Windows/Win32 native color naming. - Flex default values are generated rather than maintained as color literal
tables. - Structured light, dark, and high-contrast resolution is complete on every
supported platform, including current-state recovery on Win32 Office. - Every supported resolved appearance has a reviewed token snapshot.
- Storybook follows system appearance and renders a Flex-authored theme.
- The design package and theming guides document the approved modern,
compatibility, and migration paths.
Production exit criteria
- Runtime color derivation is an optional submodule verified against x3 and
absent unless imported. - Generated defaults de-duplicate shared values across appearances and
platforms, with measured bundle evidence. - Legacy Fluent token construction runs only when a legacy consumer requests
it; modern bundle scenarios enforce the boundary. - The Apple/macOS Flex theme matches an owner-approved specification.
- The optional contrast submodule audits approved pairings, reports
unresolvable native colors explicitly, and remains tree-shakeable. - Deprecation and migration guidance exists for every compatibility layer.
- Cross-platform package-cost budgets are promoted from warning/advisory
comparison to required reviewed gates.
Agent context
Public contract
- Modern consumers use
useThemeState()and readThemeState.tokens. - Theme authors may supply an appearance-aware Flex source or a legacy Fluent
source through the unified provider boundary. - Legacy-to-Flex conversion is loaded only when modern consumers receive a
legacy source. - Flex-to-legacy conversion and complete legacy defaults are loaded only when a
legacyuseThemeconsumer requests them. - Compatibility modules must remain thin and must not become alternate sources
of theme truth.
Appearance caveats
- Requested appearance and resolved appearance are distinct axes.
- Structured
colorSchemeandisHighContrastvalues are preferred whenever a
native source supplies them. - Win32 Office currently exposes initial constants and events but no synchronous
current-state query. Preserve event-maintained state across subscribers until
that native contract changes. - x3 Flex themes define light/dark web behavior but no forced-colors or
high-contrast source. FURN therefore owns its native high-contrast adaptation
and must document that divergence.
Sequencing
- Generated defaults and final Win32 appearance state unblock reviewed snapshot
parity. - Stable snapshots and source APIs unblock Storybook appearance coverage and
documentation. - Runtime color utilities establish the optional color-math boundary reused by
contrast auditing. - The Apple theme depends on stable dynamic sources, generated defaults, and
the Storybook macOS validation surface. - Package-cost enforcement is shared with
#4275;
component adoption evidence is shared with
#4274.
Merged evidence
- PR #4295 - Add appearance-aware Flex theme sources
- PR #4287 - Enforce Flex mapping drift checks
- PR #4294 - Infrastructure: land the public desktop driver
- PR #4296 - Pivot agentic component specs and align implementations
packages/agentic/design/src/theming/packages/agentic/design/src/tokens/mappings/- Cross-platform bundle scenarios in
apps/bundle-size
Activity