diff --git a/docs/react-v9/contributing/rfcs/react-components/convergence/cap-theme-in-fluent-v9.md b/docs/react-v9/contributing/rfcs/react-components/convergence/cap-theme-in-fluent-v9.md new file mode 100644 index 00000000000000..34d6cb10533357 --- /dev/null +++ b/docs/react-v9/contributing/rfcs/react-components/convergence/cap-theme-in-fluent-v9.md @@ -0,0 +1,198 @@ +# RFC: Bring the CAP visual language into Fluent UI v9 + +--- + +_Contributors: (author: Enrico Gianoglio)_ + +> **Status — request for engineering review.** This RFC proposes graduating the **CAP visual language** — currently shipped as `@fluentui-contrib/react-cap-theme` — into the Fluent v9 monorepo as a new in-repo package, `@fluentui/react-cap-theme`. The remaining decision is how consumers import `CAP_STYLE_HOOKS` (see [Distribution shape](#distribution-shape--considered-alternatives) — three candidates: separate preview package, separate stable package, or suite subpath). A prototype validated the docs-site toggle UX end-to-end and measured the bundle-size impact of an earlier suite-barrel re-export shape (see [Bundle-size analysis](#bundle-size-analysis)). + +## Summary + +Make the **CAP visual language** a first-class part of Fluent UI v9 so that: + +1. A consumer of Fluent v9 can opt in to CAP **without installing any separate package** (no `@fluentui-contrib/*` dependency). +2. All future CAP work happens inside the Fluent v9 repo, on the Fluent release cadence, with the same CI guarantees (bundle size, conformance, VR, a11y) as the rest of v9. +3. CAP is discoverable and try-able directly on https://react.fluentui.dev/ — as a **visual-language toggle** that overlays the currently-selected base theme (web / teams / high-contrast / light / dark), _not_ as additional entries in the theme dropdown. + +The change is small because the consumer-facing primitive already exists: `FluentProvider` accepts a `customStyleHooks_unstable` prop today and CAP is just a value to pass to it. We propose shipping that value (`CAP_STYLE_HOOKS`) from `@fluentui/react-components`, wiring it into the docs site as a toggle, and moving the source into the Fluent v9 monorepo. + +## Why — motivation and benefits + +### The problem in one sentence + +> "We should try to get off this island of working in FluentUI Contrib so that the CAP theme becomes synonymous with Fluent and not a separate entity." + +### Concrete pain caused by the current arrangement + +CAP today exists as `@fluentui-contrib/react-cap-theme`. Starting CAP in `fluentui-contrib` made sense at the time: it let the visual language be prototyped and iterated on quickly, outside Fluent's release cadence and CI surface, without committing the Fluent v9 team to ownership before the shape of CAP had settled. CAP is not "done" yet — the API surface is still evolving — but it has reached a point where its overall shape and its consumer story (Teams) are taking form. The costs of keeping it in contrib now actively work against adoption. + +- **Discovery.** CAP is technically documented on `react.fluentui.dev`, but only under the `Contributors Packages` section — it's not surfaced in the suite's README, in the API docs, or anywhere in the main browsing flow. A team evaluating Fluent for a new product is unlikely to find CAP unless someone tells them where to look. +- **Install friction.** Adopting CAP requires adding a `@fluentui-contrib/*` line to `package.json`. For internal Microsoft consumers this is read as "third-party / experimental" by reviewers and security audits, even though the underlying code overrides Fluent components themselves. +- **Surfacing CAP's needs from Fluent.** CAP can only override what Fluent components already expose. When a CAP override needs an additional slot, a richer state field, or a render-prop hook that doesn't exist yet, that's a Fluent change — it has to land in `@fluentui/react-components` first, and CAP catches up afterwards. Today, with CAP in a separate repo, that gap is harder to spot, harder to discuss with the component owner, and harder to land in lockstep. With CAP in the Fluent monorepo, the missing API, the component, and the override hook all sit next to each other and can be addressed in a single PR reviewed by the same owners. +- **Ecosystem signal.** As long as CAP lives in `fluentui-contrib`, the implicit message is "CAP is one of many community experiments." + +### Benefits of bringing CAP into v9 + +- **Zero-install adoption.** `import { CAP_STYLE_HOOKS } from '@fluentui/react-components'` — no new package, no `package.json` change beyond what teams already have. +- **One source of truth.** CAP overrides live next to the components they override. PRs touching, e.g., `