docs(updating): change theme to palette in the migration guide to v8 (#3590)

brandyscarney · web-flow · commit 632041bffb62 · 2024-04-10T16:07:44.000-04:00
diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md
@@ -74,9 +74,9 @@ npm install @ionic/core@next
 
 The following changes are not required to update to Ionic 8 as your application will continue to work. However, we recommend making the following changes to ensure you can use the new features in Ionic 8.
 
-### Light Theme
+### Light Palette
 
-Previous versions shipped a set of default color variables for the light theme:
+Previous versions defined a set of default color variables for the light palette in `theme/variables.scss`:
 
 ```css
 /** Ionic CSS Variables **/
@@ -90,15 +90,15 @@ Previous versions shipped a set of default color variables for the light theme:
 }
 ```
 
-In Ionic Framework version 8, the default color palette is included as long as `core.css` is imported. Removing the old color variables ensures that the latest palette is not overwritten.
+In Ionic Framework version 8, these color variables are included as long as `core.css` is imported. The color variables defined in `theme/variables.scss` should be removed to avoid overriding the imported default variables and ensure the app is always using the latest palette.
 
 Developers who are customizing this color palette can continue to keep the custom variables values, but any of the variables that use the default values should be removed.
 
 You can read more about the new color palette in the [Ionic v8 announcement](https://ionic.io/blog/announcing-the-ionic-8-beta).
 
-### Dark Theme
+### Dark Palette
 
-In previous versions, it was recommended to define the dark theme in the following way:
+In previous versions, it was recommended to define the dark palette in the following way:
 
 ```css
 @media (prefers-color-scheme: dark) {
@@ -116,25 +116,25 @@ In previous versions, it was recommended to define the dark theme in the followi
 }
 ```
 
-In Ionic Framework version 8, the dark theme is being distributed via css files that can be imported. Below is an example of importing a dark theme file in Angular:
+In Ionic Framework version 8, the dark palette is being distributed via css files that can be imported. Below is an example of importing a dark palette file in Angular:
 
 ```css
 /* @import '@ionic/angular/css/palettes/dark.always.css'; */
 /* @import "@ionic/angular/css/palettes/dark.class.css"; */
 @import '@ionic/angular/css/palettes/dark.system.css';
 ```
 
-The dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `<html>` element and is identical to the selector `html`, except that its specificity is higher.
+The dark palette is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `<html>` element and is identical to the selector `html`, except that its specificity is higher.
 
-While migrating to include the new dark theme files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the `body` element. We recommend updating any instances where global application variables are set to target the `:root` selector instead.
+While migrating to include the new dark palette files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the `body` element. We recommend updating any instances where global application variables are set to target the `:root` selector instead.
 
-For more information on the new dark theme files, refer to the [Dark Mode documentation](../theming/dark-mode).
+For more information on the new dark palette files, refer to the [Dark Mode documentation](../theming/dark-mode).
 
 ### Step Color Tokens
 
-To better support the high contrast theme in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of `--ion-color-step-[number]` tokens.
+To better support the high contrast palette in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of `--ion-color-step-[number]` tokens.
 
-Using the newly imported dark theme mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.
+Using the newly imported dark palette mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.
 
 `--ion-color-step-[number]` usages for **background color** can be migrated by renaming the token to `--ion-background-color-step-[number]`.
 
@@ -172,7 +172,7 @@ For more information on the dynamic font, refer to the [Dynamic Font Scaling doc
 
 ### (Angular Only) `angular.json` CSS import order
 
-The `angular.json` file currently imports `src/theme/variables.scss` before importing `src/global.scss`. This may cause the incorrect styles to be applied when customizing the new [Dark Theme](#dark-theme) changes.
+The `angular.json` file currently imports `src/theme/variables.scss` before importing `src/global.scss`. This may cause the incorrect styles to be applied when customizing the new [Dark Palette](#dark-palette) changes.
 
 We recommend having the `src/global.scss` file get imported first instead:
 
