adobe · yihuiliao · Nov 4, 2025 · Nov 3, 2025 · Nov 4, 2025 · Nov 4, 2025
diff --git a/packages/@react-spectrum/s2/src/Provider.tsx b/packages/@react-spectrum/s2/src/Provider.tsx
@@ -51,6 +51,10 @@ export interface ProviderProps extends UnsafeStyles {
 
 export const ColorSchemeContext = createContext<ColorScheme | 'light dark' | null>(null);
 
+/**
+ * Provider is the container for all React Spectrum components.
+ * It loads the font and sets the colorScheme, locale, and other application level settings.
+ */
 export function Provider(props: ProviderProps): JSX.Element {
   let result = <ProviderInner {...props} />;
   let parentColorScheme = useContext(ColorSchemeContext);

diff --git a/packages/dev/s2-docs/pages/s2/Provider.mdx b/packages/dev/s2-docs/pages/s2/Provider.mdx
@@ -0,0 +1,92 @@
+import {Layout} from '../../src/Layout';
+import {InstallCommand} from '../../src/InstallCommand';
+import {BundlerSwitcher, BundlerSwitcherItem} from '../../src/BundlerSwitcher';
+export default Layout;
+import {SegmentedControl, SegmentedControlItem} from '@react-spectrum/s2';
+
+export const section = 'Getting started';
+export const description = 'Getting started with React Spectrum';
+import docs from 'docs:@react-spectrum/s2';
+
+# Provider
+
+<PageDescription>{docs.exports.Provider.description}</PageDescription>
+
+## Example
+
+```tsx render
+'use client';
+import {Provider} from '@react-spectrum/s2';
+import {Button} from '@react-spectrum/s2';
+
+function App() {
+  return (
+    <Provider background='base'>
+      <Button variant="accent">
+        Hello React Spectrum!
+      </Button>
+    </Provider>
+  );
+}
+```
+
+## Color Schemes
+By default, React Spectrum follows the operating system color scheme setting, supporting both light and dark mode. The colorScheme prop can be set on `<Provider>` to force the app to always render in a certain color scheme.
+
+```tsx render
+'use client';
+import {Provider} from '@react-spectrum/s2';
+import {ActionButton} from '@react-spectrum/s2';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<div className={style({display: 'flex', gap: 12})}>
+  <Provider colorScheme="light">
+    <div className={style({backgroundColor: 'base', padding: 12})}>
+      <ActionButton>I'm a light button</ActionButton>
+    </div>
+  </Provider>
+  <Provider colorScheme="dark">
+    <div className={style({backgroundColor: 'elevated', padding: 12})}>
+      <ActionButton>I'm a dark button</ActionButton>
+    </div>
+  </Provider>
+</div>
+```
+
+## Locales
+By default, React Spectrum chooses the locale matching the user’s browser/operating system language, but this can be overridden with the locale prop if you have an application specific setting. This prop accepts a [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code. A list of supported locales is available [here](Concepts.html#supported-locales)
+
+```tsx
+<Provider locale="en-US">
+  <YourApp />
+</Provider>
+```
+
+{/* ### Breakpoints */}
+{/* TODO: Link to style macro docs about breakpoints */}
+
+## Client side routing
+
+The Provider component accepts an optional `router` prop. This enables React Spectrum components that render links to perform client side navigation using your application or framework's client side router. See the client side routing guide for details on how to set this up.
+
+```tsx
+let navigate = useNavigateFromYourRouter();
+
+<Provider router={{navigate}}>
+  <YourApp />
+</Provider>
+```
+
+## Server side rendering 
+
+When using SSR, the `<Provider>` component can be rendered as the root `<html>` element. The `locale` prop should always be specified to avoid hydration errors.
+
+```tsx
+<Provider elementType="html" locale="en-US">
+  <YourApp />
+</Provider>
+```
+
+## Props
+
+<PropTable component={docs.exports.Provider} links={docs.links} />