Update migration guide

jxnblk · jxnblk · commit 9e8b505f3714 · 2020-01-13T15:21:52.000-05:00
diff --git a/packages/docs/src/pages/color-modes.mdx b/packages/docs/src/pages/color-modes.mdx
@@ -72,6 +72,8 @@ export default props => (
 )
 ```
 
+To disable this behavior, add the `useBodyStyles: false` flag to your theme.
+
 ## Gatsby plugin
 
 For use in a Gatsby site, install and use `gatsby-plugin-theme-ui` to add the ThemeProvider to the root of your application.
diff --git a/packages/docs/src/pages/migrating.mdx b/packages/docs/src/pages/migrating.mdx
@@ -6,13 +6,25 @@ title: Migrating
 
 ## v0.3
 
+### What's New
+
+- Components can now be imported directly from the `theme-ui` package. Be sure that treeshaking is enabled with your build tool.
+- Includes smart defaults for adding base styles to the `<body>` element.
+- Simplified color modes API.
+- New `@theme-ui/css`, `@theme-ui/core`, `@theme-ui/color-modes`, and `@theme-ui/mdx` packages allow for more bespoke ways to use the library.
+
+### Breaking Changes
+
+- `@emotion/core` and `@mdx-js/react` are now dependencies of `theme-ui` and should not be installed separately. If you'd like to use a particular version of each library, use [Yarn resolutions](https://yarnpkg.com/lang/en/docs/selective-version-resolutions/).
 - Theme UI context no longer provides `context.components`. If you're using this object from context, use the MDX hook instead. E.g. `import { useMDXComponents } from '@mdx-js/react'`
-- Color mode API:
-  - Default color mode name
-  - Manually enable `useColorSchemeMediaQuery`
-- Removes layout components (`Layout`, `Header`, `Main`, `Footer`). Use the `Box` and `Flex` layout primitives instead.
-- Theme context is now stateless. If you've made use of `context.setTheme`, this no longer works. An alternative approach will be introduced later.
-- Global typographic styles
+- If you'd like color mode to be initialized from the `prefers-color-scheme` media query, you must enable the `useColorSchemeMediaQuery: true` flag in your theme.
+- The `ColorMode` component is deprecated and no longer required to add color styles to the `<body>` element.
+- The following components have been removed in favor of using `Box` and `Flex` components: `Layout`, `Header`, `Main`, `Footer`
+- The `initialColorMode` flag no longer works, use `initialColorModeName` instead.
+- The `ThemeProvider` now adds global typographic styles to the `<body>` element based on `theme.styles.root`. To disable this behavior set the `useBodyStyles: false` flag in your theme.
+- Theme context is now stateless. If you've made use of `context.setTheme`, this no longer works. An alternative approach is available with the `@theme-ui/editor` package.
+- The `ThemeStateProvider` component is no longer avialable, see `@theme-ui/editor` as an alternative.
+- The `@theme-ui/editor` package has a completely new API. Please refer to the package's [README.md](https://github.com/system-ui/theme-ui/blob/master/packages/editor/README.md) for more information.
 
 ## v0.2
 
diff --git a/packages/docs/src/pages/theming.mdx b/packages/docs/src/pages/theming.mdx
@@ -163,6 +163,17 @@ These values will be used to generate mobile-first (i.e. `min-width`) media quer
 }
 ```
 
+## Configuration Flags
+
+The theme object can also include configuration options for Theme UI. The following keys can be used to enable and disable certain features.
+
+Flag | Default | Description
+---|---|---
+`useCustomProperties` | `true` | Enables CSS custom properties to help mitigate a flash of unstyled content during rehydration
+`useBodyStyles` | `true` | Adds styles defined in `theme.styles.root` to the `<body>` element along with `color` and `background-color`
+`initialColorModeName` | `'default'` | The key used for the top-level color palette in `theme.colors`
+`useColorSchemeMediaQuery` | `false` | Initializes the color mode based on the `prefers-color-scheme` media query
+
 ## Example Theme
 
 The following example is from the [Base Preset][example].

Original file line number	Diff line number	Diff line change
`@@ -72,6 +72,8 @@ export default props => (`
`72`	`72`	`)`
`73`	`73`	```
`74`	`74`
	`75`	+To disable this behavior, add the `useBodyStyles: false` flag to your theme.
	`76`	`+`
`75`	`77`	`## Gatsby plugin`
`76`	`78`
`77`	`79`	For use in a Gatsby site, install and use `gatsby-plugin-theme-ui` to add the ThemeProvider to the root of your application.