docs(update): Usage page (#2009)

* basic usage example

* examples for theming and components

* adjusting description

* change links to relative paths

Co-authored-by: Joe Buono <[email protected]>

Author: joebuono

docs/src/pages/[platform]/getting-started/usage/examples/ComponentExampleCode.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { Button } from '@aws-amplify/ui-react';
+import '@aws-amplify/ui-react/styles.css';
+
+function App() {
+  return (
+    <Button
+      ariaLabel="Add item to cart"
+      backgroundColor="#ffd811"
+      borderRadius="1rem"
+      color="black"
+      fontWeight="normal"
+      onClick={() => alert('Added to cart! ✅')}
+      size="small"
+      width="8rem"
+    >
+      Add to Cart
+    </Button>
+  );
+}
+
+export default App;

docs/src/pages/[platform]/getting-started/usage/examples/ComponentExampleDemo.tsx

@@ -0,0 +1,18 @@
+import { Button } from '@aws-amplify/ui-react';
+
+export const ComponentExampleDemo = () => {
+  return (
+    <Button
+      ariaLabel="Add item to cart"
+      backgroundColor="#ffd811"
+      borderRadius="1rem"
+      color="black"
+      fontWeight="normal"
+      onClick={() => alert('Added to cart! ✅')}
+      size="small"
+      width="8rem"
+    >
+      Add to Cart
+    </Button>
+  );
+};

docs/src/pages/[platform]/getting-started/usage/examples/ReactExampleCode.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { Button } from '@aws-amplify/ui-react';
+import '@aws-amplify/ui-react/styles.css';
+
+function App() {
+  return <Button variation="primary">Hello world</Button>;
+}
+
+export default App;

docs/src/pages/[platform]/getting-started/usage/examples/ReactExampleDemo.tsx

@@ -0,0 +1,5 @@
+import { Button } from '@aws-amplify/ui-react';
+
+export const ReactExampleDemo = () => {
+  return <Button variation="primary">Hello world</Button>;
+};

docs/src/pages/[platform]/getting-started/usage/examples/ThemeExampleCode.tsx

@@ -0,0 +1,31 @@
+import { Button, ThemeProvider } from '@aws-amplify/ui-react';
+import '@aws-amplify/ui-react/styles.css'; // default theme
+
+const theme = {
+  name: 'custom-button-theme',
+  tokens: {
+    components: {
+      button: {
+        // this will affect the font weight of all Buttons
+        fontWeight: { value: '{fontWeights.black.value}' },
+        // this will only style Buttons which are the "primary" variation
+        primary: {
+          backgroundColor: { value: 'rebeccapurple' },
+          _hover: {
+            backgroundColor: { value: 'hotpink' },
+          },
+        },
+      },
+    },
+  },
+};
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Button variation="primary">Custom button</Button>
+    </ThemeProvider>
+  );
+}
+
+export default App;

docs/src/pages/[platform]/getting-started/usage/examples/ThemeExampleDemo.tsx

@@ -0,0 +1,25 @@
+import { Button, ThemeProvider } from '@aws-amplify/ui-react';
+
+const theme = {
+  name: 'custom-button-theme',
+  tokens: {
+    components: {
+      button: {
+        fontWeight: { value: '{fontWeights.black.value}' },
+        primary: {
+          backgroundColor: { value: 'rebeccapurple' },
+          _hover: {
+            backgroundColor: { value: 'hotpink' },
+          },
+        },
+      },
+    },
+  },
+};
+export const ThemeExampleDemo = () => {
+  return (
+    <ThemeProvider theme={theme}>
+      <Button variation="primary">Custom button</Button>
+    </ThemeProvider>
+  );
+};

docs/src/pages/[platform]/getting-started/usage/examples/index.ts

@@ -0,0 +1,3 @@
+export { ComponentExampleDemo } from './ComponentExampleDemo';
+export { ReactExampleDemo } from './ReactExampleDemo';
+export { ThemeExampleDemo } from './ThemeExampleDemo';

docs/src/pages/[platform]/getting-started/usage/usage.react.mdx

@@ -1,15 +1,78 @@
 import { Tabs, TabItem } from '@aws-amplify/ui-react';
 import { Example, ExampleCode } from '@/components/Example';
+import {
+  ComponentExampleDemo,
+  ReactExampleDemo,
+  ThemeExampleDemo,
+} from './examples';
 
-## Import styles and components
+## React and Amplify UI
 
-Load the default styling by importing our CSS:
+Amplify UI is designed to integrate seamlessly with the React framework so you can get started in no time. 
 
-```jsx
-import { View } from '@aws-amplify/ui-react';
-import '@aws-amplify/ui-react/styles.css'; // default theme
+### Installation
+
+If you haven't already, install `@aws-amplify/ui-react` with [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/):
+
+<Tabs>
+<TabItem title="npm">
+
+```shell
+npm install aws-amplify @aws-amplify/ui-react
+```
+
+</TabItem>
+<TabItem title="yarn">
+
+```shell
+yarn add aws-amplify @aws-amplify/ui-react
+```
+
+</TabItem>
+</Tabs>
+
+### Quick start
+
+Here's all you need to get up and running:
+
+<ExampleCode>
+```tsx file=./examples/ReactExampleCode.tsx 
+
+```
+</ExampleCode>
+
+Copy/paste the code above into your React app, start the app, and look at that lovely Button!
+
+<ReactExampleDemo />
+
+### Components
+
+You can use all of Amplify UI's primitive components (e.g., `Button`, `Tabs`, `Flex`) right out-of-the-box. These are the same components we use to build our connected components such as the [Authenticator](/react/components/authenticator). Please refer to each component's [documentation](/react/components/button) to see how they should be imported, configured and styled.
+
+<Example>
+  <ComponentExampleDemo />
+  <ExampleCode>
+```tsx file=./examples/ComponentExampleCode.tsx
+
+```
+  </ExampleCode>
+</Example>
+
+### Theming
+
+Amplify UI ships with a default [theme](/react/theming) that you can customize to match the look and feel of your project. Remember to load the default styling by importing our CSS at the entry-point to your application (e.g., `src/App.js`).
+
+```js
+import '@aws-amplify/ui-react/styles.css';
+```
+
+To learn how to customize the appearance of all components in your application with a theme, see [theming](/react/theming). 
+
+<Example>
+  <ThemeExampleDemo />
+  <ExampleCode>
+```tsx file=./examples/ThemeExampleCode.tsx
 
-export default function App() {
-  return <View>Your app here</View>;
-}
 ```
+  </ExampleCode>
+</Example>