Theming: Package Consolidation #4267

Summary

Finish consolidating theming and styling utilities into
@fluentui-react-native/design. Define the owning design submodule for each
moved symbol, reduce legacy packages to thin re-export shims, and publish clear
deprecation guidance so consumers can migrate without maintaining duplicate
public contracts.

Two packages already follow this model; this task completes the migration for
the packages that still own theming logic.

Goal

Make @fluentui-react-native/design the single owner of theming and styling
utilities and defaults, and reduce the remaining theming and token packages to
thin re-export shims over @fluentui-react-native/design or one of its
submodules.

Stage

Stage 1 - Beta foundations.

Why it matters

• Observed. Symbols are currently reachable through more than one package.
  getCurrentAppearance, isHighContrast, and setIsHighContrast are defined
  in packages/agentic/design/src/theming/platformUtils.ts
  and re-exported from
  packages/theming/theming-utils/src/index.ts,
  while theme-tokens and theming-utils still export theming logic of their
  own.
• Inferred. Every later task in this workstream publishes new public surface
  (a Flex context type, generated defaults, a color submodule, appearance
  values). Fixing the submodule boundary first avoids publishing the same
  contract from two package names and then having to deprecate one of them.

Observed current state

• Observed. The design package declares five entry points in
  packages/agentic/design/package.json:
  ., ./tokens/global, ./theming, ./testing, ./styling. Each maps to a
  react-native source condition and a built lib condition.
• Observed. Already shimmed:
  • packages/theming/theme-types/src/index.ts
    states it is a compatibility shim and re-exports types only.
  • packages/framework/theme/src/index.ts
    states it is a compatibility shim and re-exports ThemeProvider and
    ThemeReference.
• Observed. Partially shimmed:
  packages/theming/theming-utils/src/index.ts
  re-exports the appearance helpers from design but still owns
  mapPipelineToTheme
  and mapPipelineToShadow,
  including .ios.ts and .android.ts platform variants.
• Observed. Not shimmed:
  • packages/theming/theme-tokens
    exports globalTokens, getAliasTokens, and getShadowTokens, loading
    whole token JSON files from the @fluentui-react-native/design-tokens-*
    packages at module scope
    (getTokens.ts).
  • packages/utils/tokens exports the token
    style helpers (colorTokens, borderTokens, fontStyles, layoutTokens,
    shadowTokens, tokenBuilder, styleFunction).
  • packages/framework/use-tokens,
    packages/framework/use-styling,
    and packages/framework/themed-stylesheet
    own the legacy token and styling hooks.
• Observed. The design package already hosts the newer styling helpers under
  src/styling
  (branchedStyle, colorStyles, numericStyleValue, gapStyleValue,
  interactiveStatePriority), moved there by
  PR #4183
  so external components can consume them.
• Observed. Dependent counts by package.json reference within packages
  and apps: theme-types 2, theming-utils 6, theme-tokens 7,
  default-theme 9, win32-theme 4, apple-theme 3, android-theme 3.
• Observed. New packages must be added to the root
  tsconfig.json references array to join the
  unified tsc -b build; the design package is already listed there.

Upstream packaging precedent (x3-design/fluent-design at d334acf)

• Observed. Upstream splits the same concerns across two packages:
  @x3-design/flex-tokens@0.9.0 is the data layer (token values and mappings,
  no opinion on application) and @x3-design/flex-themes@0.8.0 is the theme and
  runtime layer that depends on it.
• Observed. Optional capabilities are separate export subpaths rather than
  root-barrel exports: @x3-design/flex-themes declares ./oklch and
  ./contrast entries alongside per-file CSS entries, marks only CSS files as
  having side effects, and its README states the two utility subpaths
  "tree-shake independently (<=4 KB minified each)".
• Inferred. This matches the boundary this task establishes, and it is the
  pattern Runtime Color Utilities should follow
  when publishing the color derivation submodule.

Scope

• Produce a symbol inventory for theme-tokens, theming-utils,
  utils/tokens, and framework/themed-stylesheet, and assign each exported symbol a destination:
  a design submodule, deletion, or intentionally staying put.
• Move the assigned symbols into design submodules, following the existing
  exports map convention and adding new entry points where a symbol should be
  optional rather than part of the root barrel.
• Reduce each source package to explicit named re-exports, matching the comment
  style already used by theme-types and framework/theme.
