Theming: Apple Theme

Summary

Build a Flex-contract Apple theme from the
Office macOS design specification
so agentic components receive the intended macOS look and feel through
ThemeState. Map specification values to Flex tokens, preserve system-driven
colors and materials where platform behavior requires them, and define the
migration path for the existing legacy Apple theme.

The current package produces a legacy Fluent Theme from macOS system colors;
it does not provide a specification-backed Flex theme.

Goal

Create an Apple theme that delivers the macOS look and feel specified by the
linked Office macOS design file, built on the Flex token contract so
agentic components pick it up through ThemeState.

Stage

Stage 3 - Production fidelity.

Why it matters

• Observed. Agentic components resolve styling through useThemeState
  (18 files under packages/agentic/components/src/components),
  which reads Flex tokens. The existing Apple theme produces a Fluent Theme,
  so its values only reach those components through the generic
  flexTokensFromTheme projection.
• Observed. That projection is not macOS-specific. It is driven by
  flex-from-theme.json,
  and flex-token-map.yaml records that its Fluent source is
  @fluentui-react-native/design-tokens-win32/colorful; it also notes that
  material background tokens fall back to white-alpha values where platform
  acrylic or vibrancy (NSVisualEffectView) would be preferred.
• Observed. The existing Apple theme hard-codes component metrics that
  predate the Flex contract: appleComponents in
  appleTheme.macos.ts
  sets Button borderRadius: 6, minHeight: 28, minWidth: 72, and paddings,
  commented as the FluentUI Apple "Large" button size values.

Observed current state

• Observed. packages/theming/apple-theme
  contains separate iOS and macOS implementations
  (appleTheme.ios.ts/appleTheme.macos.ts,
  appleColors.ios.ts/appleColors.macos.ts,
  appleShadows.*, appleTypography.*, createMacOSAliasTokens.ts,
  createiOSAliasTokens.ts, getMacOSTokens.ts), plus a snapshot test at
  src/__tests__/apple-theme.test.ts.
• Observed. macOS colors come from system colors, not from a design
  specification: appleColors.macos.ts
  builds its palette from PlatformColor, DynamicColorMacOS, and
  ColorWithSystemEffectMacOS imported from react-native-macos.
• Observed. createAppleTheme.macos.ts
  wraps the theme in a ThemeReference whose recipe calls
  getCurrentAppearance(Appearance.getColorScheme(), 'light'), invalidates on
  Appearance.addChangeListener, and invalidates on the macOS
  highContrastChanged accessibility event while calling setIsHighContrast.
• Observed. setIsHighContrast on macOS writes a module-level mutable flag
  (platformUtils.macos.ts),
  which useThemeState reads when constructing ThemeState.highContrast
  (useThemeState.ts).
• Observed. The design package's Jest platform is macOS
  ("furn": { "jestPlatform": "macos" } in
  package.json), so macOS
  resolution is already exercised by the design package's tests.
• Observed. The macOS design token package ships light, dark, hclight,
  and hcdark variants, but the design codegen consumes only macos/light
  (codegen.cts).
• Observed. Upstream provides no Apple input. At
  d334acf5cbad813f2b7cd554da942b09a7ff8f10, dev/web/flex-themes contains only
  web CSS, a JavaScript theme factory, and OKLCH and contrast utilities; it has
  no macOS, iOS, or React Native artifacts and no high-contrast theme. The
  Fluent token packages and the Figma specification are the sources for Apple
  values.

Scope

• Review the Office macOS specification and record what it defines:
  color, typography, spacing, radius, stroke, elevation, and any component
  metrics.
• Map the specification onto the Flex token contract, extending
  flex-token-map.yaml with an Apple or macOS source column so provenance is
  recorded the same way as the generic and Fluent sources.
• Author the Apple theme against the Flex contract so agentic components consume
  it through useThemeState.
• Define how specification values combine with macOS system colors and materials
  (PlatformColor, DynamicColorMacOS, vibrancy), including which tokens must
  remain system-driven for accessibility and appearance correctness.
• Cover light, dark, and high-contrast appearances on macOS.
• Decide and document the relationship to the existing apple-theme package:
  replacement, shim, or parallel legacy path.
• Validate in the Storybook app on macOS.

Out of scope

