docs(updating): show how to migrate custom step color usages (#3496)

Author: liamdebeasi

docs/updating/8-0.md

@@ -108,6 +108,34 @@ While migrating to include the new dark theme files is unlikely to cause breakin
 
 For more information on the new dark theme 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.
+
+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.
+
+`--ion-color-step-[number]` usages for **background color** can be migrated by renaming the token to `--ion-background-color-step-[number]`.
+
+**Example**:
+
+```diff
+button {
+- background: var(--ion-color-step-400);
++ background: var(--ion-background-color-step-400);
+}
+```
+
+`--ion-color-step-[number]` usages for **text color** can be migrated by renaming the token to `--ion-text-color-step-[number]` and subtracting the number from 1000.
+
+**Example**:
+
+```diff
+button {
+- color: var(--ion-color-step-400);
++ color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */
+}
+```
+
 ### Dynamic Font
 
 The `core.css` file has been updated to enable dynamic font scaling by default.