From 16a3c352dee20c5b1c652162bb5b8e2ba6818d83 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <aaron.casanova@shopify.com>
Date: Mon, 22 Nov 2021 16:46:24 -0800
Subject: [PATCH 1/3] docs: Initial ThemeProvider migration guide

---
 .../guides/migrating-from-v7-to-v8.md         | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/documentation/guides/migrating-from-v7-to-v8.md b/documentation/guides/migrating-from-v7-to-v8.md
index f54521f1e2d..ea0b1c36932 100644
--- a/documentation/guides/migrating-from-v7-to-v8.md
+++ b/documentation/guides/migrating-from-v7-to-v8.md
@@ -1,3 +1,39 @@
 # Migrating from v7 to v8
 
 Polaris v8.0.0 ([full release notes](https://github.com/Shopify/polaris-react/releases/tag/v8.0.0)) features a rebuild of the `Autocomplete` component, build changes, . This file describes all code updates required to stay up to date.
+
+## `ThemeProvider` changes
+
+The `ThemeProvider` has been deprecated in favor of the new `CustomProperties` component. As a result, a number of internal components using the `ThemeProvider` have been updated to use the `CustomProperties` component and adjusted their prop interfaces accordingly (such as: `AppProvider`, `Popover`, etc.).
+
+`polaris-react` no longer supports accepting and transforming a custom theme object to influence the component library. Polaris will now maintain a set of predefined color-schemes that meet the immediate needs of the admin and thus the following changes are required:
+
+```diff
+- import {ThemeProvider} from '@shopify/polaris-react';
++ import {CustomProperties} from '@shopify/polaris-react';
+
+const App = (props) => (
+-  <ThemeProvider theme={{colorScheme: 'dark'}}>
+-    {props.children} 
+-	 </ThemeProvider>
++  <CustomProperties colorScheme="dark">
++    {props.children} 
++	 </CustomProperties>
+)
+```
+
+As mentioned above, the `ThemeProvider` has been removed from the `AppProvider` and replaced with the `CustomProperties` component.
+
+With that said, the `AppProvider` no longer accepts a custom theme object to forward to the `ThemeProvider`. However, similar behavior is still optionally exposed by forwarding the `colorScheme` prop to the `CustomProperties` component:
+
+```diff
+import {AppProvider} from '@shopify/polaris-react';
+
+const App = (props) => (
+-  <AppProvider theme={{colorScheme: 'dark'}}>
+-    {props.children} 
+-	 </AppProvider>
++  <AppProvider colorScheme="dark">
++    {props.children} 
++	 </AppProvider>
+)

From 5f6fd128a22392b9c63e5bedfe5257069fbb57e9 Mon Sep 17 00:00:00 2001
From: Aaron Casanova <aaron.casanova@shopify.com>
Date: Tue, 23 Nov 2021 09:43:41 -0800
Subject: [PATCH 2/3] docs: Fix formatting issue

---
 documentation/guides/migrating-from-v7-to-v8.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/documentation/guides/migrating-from-v7-to-v8.md b/documentation/guides/migrating-from-v7-to-v8.md
index ea0b1c36932..9ddf696663d 100644
--- a/documentation/guides/migrating-from-v7-to-v8.md
+++ b/documentation/guides/migrating-from-v7-to-v8.md
@@ -15,10 +15,10 @@ The `ThemeProvider` has been deprecated in favor of the new `CustomProperties` c
 const App = (props) => (
 -  <ThemeProvider theme={{colorScheme: 'dark'}}>
 -    {props.children} 
--	 </ThemeProvider>
+-  </ThemeProvider>
 +  <CustomProperties colorScheme="dark">
 +    {props.children} 
-+	 </CustomProperties>
++  </CustomProperties>
 )
 ```
 
@@ -32,8 +32,8 @@ import {AppProvider} from '@shopify/polaris-react';
 const App = (props) => (
 -  <AppProvider theme={{colorScheme: 'dark'}}>
 -    {props.children} 
--	 </AppProvider>
+-  </AppProvider>
 +  <AppProvider colorScheme="dark">
 +    {props.children} 
-+	 </AppProvider>
++  </AppProvider>
 )

From 0f9cafd723a944169f6c0a7f6dfc1662d6f6734f Mon Sep 17 00:00:00 2001
From: Aaron Casanova <aaron.casanova@shopify.com>
Date: Wed, 24 Nov 2021 08:53:37 -0800
Subject: [PATCH 3/3] docs: Fix formatting

---
 documentation/guides/migrating-from-v7-to-v8.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/documentation/guides/migrating-from-v7-to-v8.md b/documentation/guides/migrating-from-v7-to-v8.md
index 9ddf696663d..3852da7702b 100644
--- a/documentation/guides/migrating-from-v7-to-v8.md
+++ b/documentation/guides/migrating-from-v7-to-v8.md
@@ -14,10 +14,10 @@ The `ThemeProvider` has been deprecated in favor of the new `CustomProperties` c
 
 const App = (props) => (
 -  <ThemeProvider theme={{colorScheme: 'dark'}}>
--    {props.children} 
+-    {props.children}
 -  </ThemeProvider>
 +  <CustomProperties colorScheme="dark">
-+    {props.children} 
++    {props.children}
 +  </CustomProperties>
 )
 ```
@@ -31,9 +31,10 @@ import {AppProvider} from '@shopify/polaris-react';
 
 const App = (props) => (
 -  <AppProvider theme={{colorScheme: 'dark'}}>
--    {props.children} 
+-    {props.children}
 -  </AppProvider>
 +  <AppProvider colorScheme="dark">
-+    {props.children} 
++    {props.children}
 +  </AppProvider>
 )
+```