• Update dependencies in every affected package.json and the references
  arrays in the affected tsconfig.json files.
• Record deprecation guidance for each shimmed package.
• Add changesets for every changed package.

Out of scope

• Changing runtime behavior or token values of any moved symbol.
• Deleting or unpublishing any package.
• Consolidating framework/use-tokens and framework/use-styling
• Rewriting the platform theme packages (default-theme, apple-theme,
  win32-theme, android-theme) onto the Flex contract; those are theme
  construction changes owned by
  Dynamic Theme Building and
  Apple Theme.
• Introducing the Flex-value context type, generated defaults, appearance model
  changes, or color derivation.

Deliverables

1. A symbol inventory and destination map, checked in under the design package
   or in this workstream, covering every export of the six packages listed in
   Scope.
2. Design submodule placement for the moved symbols, with exports entries in
   packages/agentic/design/package.json.
3. Shimmed source packages using explicit named re-exports and no local logic
   beyond what the inventory marks as intentionally staying.
4. Updated manifests, tsconfig.json references, and changesets.
5. Deprecation notes for each shimmed package.

Acceptance criteria

• Every symbol in the inventory has exactly one definition site in the
  repository, and any other package exporting it does so by re-export.
• No shimmed package contains theming or styling logic that the inventory
  did not explicitly mark as staying.
• All re-exports are explicit named re-exports; no export * from is
  introduced, per the repository export rule in AGENTS.md.
• Design submodules that exist only for optional capabilities are reachable
  through their own exports entry and are not re-exported from the root
  barrel.
• yarn build succeeds at the repository root.
• yarn lage test and yarn lage lint pass at the repository root.
• yarn depcheck reports no unused dependency in the shimmed packages.
• A changeset exists for each changed package and no changeset requests a
  major version.

Dependencies and ordering

• No prerequisite tasks; this is the first task in Stage A of the
  workstream roadmap.
• Blocks Runtime Color Utilities, which needs
  the optional-submodule pattern established here.
• Should land before Default Values Codegen so
  generated files are emitted into their final submodule location.
• Interacts with Dynamic Theme Building: if that
  task lands first, the legacy Fluent token path must be shimmed rather than
  moved.

Risks and open decisions

• Open decision. Whether the legacy token and styling hooks
  (use-tokens, use-styling, themed-stylesheet, utils/tokens) move into
  design at all, or stay in place and are marked legacy. Inferred: moving
  them enlarges the design package's public surface for code that the agentic
  components do not use, since those components consume useThemeState and the
  styling submodule instead.
• Open decision. Whether theme-tokens should be shimmed as-is or replaced
  by generated constants. Observed: its module-scope JSON imports are the
  same values that Default Values Codegen plans to
  generate, so shimming it unchanged may preserve a bundle-size problem.
• Risk. The design package's only runtime dependency today is
  @fluentui-react-native/framework-base. Moving symbols that depend on
  react-native-windows, react-native-macos, or assert-never could add
  runtime dependencies or pull platform React Native forks into one type graph,
  which AGENTS.md prohibits. Platform-specific code must
  stay in .macos.ts, .win32.ts, and .windows.ts files.
• Risk. Shims that re-export types plus values across package boundaries can
  change declaration emit under project references; the root build is the gate.

Evidence and references

• packages/agentic/design/package.json: current entry points and dependency set.
• packages/theming/theme-types/src/index.ts: reference shim implementation.
• packages/framework/theme/src/index.ts: reference shim implementation.
• packages/theming/theming-utils/src/index.ts: partial shim.
• packages/theming/theme-tokens/src/index.ts, getTokens.ts: unmigrated token loading.
• packages/utils/tokens/src/index.ts: legacy token style helpers.
• packages/agentic/design/src/styling: the styling submodule that moved symbols should follow.
• AGENTS.md: export, build, and validation rules.
• microsoft/fluentui-react-native@d2690c9: PR Consolidate theming logic into the new design package #4143, first consolidation wave.
• microsoft/fluentui-react-native@80bf14d: PR Consolidate getCurrentAppearance, isHighContrast and setHighContrast in design package #4155, appearance helper consolidation.
• microsoft/fluentui-react-native@1157793: PR Move styling utilities to design package #4183, styling utilities moved into design.
• x3 dev/web/flex-themes/package.json: subpath exports map and sideEffects scoping.