Update theme documentation (#1392)

* Update theming doc to include info + examples with mergeTheme function

* Bump evergreen to 6.7.0 in docs

* Add mergeTheme/defaultTheme to code sandbox generator, as well as pulling in same version of evergreen that doc site uses

* Typos, add theme utilities section, fix bug in updated baseStyle example as the previous version was using object spreads to clobber all other Button styles without appearance='none'

* Bump evergreen version in docs

docs/documentation/introduction/theming.mdx

@@ -1,12 +1,12 @@
 # Introduction
 
-Evergreen ships with an all-new, extensible theming architecture that lets end-users customize the look and feel of the components in Evergreen as you want. You can target arbtirary styles and states of each component to achieve maximum flexibility and alignment with your brand. This page goes over some of the options and background of the theming architecture, and how you can leverage it in your apps.
+Evergreen ships with an all-new, extensible theming architecture that lets end-users customize the look and feel of the components in Evergreen as you want. You can target arbitrary styles and states of each component to achieve maximum flexibility and alignment with your brand. This page goes over some of the options and background of the theming architecture, and how you can leverage it in your apps.
 
 # Classic and Default Theme
 
-For starters, Evergreen ships with two themes. The `defaultTheme` is the current brand (and the one we use internally at Segment!), and the `classicTheme` is the same look and feel from the previous iterations of Evergreen (v4+).
+For starters, Evergreen ships with two themes. The `defaultTheme` is the current brand (and the one we use internally at Segment!), and the `classicTheme` is the same look and feel from the previous iterations of Evergreen (v4 and v5).
 
-> If you are using a previous version of upgrade, you'll want to explicitly set your theme to the classicTheme
+> If you are using a previous version of Evergreen, you'll want to explicitly set your theme to the classicTheme
 
 ```jsx
 <Pane display="grid" gridTemplateColumns="repeat(auto-fill, minmax(100px, 1fr))" gridColumnGap="300px">
@@ -45,10 +45,8 @@ An example implementation that leverages some of these props to create a custom
 
 ```jsx
 function CustomButtonExample() {
-  const theme = {
-    ...defaultTheme,
+  const theme = mergeTheme(defaultTheme, {
     components: {
-      ...defaultTheme.components,
       Button: {
         baseStyle: {
           color: 'white',
@@ -68,11 +66,11 @@ function CustomButtonExample() {
         },
       },
     },
-  }
+  })
 
   return (
     <ThemeProvider value={theme}>
-      <Button>Custom Button</Button>
+      <Button appearance="none">Custom Button</Button>
     </ThemeProvider>
   )
 }
@@ -83,13 +81,10 @@ function CustomButtonExample() {
 The theming API also supports custom appearances, so you can bring your own verbiage and nomenclature to how you want to define Evergreen styles. We are still working out TypeScript support for this, so use at your own discretion! For the example below, we are going to take those same styles, and apply them to respond to a prop `appearance="superdanger"`.
 
 ```jsx
-function CustomAppearancesExmaple() {
-  const theme = {
-    ...defaultTheme,
+function CustomAppearancesExample() {
+  const theme = mergeTheme(defaultTheme, {
     components: {
-      ...defaultTheme.components,
       Button: {
-        ...defaultTheme.components.Button,
         appearances: {
           superdanger: {
             color: 'white',
@@ -110,7 +105,7 @@ function CustomAppearancesExmaple() {
         },
       },
     },
-  }
+  })
 
   return (
     <ThemeProvider value={theme}>
@@ -120,9 +115,15 @@ function CustomAppearancesExmaple() {
 }
 ```
 
+# Theme Utilities
+
+`mergeTheme` is a utility function that allows you to deeply merge a partial `Theme` object onto another one, such as the `defaultTheme`, without having to do multiple object spreads (i.e. `...defaultTheme, ...defaultTheme.colors, ...defaultTheme.components`). If you're using TypeScript, it returns a type union of `DestinationTheme & SourceTheme`, where `DestinationTheme` is the first argument (such as `defaultTheme`) and `SourceTheme` is the type of the second argument (which can be explicitly or implicitly typed).
+
+`useTheme` is a hook that returns the current theme object from the `ThemeProvider`. It is generically typed, so you can use it to provide a strongly typed version of your own theme.
+
 # Theme Shape
 
-All in all, the shape of the theme object looks as follows. Use this as your baseline direction for piecing together and building theme objects.
+All in all, the shape of the theme object looks as follows. Use this as your baseline direction for piecing together and building theme objects. For TypeScript users, you should be able to use parts of the generic [Theme](https://github.com/segmentio/evergreen/blob/11fd42f489b4784d6e82acae9bd27133be898148/index.d.ts#L311-L324) for constructing your own theme, or [DefaultTheme](https://github.com/segmentio/evergreen/blob/master/index.d.ts#L368-L388) which is a more specific version of the interface for `defaultTheme`.
 
 ```js readonly
 export default {
@@ -137,16 +138,16 @@ export default {
     mono: '...',
   },
   fontSizes: {
-    /*...*/
+    /* ... */
   },
   fontWeights: {
-    /*...*/
+    /* ... */
   },
   letterSpacings: {
-    /* ...*/
+    /* ... */
   },
   lineHeights: [
-    /*...*/
+    /* ... */
   ],
   zIndices,
   components: {

docs/lib/codesandbox.ts

@@ -1,4 +1,5 @@
 import LZString from 'lz-string'
+import { dependencies } from '../package.json'
 
 function compress(string: string) {
   return LZString.compressToBase64(string).replace(/\+/g, `-`).replace(/\//g, `_`).replace(/=+$/, ``)
@@ -20,9 +21,9 @@ export const getCodeSandboxLink: (source: string) => string = (source) => {
 
   const usedComponents = Array.from(
     new Set(
-      (source.match(/<((\w+))|minorScale|majorScale|(((\w+)Icon))|Position/g) || []).map((component) =>
-        component.replace('<', '')
-      )
+      (
+        source.match(/<((\w+))|minorScale|majorScale|mergeTheme|defaultTheme|(((\w+)Icon))|Position/g) || []
+      ).map((component) => component.replace('<', ''))
     )
   ).join(', ')
 
@@ -48,7 +49,7 @@ ReactDOM.render(
           dependencies: {
             react: '16.8.0',
             'react-dom': '16.8.0',
-            'evergreen-ui': `6.0.0-34`,
+            'evergreen-ui': `${dependencies['evergreen-ui']}`,
           },
           devDependencies: {
             'react-scripts': 'latest',

docs/package.json

@@ -15,7 +15,7 @@
     "@segment/consent-manager": "^5.1.0",
     "@types/react-github-button": "^0.1.0",
     "@types/react-syntax-highlighter": "^13.5.0",
-    "evergreen-ui": "6.6.5",
+    "evergreen-ui": "6.7.1",
     "lz-string": "^1.4.4",
     "next": "latest",
     "next-mdx-remote": "^2.1.3",

docs/utils/IA.ts

@@ -59,7 +59,7 @@ const IA: IA = {
         id: 'what-is-new',
         name: 'What is new',
         description:
-          'Evergreen is a living system, which means we are constently making updates to it. You can learn more about those changes and upcoming ones here.',
+          'Evergreen is a living system, which means we are constantly making updates to it. You can learn more about those changes and upcoming ones here.',
       },
     ],
   },