diff --git a/documentation/guides/migrating-from-v8-to-v9.md b/documentation/guides/migrating-from-v8-to-v9.md
index b4ffed52e9c..6cf5a2d363b 100644
--- a/documentation/guides/migrating-from-v8-to-v9.md
+++ b/documentation/guides/migrating-from-v8-to-v9.md
@@ -108,15 +108,13 @@ The following CSS custom properties have either been renamed or removed. You wil
## Sass functions and mixins
-The following sass functions and mixins have been removed. You will either need to add the functions to your repo or replace all function instances with values.
+The following Sass functions and mixins have been removed. You will need to either add the function or mixin to your repo or replace any instances of them with a CSS custom property or value equivalent.
-### Replacing function and mixin instances with values or tokens
-
-A list of functions/mixins and their value equivalents or new token values.
+### Replacing function and mixin instances with value equivalents
#### `border()`
-| Function | Replacement Value/Token |
+| Deprecated Function | Replacement Value |
| ---------------------------- | ------------------------ |
| `border()`
`border(base)` | `--p-border-base` |
| `border(dark)` | `--p-border-dark` |
@@ -125,18 +123,18 @@ A list of functions/mixins and their value equivalents or new token values.
#### `border-radius()`
-| Function | Replacement Value/Token |
+| Deprecated Function | Replacement Value |
| ------------------------------------------ | ------------------------- |
| `border-radius()`
`border-radius(base)` | `--p-border-radius-base` |
| `border-radius(large)` | `--p-border-radius-large` |
#### `border-width()`
-| Function | Replacement Value/Token |
-| ---------------------------------------- | ----------------------- |
-| `border-width()`
`border-width(base)` | `--p-border-width-1` |
-| `border-width(thick)` | `--p-border-width-2` |
-| `border-width(thicker)` | `--p-border-width-3` |
+| Deprecated Function | Replacement Value |
+| ---------------------------------------- | -------------------- |
+| `border-width()`
`border-width(base)` | `--p-border-width-1` |
+| `border-width(thick)` | `--p-border-width-2` |
+| `border-width(thicker)` | `--p-border-width-3` |
#### `color()`
@@ -179,31 +177,32 @@ Use your browser developer tools to inspect the output color value of the functi
Otherwise, you can copy the function definition and use it locally.
-| Function | Source |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `color-multiply()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L479-L500) |
+| Deprecated Function | Source |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color-multiply()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L479-L500) |
#### `duration()`
-| Function | Replacement Value/Token |
-| -------------------------------- | ----------------------- |
-| `duration(none)` | 0 |
-| `duration(fast)` | `--p-duration-100` |
-| `duration()`
`duration(base)` | `--p-duration-200` |
-| `duration(slow)` | `--p-duration-300` |
-| `duration(slower)` | `--p-duration-400` |
-| `duration(slowest)` | `--p-duration-500` |
+| Deprecated Function | Replacement Value |
+| -------------------------------- | ------------------ |
+| `duration(none)` | 0 |
+| `duration(fast)` | `--p-duration-100` |
+| `duration()`
`duration(base)` | `--p-duration-200` |
+| `duration(slow)` | `--p-duration-300` |
+| `duration(slower)` | `--p-duration-400` |
+| `duration(slowest)` | `--p-duration-500` |
#### `em()`
This function has been deprecated, but the definition can be copied and used locally.
-| Function | Source |
-| -------- | -------------------- |
-| `em()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L333-L352) |
+
+| Deprecated Function | Source |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `em()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L333-L352) |
#### `easing()`
-| Function | Replacement Value/Token |
+| Deprecated Function | Replacement Value |
| ---------------------------- | -------------------------------------- |
| `easing()`
`easing(base)` | `--p-ease` |
| `easing(in)` | `--p-ease-in` |
@@ -214,12 +213,12 @@ This function has been deprecated, but the definition can be copied and used loc
#### `filter()`
-We replaced a few of the following filter function instances with color tokens instead of their exact replacement values. However, this can break intended behavior so be careful if you take this approach as well.
+We replaced a few of the following filter function instances with our [new color tokens](https://github.com/Shopify/polaris-react/blob/20dba92b5b226347d4e5220246a7165319a07836/src/tokens/token-groups/color.light.json) instead of their exact replacement values. However, this can break intended behavior so be careful if you take this approach as well. If you decide to use the new color tokens make sure to prefix them with `--p-` (they get mapped to css custom properties).
-Table of Replacement Values/Tokens
+Table of Replacement Values
-| Function | Replacement Value/Token |
+| Deprecated Function | Replacement Value |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `filter('purple', 'text')` | `brightness(0) saturate(100%) invert(29%) sepia(3%) saturate(2843%) hue-rotate(223deg) brightness(92%) contrast(86%)` |
| `filter('purple', 'darker')` | `brightness(0) saturate(100%) invert(8%) sepia(38%) saturate(6605%) hue-rotate(265deg) brightness(99%) contrast(124%)` |
@@ -286,10 +285,10 @@ We replaced a few of the following filter function instances with color tokens i
#### `font-family()`
-| Function | Replacement Value/Token |
-| ----------------------------------------------- | ----------------------- |
-| `font-family()`
`font-family($family: base)` | `--p-font-family-sans` |
-| `font-family($family: 'monospace')` | `--p-font-family-mono` |
+| Deprecated Function | Replacement Value |
+| ----------------------------------------------- | ---------------------- |
+| `font-family()`
`font-family($family: base)` | `--p-font-family-sans` |
+| `font-family($family: 'monospace')` | `--p-font-family-mono` |
#### `hidden-when-printing()`
@@ -318,7 +317,7 @@ We replaced a few of the following filter function instances with color tokens i
#### `high-contrast-border()`
-| Mixin | Replacement Value/Token |
+| Deprecated Mixin | Replacement Value |
| -------------------------------------------------------------- | ---------------------------------------------------- |
| `@include high-contrast-border` | `border: var(--p-border-width-1) solid transparent;` |
| `@include high-contrast-border($border-width: )` | `border: solid transparent;` |
@@ -329,7 +328,7 @@ For `` instances that are hard coded values, see if you can replac
#### `high-contrast-outline()`
-| Mixin | Replacement Value/Token |
+| Deprecated Mixin | Replacement Value |
| --------------------------------------------------------------- | ----------------------------------------------------- |
| `@include high-contrast-outline` | `outline: var(--p-border-width-1) solid transparent;` |
| `@include high-contrast-outline($border-width: )` | `outline: solid transparent;` |
@@ -340,29 +339,29 @@ For `` instances that are hard coded values, see if you can replac
#### `icon-size()`
-| Function | Replacement Value/Token |
-| ------------- | ----------------------- |
-| `icon-size()` | `--p-icon-size-medium` |
+| Deprecated Function | Replacement Value |
+| ------------------- | ---------------------- |
+| `icon-size()` | `--p-icon-size-medium` |
#### `map-extend()`
This function has been deprecated, but the definition can be copied and used locally.
-| Function | Source |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `map-extend()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L388-L409) |
+| Deprecated Function | Source |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `map-extend()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L388-L409) |
#### `ms-high-contrast-color()`
-| Function | Replacement Value/Token |
-| ---------------------------------------------------- | ----------------------- |
-| `ms-high-contrast-color('text')` | `windowText` |
-| `ms-high-contrast-color('disabled-text')` | `grayText` |
-| `ms-high-contrast-color('selected-text')` | `highlightText` |
-| `ms-high-contrast-color('selected-text-background')` | `highlight` |
-| `ms-high-contrast-color('button-text')` | `buttonText` |
-| `ms-high-contrast-color('button-text-background')` | `buttonFace` |
-| `ms-high-contrast-color('background')` | `window` |
+| Deprecated Function | Replacement Value |
+| ---------------------------------------------------- | ----------------- |
+| `ms-high-contrast-color('text')` | `windowText` |
+| `ms-high-contrast-color('disabled-text')` | `grayText` |
+| `ms-high-contrast-color('selected-text')` | `highlightText` |
+| `ms-high-contrast-color('selected-text-background')` | `highlight` |
+| `ms-high-contrast-color('button-text')` | `buttonText` |
+| `ms-high-contrast-color('button-text-background')` | `buttonFace` |
+| `ms-high-contrast-color('background')` | `window` |
#### `print-hidden()`
@@ -392,21 +391,22 @@ This function has been deprecated, but the definition can be copied and used loc
#### `px()`
This function has been deprecated, but the definition can be copied and used locally.
-| Function | Source |
-| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `px()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss##L313-L331) |
+
+| Deprecated Function | Source |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `px()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss##L313-L331) |
#### `rem()`
This function has been deprecated, but the definition can be copied and used locally.
-| Function | Source |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rem()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L293-L311) |
+| Deprecated Function | Source |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rem()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss#L293-L311) |
#### `shadow()`
-| Function | Replacement Value/Token |
+| Deprecated Function | Replacement Value |
| ---------------------------- | ------------------------ |
| `shadow(faint)` | `--p-shadow-faint` |
| `shadow()`
`shadow(base)` | `--p-shadow-base` |
@@ -489,15 +489,15 @@ will-change: opacity;
#### `spacing()`
-| Function | Replacement Value/Token |
-| ------------------------------ | ----------------------- |
-| `spacing(none)` | `--p-space-0` |
-| `spacing(extra-tight)` | `--p-space-1` |
-| `spacing(tight)` | `--p-space-2` |
-| `spacing(base-tight)` | `--p-space-3` |
-| `spacing()`
`spacing(base)` | `--p-space-4` |
-| `spacing(loose)` | `--p-space-5` |
-| `spacing(extra-loose)` | `--p-space-8` |
+| Deprecated Function | Replacement Value |
+| ------------------------------ | ----------------- |
+| `spacing(none)` | `--p-space-0` |
+| `spacing(extra-tight)` | `--p-space-1` |
+| `spacing(tight)` | `--p-space-2` |
+| `spacing(base-tight)` | `--p-space-3` |
+| `spacing()`
`spacing(base)` | `--p-space-4` |
+| `spacing(loose)` | `--p-space-5` |
+| `spacing(extra-loose)` | `--p-space-8` |
#### `unstyled-link()`
@@ -554,33 +554,33 @@ list-style: none;
#### `when-not-printing()`
-| Mixin | Replacement Value/Token |
-| ---------------------------- | ----------------------- |
-| `@include when-not-printing` | `@media not print` |
+| Deprecated Mixin | Replacement Value |
+| ---------------------------- | ------------------ |
+| `@include when-not-printing` | `@media not print` |
#### `when-printing()`
-| Mixin | Replacement Value/Token |
-| ------------------------ | ----------------------- |
-| `@include when-printing` | `@media print` |
+| Deprecated Mixin | Replacement Value |
+| ------------------------ | ----------------- |
+| `@include when-printing` | `@media print` |
#### `z-index()`
-| Function | Replacement Value/Token |
-| -------------------------- | ----------------------- |
-| `z-index(content)` | `--p-z-1` |
-| `z-index(overlay)` | `--p-z-2` |
-| `z-index(global-ribbon)` | `--p-z-3` |
-| `z-index(top-bar)` | `--p-z-4` |
-| `z-index(context-bar)` | `--p-z-5` |
-| `z-index(loading-bar)` | `--p-z-6` |
-| `z-index(nav-backdrop)` | `--p-z-7` |
-| `z-index(nav)` | `--p-z-8` |
-| `z-index(skip-to-content)` | `--p-z-9` |
-| `z-index(backdrop)` | `--p-z-10` |
-| `z-index(modal)` | `--p-z-11` |
-| `z-index(toast)` | `--p-z-12` |
-| `z-index(devUi)` | `521` |
+| Deprecated Function | Replacement Value |
+| -------------------------- | ----------------- |
+| `z-index(content)` | `--p-z-1` |
+| `z-index(overlay)` | `--p-z-2` |
+| `z-index(global-ribbon)` | `--p-z-3` |
+| `z-index(top-bar)` | `--p-z-4` |
+| `z-index(context-bar)` | `--p-z-5` |
+| `z-index(loading-bar)` | `--p-z-6` |
+| `z-index(nav-backdrop)` | `--p-z-7` |
+| `z-index(nav)` | `--p-z-8` |
+| `z-index(skip-to-content)` | `--p-z-9` |
+| `z-index(backdrop)` | `--p-z-10` |
+| `z-index(modal)` | `--p-z-11` |
+| `z-index(toast)` | `--p-z-12` |
+| `z-index(devUi)` | `521` |
### Adding the functions and mixins to your repo