• iOS look and feel. This task is macOS-specific; the existing iOS
  implementation stays as it is unless the scope is extended.
• Inventing values that are not defined by the specification or a documented
  macOS system behavior.
• Changing the appearance resolution model itself; see
  System Appearance Handling.
• Adding color derivation; see
  Runtime Color Utilities.

Deliverables

1. A design-to-token mapping record for the Office macOS specification,
   including which values it authoritatively defines.
2. An Apple or macOS source mapping recorded in
   flex-token-map.yaml
   or an equivalent checked-in mapping file.
3. A Flex-contract Apple theme covering light, dark, and high contrast.
4. A documented decision and migration note for the existing
   @fluentui-react-native/apple-theme package.
5. Tests: resolved Flex token snapshots per appearance, plus the system-color
   and material behavior that must remain platform-driven.
6. Storybook validation on macOS.
7. Changesets.

Acceptance criteria

• The specification sections and values used by the implementation are
  recorded in the repository; no value is invented or approximated.
• Every Apple theme token value traces to the specification, to a macOS
  system color, or to an explicitly recorded fallback.
• Agentic components render with the Apple theme through useThemeState
  without component-level changes.
• Light, dark, and high-contrast appearances are covered and change with the
  system appearance, preserving the existing Appearance and
  highContrastChanged invalidation behavior.
• Tokens that must remain system-driven are documented and verified not to
  be replaced by static values.
• The relationship to the existing apple-theme package is decided,
  documented, and implemented.
• The theme is exercised in the Storybook app on macOS.
• yarn build, yarn lage test, and yarn lage lint pass at the
  repository root, and changesets are present.

Dependencies and ordering

• Depends on Dynamic Theme Building for the
  Flex-authoring model this theme is written in.
• Depends on Default Values Codegen for the
  generated per-appearance value sets it layers over.
• Depends on System Appearance Handling for resolved
  scheme and high-contrast values on macOS.
• Benefits from Runtime Color Utilities where the
  specification supplies rest values without interaction states.
• Review the linked design specification before implementation begins.

Risks and open decisions

• Open decision. Whether the new Apple theme replaces
  @fluentui-react-native/apple-theme, is added alongside it, or the existing
  package becomes a shim. Observed: three packages reference apple-theme
  in their manifests, and it has a committed snapshot test.
• Open decision. Which tokens must stay as macOS system colors rather than
  specification constants. Observed: the current implementation is built
  almost entirely from PlatformColor and DynamicColorMacOS, so replacing
  them with static values would change accessibility and appearance behavior.
• Open decision. Whether macOS materials (vibrancy) are represented as Flex
  material tokens or handled at the component layer. Observed:
  flex-token-map.yaml records that material tokens currently fall back to
  white-alpha colors and notes NSVisualEffectView as preferred where available.
• Risk. AGENTS.md prohibits pulling more than one
  React Native fork into a single program's type graph, so react-native-macos
  imports must stay in .macos.ts files.

Evidence and references

• packages/theming/apple-theme: existing Apple theme package.
• packages/theming/apple-theme/src/createAppleTheme.macos.ts: appearance and high-contrast wiring.
• packages/theming/apple-theme/src/appleColors.macos.ts: system color palette construction.
• packages/theming/apple-theme/src/appleTheme.macos.ts: hard-coded component metrics.
• packages/agentic/design/src/useThemeState.ts: the consumption path agentic components use.
• packages/agentic/design/src/tokens/mappings/flex-token-map.yaml: mapping provenance format and the material fallback note.
• packages/agentic/design/scripts/codegen.cts: macOS token variant currently consumed.
• apps/storybook/src/StorybookTheme.tsx: where the theme would be exercised.
• Office macOS Figma file: source for the macOS look and feel.
• x3 dev/web/flex-themes/README.md: confirms the upstream Flex layer is web CSS only.

Start by reviewing the Office macOS Figma specification, the Flex token contract in flex-token-map.yaml, and the macOS variant handling in codegen.cts. Trace consumption through useThemeState.ts and compare the existing apple-theme files, especially createAppleTheme.macos.ts and appleColors.macos.ts. Done means a documented, tested Flex Apple theme covering light, dark, and high contrast, with migration guidance and Storybook validation.