chore(docs): ThemeProvider API documentation (#2711)

* add new docs page for ThemeProvider API

* rename ThemeProvider API to ThemeProvider

* document nonce prop for ThemeProvider

* include basic ThemeProvider example

* update theming example

* update custom theme example

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

Co-authored-by: Danny Banks <djb@amazon.com>

* remove useTheme hook from custom theme example

Co-authored-by: Joe Buono <joebuono@amazon.com>
Co-authored-by: Danny Banks <djb@amazon.com>

docs/src/data/links.tsx

@@ -540,6 +540,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/default-theme/colors/examples/ColorsExample.tsx

@@ -1,32 +1,26 @@
-import {
-  ThemeProvider,
-  Card,
-  Heading,
-  Text,
-  useTheme,
-} from '@aws-amplify/ui-react';
+import { Card, Heading, Text, ThemeProvider } from '@aws-amplify/ui-react';
 
-export const ColorsExample = () => {
-  const { tokens } = useTheme();
-  const theme = {
-    name: 'custom-theme',
-    tokens: {
-      components: {
-        card: {
-          backgroundColor: tokens.colors.background.secondary,
-          outlined: {
-            borderColor: tokens.colors.black,
-          },
-        },
-        text: {
-          color: tokens.colors.neutral[80],
-        },
-        heading: {
-          color: tokens.colors.brand.secondary[80],
+const theme = {
+  name: 'custom-theme',
+  tokens: {
+    components: {
+      card: {
+        backgroundColor: { value: '{colors.background.secondary}' },
+        outlined: {
+          borderColor: { value: '{colors.black}' },
         },
       },
+      heading: {
+        color: { value: '{colors.brand.secondary[80]}' },
+      },
+      text: {
+        color: { value: '{colors.brand.primary[80]}' },
+      },
     },
-  };
+  },
+};
+
+export const ColorsExample = () => {
   return (
     <ThemeProvider theme={theme}>
       <Card variation="outlined">

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

@@ -0,0 +1,11 @@
+import { Button, useTheme } from '@aws-amplify/ui-react';
+
+export const BasicExample = () => {
+  const { tokens } = useTheme();
+
+  return (
+    <Button border={`2px solid ${tokens.colors.blue[80]}`} color="purple.80">
+      Themed Button
+    </Button>
+  );
+};

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

@@ -0,0 +1,32 @@
+import { Card, Heading, Text, ThemeProvider } from '@aws-amplify/ui-react';
+
+const theme = {
+  name: 'custom-theme',
+  tokens: {
+    components: {
+      card: {
+        backgroundColor: { value: '{colors.background.secondary}' },
+        outlined: {
+          borderColor: { value: '{colors.black}' },
+        },
+      },
+      heading: {
+        color: { value: '{colors.brand.secondary[80]}' },
+      },
+      text: {
+        color: { value: '{colors.brand.primary[80]}' },
+      },
+    },
+  },
+};
+
+export const CustomThemeExample = () => {
+  return (
+    <ThemeProvider theme={theme}>
+      <Card variation="outlined">
+        <Heading level={6}>Heading text</Heading>
+        <Text>Some sample text for this card.</Text>
+      </Card>
+    </ThemeProvider>
+  );
+};

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

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

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,89 @@
+import { Flex } from '@aws-amplify/ui-react';
+import { Example, ExampleCode } from '@/components/Example';
+
+import { BasicExample, CustomThemeExample } 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>
+);
+```
+
+After wrapping your application in the `ThemeProvider`, you have access to all theme values in your components. To style the components in your app, you can either:
+1. Get the theme `tokens` through the `useTheme` hook (e.g., `tokens.colors.blue[80]`)
+2. Reference the theme `tokens` directly in style props (e.g., `"purple.80"`)
+
+<Example>
+  <Flex>
+    <BasicExample />
+  </Flex>
+
+  <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)
+
+<Example>
+  <CustomThemeExample />
+
+  <ExampleCode>
+    ```tsx file=./examples/CustomThemeExample.tsx
+    ```
+
+  </ExampleCode>
+</Example>
+
+### 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).