Theming: Theming Documentation Refresh

[JasonVMo]

Summary

Update three surfaces so that a developer reading any of them gets an accurate
picture of the consolidated theming contract: redirect packages/theming/README.md
away from the shim packages it still presents as entry points, create a missing
packages/agentic/design/README.md that describes the package's five entry points
and both authoring models, and revise the pages under docs/pages/Theming so that
import examples and usage descriptions match the current API rather than the legacy
Fluent Theme shape.

This task has no implementation work of its own. It is a clean-up pass that
becomes feasible once Package Consolidation fixes the submodule boundary and
Dynamic Theme Building defines the Flex-value authoring model, so examples
written here will not become stale before they are merged.

Goal

Make packages/theming/README.md, the new packages/agentic/design/README.md,
and the pages under docs/pages/Theming consistent with the post-consolidation
public contract. No surface should name a compatibility shim as a primary entry
point or describe only the legacy Fluent Theme authoring model as the way to
use theming in new code.

Stage

Stages 2 and 3. packages/theming/README.md and packages/agentic/design/README.md
can be written as soon as Stage 1 lands. The docs/pages/Theming pages that
describe appearance resolution and Flex-first authoring are complete only after
System Appearance Handling and Default Values Codegen stabilize the full API.

Why it matters

• Observed. packages/theming/README.md lists theme-types and
  theme-tokens as the theming entry points under a "Theme types and utilities"
  heading. Both are compatibility shims. theme-types is a re-export shim over
  @fluentui-react-native/design/theming, and theme-tokens loads whole token
  JSON files at module scope and has not been migrated. Directing readers to
  either package as a starting point describes a contract that is either
  transitional or has already moved.
• Observed. packages/agentic/design has no README.md. A contributor or
  consumer arriving at the canonical theming package via GitHub or a package
  registry finds no orientation material, no description of its five entry
  points, and no links to developer documentation.
• Observed. docs/pages/Theming/Basics.md presents useFluentTheme() from
  @fluentui-react-native/framework as the primary way to read theme values
  inside a component. That hook reads the legacy Fluent Theme shape; there is
  no mention of useThemeState, useFlexTokens, or the
  @fluentui-react-native/design hooks.
• Observed. docs/pages/Theming/CustomTheme.md describes ThemeRecipes and
  PartialTheme exclusively against the legacy Fluent token shape
  (theme.colors, theme.typography, theme.spacing). Flex tokens are not
  mentioned. One example uses _overrides syntax from the older foundation
  framework.
• Inferred. Docs that describe only the legacy contract will slow adoption of
  the Flex-first path defined by Dynamic Theme Building, and may cause new
  contributors to write components and tests against legacy hooks rather than
  ThemeState.

Observed current state

• Observed. packages/theming/README.md is 14 lines. Its only links are to
  default-theme, apple-theme, win32-theme, android-theme, theme-types,
  and theme-tokens subpackage READMEs. There is no mention of
  @fluentui-react-native/design, ThemeProvider, or ThemeReference, and no
  description of the consolidation that has already taken place.
• Observed. packages/agentic/design has no README.md file. Its five
  entry points (., ./tokens/global, ./theming, ./testing, ./styling)
  are described only in its package.json exports map and in the
  research/theming/README.md workstream document.
• Observed. docs/pages/Theming/Basics.md imports ThemeProvider from
  @fluentui-react-native/design/theming (already updated) but then imports
  useFluentTheme from @fluentui-react-native/framework for property access,
  and shows theme.colors.bodyText as the canonical pattern. The design package
  hooks (useThemeState, useFlexTokens) are not referenced.
• Observed. docs/pages/Theming/CustomTheme.md describes ThemeReference
  construction and ThemeRecipes against the legacy Fluent Theme shape only.
  Code examples access theme.colors, theme.host.palette, theme.typography,
  and theme.spacing. Flex token access and the Flex-value context type are
  absent. One code block demonstrates the _overrides shape from the older
  foundation framework.
• Observed. docs/pages/Theming/DefaultThemes.md lists createDefaultTheme(),
  createAndroidTheme(), createAppleTheme(), and createOfficeTheme() as the
  complete creation API. There is no description of a Flex-first creation path.
• Observed. Several pages under docs/pages/Theming/ already link to source
  files under packages/agentic/design/src via relative paths, confirming a
  partial update pass was done, but the consumer-facing API descriptions and
  import examples were not updated at the same time.
• Observed. Three pages under docs/pages/Theming/Tokens/ cover global token
  overrides and component token usage using the legacy framework composition
  model.

Scope

• Update packages/theming/README.md to name @fluentui-react-native/design as
  the theming entry point, describe each subpackage's current role (platform
  theme or compatibility shim), and remove the "Theme types and utilities"
  framing that elevates the two shim packages.
• Create packages/agentic/design/README.md describing the five entry points
  and their intended use cases, the two authoring models (Flex token and legacy
  Fluent), the relationship between ThemeProvider and ThemeState, and links
  to docs/pages/Theming.
• Update docs/pages/Theming/Basics.md to cover both the Flex token path
  (useThemeState, useFlexTokens) and the legacy Fluent hook path, with clear
  guidance that new code should prefer the design package hooks.
