diff --git a/documentation/guides/migrating-from-v8-to-v9.md b/documentation/guides/migrating-from-v8-to-v9.md
index c0d09148896..73e5501cbf3 100644
--- a/documentation/guides/migrating-from-v8-to-v9.md
+++ b/documentation/guides/migrating-from-v8-to-v9.md
@@ -4,6 +4,42 @@ Polaris v9.0.0 ([full release notes](https://github.com/Shopify/polaris-react/re
 
 ## Theme provider
 
+## CSS Custom Properties
+
+CSS custom properties that were renamed can be replaced with the new CSS custom property name.
+
+|              Before               |               After                |
+| :-------------------------------: | :--------------------------------: |
+|      `--p-badge-font-weight`      |     `--p-font-weight-regular`      |
+|     `--p-button-font-weight`      |      `--p-font-weight-medium`      |
+|       `--p-duration-1-0-0`        |         `--p-duration-100`         |
+|       `--p-duration-1-5-0`        |         `--p-duration-150`         |
+|         `--p-card-shadow`         |         `--p-shadow-card`          |
+|       `--p-popover-shadow`        |        `--p-shadow-popover`        |
+|        `--p-modal-shadow`         |         `--p-shadow-modal`         |
+|       `--p-top-bar-shadow`        |        `--p-shadow-top-bar`        |
+|     `--p-button-drop-shadow`      |        `--p-shadow-button`         |
+|     `--p-button-inner-shadow`     |     `--p-shadows-inset-button`     |
+| `--p-button-pressed-inner-shadow` | `--p-shadows-inset-button-pressed` |
+|          `--p-icon-size`          |       `--p-icon-size-small`        |
+
+CSS custom properties that have been deprecated can be replaced with the CSS property value.
+
+|             Before              |          Value           |
+| :-----------------------------: | :----------------------: |
+|       `--p-override-none`       |          `none`          |
+|   `--p-override-transparent`    |      `transparent`       |
+|       `--p-override-one`        |           `1`            |
+|     `--p-override-visible`      |        `visible`         |
+|       `--p-override-zero`       |           `0`            |
+|     `--p-non-null-content`      |           `''`           |
+|   `--p-badge-mix-blend-mode`    |       `luminosity`       |
+| `--p-range-slider-thumb-scale`  |          `1.5`           |
+|       `--p-frame-offset`        |          `0px`           |
+| `--p-shadow-from-ambient-light` | `rgba(23, 24, 24, 0.05)` |
+| `--p-shadow-from-direct-light`  |  `rgba(0, 0, 0, 0.15)`   |
+|   `--p-shadow-from-dim-light`   |   `rgba(0, 0, 0, 0.2)`   |
+
 ## Removal of the public scss api
 
 Any functions that were being consumed from `build/styles/_public-api.scss` have been removed. The functions can be found in the following permalinks.