chore(docs): ThemeProvider API documentation

docs/src/data/links.tsx

@@ -523,6 +523,11 @@ export const theming: ComponentNavItem[] = [
     platforms: ['react', 'vue', 'angular'],
     tertiary: true,
   },
+  {
+    href: '/theming/theme-provider',
+    label: 'ThemeProvider',
+    platforms: ['react'],
+  },
   {
     href: '/theming/dark-mode',
     label: 'Dark mode',

docs/src/pages/[platform]/theming/theme-provider/examples/BasicExample.tsx

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { Card, Text } from '@aws-amplify/ui-react';
+
+export const BasicExample = () => (
+  // Example using component variations
+  <Card variation="outlined">
+    {/* Example using color tokens */}
+    <Text color="purple.80">Themed purple text</Text>
+  </Card>
+);

docs/src/pages/[platform]/theming/theme-provider/examples/index.ts

@@ -0,0 +1 @@
+export { BasicExample } from './BasicExample';

docs/src/pages/[platform]/theming/theme-provider/index.page.mdx

@@ -0,0 +1,21 @@
+---
+title: ThemeProvider
+description: The ThemeProvider allows you to apply a Theme to your application.
+supportedFrameworks: react
+---
+
+import { Fragment } from '@/components/Fragment';
+import { FRAMEWORKS } from '@/data/frameworks';
+import { getCustomStaticPath } from "@/utils/getCustomStaticPath";
+
+export async function getStaticPaths() {
+  return getCustomStaticPath(frontmatter.supportedFrameworks);
+}
+
+{/*  `getStaticProps` is required to prevent "Error: getStaticPaths was added without a getStaticProps. Without getStaticProps, getStaticPaths does nothing" */}
+
+export async function getStaticProps() {
+  return { props: {} }
+}
+
+<Fragment>{({ platform }) => import(`./${platform}.mdx`)}</Fragment>

docs/src/pages/[platform]/theming/theme-provider/react.mdx

@@ -0,0 +1,75 @@
+import { Example, ExampleCode } from '@/components/Example';
+
+import { BasicExample } from './examples';
+
+## Usage
+
+Import the `ThemeProvider` and wrap your application with it:
+
+```jsx
+import { ThemeProvider } from '@aws-amplify/ui-react';
+
+export const App = (
+  <ThemeProvider>
+    <YourApplication />
+  </ThemeProvider>
+);
+```
+
+Use the [default theme](./default-theme) to style the components in your app:
+
+<Example>
+  <BasicExample />
+
+  <ExampleCode>
+    ```tsx file=./examples/BasicExample.tsx
+    ```
+
+  </ExampleCode>
+</Example>
+
+### theme
+
+To create and use your own custom theme, you may pass a [theme object](https://ui.docs.amplify.aws/react/theming#theme-object) to the `theme` prop on the `ThemeProvider`. 
+
+- [Theming overview](./theming)
+- [Demonstration](./default-theme/colors) of how to use the `theme` prop
+
+### colorMode
+
+The `ThemeProvider` accepts a `colorMode` prop which can be `light`, `dark`, or `system`.
+
+See the [Dark mode documentation](./dark-mode) for a detailed explanation of how to use the `colorMode` prop. 
+
+### nonce
+
+When you have a `Content-Security-Policy` ([CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)) header defined, the browser will automatically block inline styles. 
+
+To safely allow inline styles when using strict CSP rules, you may pass a [nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) to the `nonce` prop on the `ThemeProvider`. This will add a nonce to the `<style>` tag rendered by the `ThemeProvider`. For example:
+
+**CSP rules**
+```
+style-src css-cdn.example.com 'nonce-rAnd0m';
+```
+
+**ThemeProvider**
+```jsx
+<ThemeProvider nonce="rAnd0m">
+  {/* your app */}
+</ThemeProvider>
+```
+
+**HTML output**
+```html
+<style nonce="rAnd0m">
+  :root, [data-amplify-theme] {
+    --amplify-colors-white: hsl(0, 0%, 100%);
+    /* etc */
+  }
+  /* 
+   * Any of your custom theme styles
+   */
+</style>
+```
+
+For more information, see the following documention on [allowing inline styles using a nonce](https://content-security-policy.com/examples/allow-inline-style).