• Update docs/pages/Theming/CustomTheme.md to describe Flex-first
  customization alongside the existing ThemeRecipes content. Remove or
  annotate the _overrides example as a legacy-only pattern.
• Update docs/pages/Theming/DefaultThemes.md to reflect the current entry
  point and describe the Flex-first creation path alongside the existing platform
  functions.
• Correct any remaining import paths, package names, or API references under
  docs/pages/Theming/ that no longer match the consolidated contract.

Out of scope

• Changing any runtime behavior or token values.
• Writing new tutorials or end-to-end migration guides for consumers moving off
  legacy framework components.
• Updating reference documentation for packages/framework/use-tokens,
  use-styling, or themed-stylesheet beyond annotating them as legacy paths.
• Documentation work that requires runtime color derivation or the Apple theme
  to be accurate; those updates follow
  Runtime Color Utilities and
  Apple Theme.
• Adding API reference pages or auto-generated documentation.

Deliverables

1. An updated packages/theming/README.md that describes each subpackage's
   current role and redirects readers to @fluentui-react-native/design.
2. A new packages/agentic/design/README.md covering the five entry points,
   both authoring models, and links to docs/pages/Theming.
3. Updated docs/pages/Theming/Basics.md, CustomTheme.md, and
   DefaultThemes.md with correct import paths and usage examples for both
   authoring models.
4. Corrections to any other pages under docs/pages/Theming/ where package
   names, import paths, or API descriptions no longer match the consolidated
   contract.
5. Changesets for packages/theming and packages/agentic/design if their
   published documentation content changes.

Acceptance criteria

• packages/theming/README.md names @fluentui-react-native/design as the
  theming entry point and describes each subpackage's current role without
  presenting any compatibility shim as a primary consumer entry point.
• packages/agentic/design/README.md exists and lists all five entry points
  with their import path, describes the Flex token and legacy Fluent
  authoring models, and links to the developer documentation pages.
• No page under docs/pages/Theming/ still names theme-types or
  theme-tokens as a primary entry point.
• docs/pages/Theming/Basics.md includes a working example using the design
  package hooks alongside the legacy useFluentTheme example, with the
  legacy path clearly marked.
• All source links in the updated documentation use absolute
  https://github.com/microsoft/fluentui-react-native/blob/main/ or
  tree/main URLs rather than relative source paths.
• yarn lage test-links passes at the repository root after all changes,
  confirming no broken links were introduced.
• Changesets are present for packages/theming and packages/agentic/design
  if their published documentation content changed, and no changeset requests
  a major version.

Dependencies and ordering

• Requires Package Consolidation so that
  documentation can describe the final submodule boundary rather than a
  transitional state.
• Requires Dynamic Theme Building so that
  Flex-first authoring examples are accurate and the Flex-value context type is
  stable.
• The sections of docs/pages/Theming covering appearance resolution depend on
  System Appearance Handling; those updates land in
  Stage 3.
• docs/pages/Theming/DefaultThemes.md should not describe generated default
  construction until Default Values Codegen has
  stabilized the creation API.
• Does not block any other task in this workstream.

Risks and open decisions

• Open decision. Whether packages/agentic/design/README.md contains full
  prose or is a brief orientation page that delegates to docs/pages/Theming.
  A short README with links is lower maintenance than a comprehensive README
  that can drift from the docs site.
• Open decision. Whether the primary getting-started example in
  docs/pages/Theming/Basics.md should show the Flex token path or the legacy
  ThemeReference recipe after Dynamic Theme Building lands. Inferred: new
  code should prefer the Flex path, but the legacy path must remain documented
  for existing component consumers.
• Risk. If Package Consolidation or Dynamic Theme Building introduce
  additional API changes after this documentation lands, the docs will drift
  again. Tying the final docs/ update to the stabilizing commit in each
  dependency reduces this risk.
• Risk. docs/pages/Theming/CustomTheme.md contains _overrides examples
  from the older foundation framework. Determining whether that pattern is still
  supported requires cross-checking with the current composition package before
  those examples are updated or removed.

Evidence and references

• packages/theming/README.md: 14-line file presenting theme-types and theme-tokens as the entry points.
• packages/agentic/design: canonical theming package; no README.md present.
• packages/agentic/design/package.json: the five declared entry points.
• packages/theming/theme-types/src/index.ts: compatibility shim; still advertised as an entry point by packages/theming/README.md.
• packages/theming/theme-tokens/src/index.ts: unmigrated token loading; still advertised as an entry point by packages/theming/README.md.
• docs/pages/Theming/Basics.md: useFluentTheme from @fluentui-react-native/framework as the primary hook example.
• docs/pages/Theming/CustomTheme.md: ThemeRecipes and PartialTheme against the legacy Fluent Theme shape only; contains _overrides example.
• docs/pages/Theming/DefaultThemes.md: legacy creation functions only; no Flex-first path.
• docs/pages/Theming/ThemedStylesheet.md: legacy ThemedStyleSheet API.
• docs/pages/Theming/Tokens/: token override and component token usage pages using the legacy framework model.
• Package Consolidation: defines the final submodule boundary this documentation describes.
• Dynamic Theme Building: defines the Flex-value context type and authoring model to be documented.