Add appearance-aware Flex theme sources

[Jason Morse (JasonVMo)]

Platforms Impacted

• iOS
• macOS
• win32 (Office)
• windows
• android

Description of changes

Adds an appearance-aware theming source model that supports both Flex-first and legacy Fluent theme authoring while keeping useThemeState() as the sole modern consumption API.

• Adds FlexThemeReference, structured requested/resolved appearance axes, and stable theme-state/token identity keyed by source revision and resolved appearance.
• Reworks ThemeProvider around a unified external-store source contract. Nested raw legacy themes and source providers resolve through one effective boundary without mutating author-owned theme or token objects.
• Keeps the existing legacy ThemeReference, ThemeProvider, ThemeContext, and useTheme APIs compatible. Legacy-to-Flex conversion is loaded only for modern consumers of legacy sources, while Flex-to-legacy conversion and complete legacy defaults are loaded only when legacy useTheme consumers request them.
• Removes the temporary useFlexTokens API; modern consumers read useThemeState().tokens.
• Adds schema-v2 forward/reverse token mappings, generated reverse projection data, documented omissions and fallbacks, and package export boundaries for legacy-source and compatibility code.
• Migrates default, Android, Apple, Windows, macOS, iOS, and Win32 theme handling to the structured appearance model, including source invalidation and listener lifetime management.
• Adds bundle scenarios that enforce modern paths do not include reverse compatibility code or legacy default token payloads.
• Updates agentic component tests and resolves Button, Badge, and Tag state-name collisions with ThemeState.appearance.

The Win32 adapter now consumes structured native colorScheme and isHighContrast values when available and preserves event-maintained state across subscribers. The current Office native contract has no synchronous current-state getter, so a host change while no consumer is subscribed cannot be recovered until a later event; host-theme string inference remains as a transitional fallback.

Fixes #4264
Addresses #4270

Verification

• yarn build
• yarn lint-repo
• yarn lage lint
• yarn lage test
• yarn workspace @fluentui-react-native/design check:mappings
• yarn check-publishing
• yarn change:check
• Cross-platform theming bundle measurement on macOS, Win32, and Windows

Scenario	macOS	Win32	Windows
Modern Flex theme state	34.08 KB	33.87 KB	34.01 KB
Modern legacy-source theme state	36.18 KB	35.96 KB	36.11 KB
Legacy theme converted from Flex	102.64 KB	102.28 KB	102.38 KB

Before	After
Themes must start as complete legacy Theme objects, and appearance/high-contrast state is represented inconsistently.	Theme authors can supply appearance-aware Flex tokens with stable identity; legacy conversion remains lazy and API-compatible.

Pull request checklist

This PR has considered (when applicable):

• Automated Tests
• Documentation and examples
• Keyboard Accessibility
• Voiceover
• Internationalization and Right-to-left Layouts

[github-actions]

Bundle size report

Tree-shaken production Metro bundles. Component costs are relative to their platform shell; shell costs are absolute.

Platform	Scenario	Baseline cost	Current cost	Cost delta	Change	Gzip delta	Module delta
macos	shell	801.3 KiB	801.3 KiB	0.0 KiB	0.00%	0.0 KiB	+0
macos	components-button	46.4 KiB	50.1 KiB	+3.7 KiB	+7.95%	+1.1 KiB	+4
macos	components-catalog	263.8 KiB	267.3 KiB	+3.5 KiB	+1.34%	+1.2 KiB	+4
macos	design-theme-state	New	33.3 KiB	New	New	New	New
macos	design-theme-state-legacy-source	New	35.3 KiB	New	New	New	New
macos	design-legacy-theme-from-flex	New	100.2 KiB	New	New	New	New
windows	shell	810.2 KiB	810.2 KiB	0.0 KiB	0.00%	0.0 KiB	+0
windows	components-button	46.5 KiB	50.0 KiB	+3.5 KiB	+7.63%	+1.1 KiB	+4
windows	components-catalog	263.6 KiB	267.0 KiB	+3.4 KiB	+1.29%	+1.2 KiB	+4
windows	design-theme-state	New	33.2 KiB	New	New	New	New
windows	design-theme-state-legacy-source	New	35.3 KiB	New	New	New	New
windows	design-legacy-theme-from-flex	New	100.0 KiB	New	New	New	New

The job is advisory: size changes are reported but do not fail the pull request. Bundle or analysis errors still fail.

---

View bundle-size workflow run