docs: Write migration notes for v0.13

Author: hasparus

.gitignore

@@ -12,6 +12,6 @@ coverage
 .envrc.ps1
 .publish-log.txt
 .yarn-error.log
-
+yarn-error.log
 
 .vercel

MIGRATING.md

@@ -1,5 +1,37 @@
 # Migration Guides
 
+## v0.13
+
+**Moved Emotion and `@mdx-js/react` to peerDependencies to solve context
+mismatch bugs**
+
+You now install `theme-ui` umbrella package like this:
+
+```
+npm install theme-ui @emotion/react @emotion/styled @mdx-js/react
+```
+
+- `@emotion/react` is now a peer dependency of the majority of Theme UI
+  libraries
+- `@emotion/styled` is now a peer dependency of `@theme-ui/components`,
+  `@theme-ui/mdx`, and `theme-ui`
+- `@mdx-js/react` is now a peer dependency of `@theme-ui/mdx` and `theme-ui`
+
+This is a revert of change from Theme UI v0.3, and it's meant to help solve
+version clashes and context mismatch bugs on user side. Connected issues:
+[#1793](https://github.com/system-ui/theme-ui/pull/1793),
+[#1531](https://github.com/system-ui/theme-ui/pull/1531),
+[#1530](https://github.com/system-ui/theme-ui/pull/1530),
+[#1388](https://github.com/system-ui/theme-ui/pull/1388),
+[#1345](https://github.com/system-ui/theme-ui/pull/1345),
+[#1130](https://github.com/system-ui/theme-ui/pull/1130).
+
+_Disclaimer: You might still encounter this problem if other libraries install
+clashing Emotion versions._
+
+Learn more at
+[#1867](https://github.com/system-ui/theme-ui/pull/1867#issue-948084198).
+
 ## v0.9
 
 **Dropped support for legacy browsers.**

packages/core/package.json

@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "@theme-ui/css": "0.12.1",
-    "@theme-ui/parse-props": "0.12.1",
+    "@theme-ui/parse-props": "0.12.1"
   },
   "peerDependencies": {
     "react": "^16 || ^17",

packages/theme-ui/README.md

@@ -113,7 +113,7 @@ scales help you build UI rooted in constraint-based design principles.
 ## Getting Started
 
 ```sh
-npm install theme-ui @emotion/react @mdx-js/react
+npm install theme-ui @emotion/react @emotion/styled @mdx-js/react
 ```
 
 _If you don't need color modes, components and MDX support, you can install
@@ -176,7 +176,8 @@ export default (props) => (
       fontWeight: 'bold',
       fontSize: 4, // picks up value from `theme.fontSizes[4]`
       color: 'primary', // picks up value from `theme.colors.primary`
-    }}>
+    }}
+  >
     Hello
   </div>
 )

yarn.lock

@@ -1467,7 +1467,7 @@
   dependencies:
     "@emotion/memoize" "0.7.4"
 
-"@emotion/is-prop-valid@^1.1.1":
+"@emotion/is-prop-valid@^1.1.0", "@emotion/is-prop-valid@^1.1.1":
   version "1.1.1"
   resolved "https://registry.yarnpkg.com/@emotion/is-prop-valid/-/is-prop-valid-1.1.1.tgz#cbd843d409dfaad90f9404e7c0404c55eae8c134"
   integrity sha512-bW1Tos67CZkOURLc0OalnfxtSXQJMrAMV0jZTVGJUPSOd4qgjF3+tTD5CwJM13PHA8cltGW1WGbbvV9NpvUZPw==