Cleanup UI migration

docs/best-practices.md

@@ -102,45 +102,58 @@ export default ComponentName
 
 ## Styling
 
-- `src/theme.ts` - Declares site color themes, breakpoints and other constants (try to utilize these colors first)
-- We use [emotion](https://emotion.sh/)
+We use [Chakra UI](https://chakra-ui.com/).
 
-  - Tagged template literals are used to style custom components
+`src/@chakra-ui/gatsby-plugin/theme.ts` - Holds all the theme configuration. This is where you can find the colors, fonts, component themes, variants, etc.
 
-  ```tsx
-  // Example of styling syntax using emotion
-
-  import styled from "@emotion/styled"
-
-  const GenericButton = styled.div`
-    width: 200px;
-    height: 50px;
-  `
-  const PrimaryButton = styled(GenericButton)`
-    background: blue;
-  `
-  const SecondaryButton = styled(GenericButton)`
-    background: red;
-  `
-
-  // These are each components, capitalized by convention, and can be used within JSX code
-  // ie: <PrimaryButton>Text</PrimaryButton>
-  ```
+- Wrappers or layout divs
 
-- Values from `src/theme.ts` are automatically passed as a prop object to styled components
+Use the [native layouts components](https://chakra-ui.com/docs/components/box)
 
-  ```tsx
-  // Example of theme.ts usage
+```tsx
+<Stack direction='row'>
+```
 
-  import styled from "@emotion/styled"
+Center things using the `<Center />` component
 
-  const Container = styled.div`
-    background: ${(props) => props.theme.colors.background};
-    @media (max-width: ${(props) => props.theme.breakpoints.s}) {
-      font-size: #{(props) => props.theme.fontSized.s};
-    }
-  `
-  ```
+```tsx
+<Center h="100px">
+```
+
+- Group buttons using `<ButtonGroup />` or `<Wrap />`
+
+```tsx
+<ButtonGroup variant='outline' spacing={2}>
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</ButtonGroup>
+
+// or
+<Wrap spacing={2}>
+  <WrapItem><Button variant="outline">Button 1</Button></WrapItem>
+  <WrapItem><Button variant="outline">Button 2</Button></WrapItem>
+</Wrap>
+```
+
+- Breakpoints
+
+Use [the Chakra default breakpoints](https://chakra-ui.com/docs/styled-system/theme#breakpoints).
+
+```tsx
+<Container display={{ base: "block", sm: "flex" }} />
+```
+
+- Theme colors
+
+```tsx
+<Text color="primary.base" bg="background.base" />
+```
+
+> Note the dotted notation. In Chakra, the values are referred to as "semantic tokens" and the new theme applies a nested structure of like tokens for better organization. See [semanticTokens.ts](../src/%40chakra-ui/gatsby-plugin/semanticTokens.ts)
+
+> Note 2: all the previous colors defined in the old theme `src/theme.ts` were
+> ported into the new theme for compatibility reasons. Those colors will
+> transition out of the codebase as we adopt the DS colors.
 
 - [Framer Motion](https://www.framer.com/motion/) - An open source and production-ready motion library for React on the web, used for our animated designs
 - **Emojis**: We use [Twemoji](https://twemoji.twitter.com/), an open-source emoji set created by Twitter. These are hosted by us, and used to provide a consistent experience across operating systems.
@@ -154,29 +167,14 @@ import Emoji from "./Emoji"
 ```
 
 - **Icons**: We use [React Icons](https://react-icons.github.io/react-icons/)
-  - `src/components/Icon.ts` is the component used to import icons to be used
-  - If an icon you want to use is not listed you will need to add it to this file
-
-`src/components/Icon.ts`:
-
-```tsx
-// Example of how to add new icon not listed
-import { ZzIconName } from "react-icons/zz"
-
-// Then add to IconContext.Provider children:
-{
-  name === "alias" && <ZzIconName />
-}
-```
-
-From React component:
+  with [Chakra UI Icon component](https://chakra-ui.com/docs/components/icon/usage)
 
 ```tsx
-// Example of icon use
-import Icon from "./Icon"
+import { Icon } from "@chakra-ui/react"
+import { BsQuestionSquareFill } from "react-icons/bs"
 
-// Within JSX:
-;<Icon name="alias" />
+// wrap your imported icon with the `Icon` component from Chakra UI
+;<Icon as={BsQuestionSquareFill} />
 ```
 
 ## Image loading and API calls using GraphQL