From 25b45426804a5854da89131f858b94635cc9f322 Mon Sep 17 00:00:00 2001 From: Laura Griffee Date: Fri, 11 Feb 2022 15:00:54 -0700 Subject: [PATCH 1/3] Clarify language --- .../guides/migrating-from-v8-to-v9.md | 164 +++++++++--------- 1 file changed, 81 insertions(+), 83 deletions(-) diff --git a/documentation/guides/migrating-from-v8-to-v9.md b/documentation/guides/migrating-from-v8-to-v9.md index b4ffed52e9c..1367d2b443d 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 functions to your repo or replace any instances of them with their new 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,31 @@ 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 | +| 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 +212,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 +284,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 +316,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 +327,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 +338,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,7 +390,7 @@ 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 | +| Deprecated Function | Source | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `px()` | [definition](https://github.com/Shopify/polaris-react/blob/b443d114d447df15d9e72914c8ca5058439a175e/documentation/guides/legacy-polaris-v8-public-api.scss##L313-L331) | @@ -400,13 +398,13 @@ This function has been deprecated, but the definition can be copied and used loc 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 +487,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 +552,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 From 7025869e6f93c545bf55a882d540a7ec85c8c8ba Mon Sep 17 00:00:00 2001 From: Sam Rose Date: Fri, 11 Feb 2022 15:56:06 -0700 Subject: [PATCH 2/3] Minor noun casing adjustments to migration guide --- documentation/guides/migrating-from-v8-to-v9.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/documentation/guides/migrating-from-v8-to-v9.md b/documentation/guides/migrating-from-v8-to-v9.md index 1367d2b443d..91e2636e2ea 100644 --- a/documentation/guides/migrating-from-v8-to-v9.md +++ b/documentation/guides/migrating-from-v8-to-v9.md @@ -108,7 +108,7 @@ 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 need to either add the functions to your repo or replace any instances of them with their new CSS custom property or value equivalent. +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 the CSS custom property or value equivalent. ### Replacing function and mixin instances with value equivalents @@ -195,9 +195,10 @@ Otherwise, you can copy the function definition and use it locally. #### `em()` This function has been deprecated, but the definition can be copied and used locally. -| Deprecated 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()` @@ -390,9 +391,10 @@ 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. -| Deprecated 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()` From 4c56af6ababbcc50cf9424a0a6a67e34b154cfd6 Mon Sep 17 00:00:00 2001 From: Laura Griffee Date: Fri, 11 Feb 2022 16:13:57 -0700 Subject: [PATCH 3/3] Minor language tweak --- documentation/guides/migrating-from-v8-to-v9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/migrating-from-v8-to-v9.md b/documentation/guides/migrating-from-v8-to-v9.md index 91e2636e2ea..6cf5a2d363b 100644 --- a/documentation/guides/migrating-from-v8-to-v9.md +++ b/documentation/guides/migrating-from-v8-to-v9.md @@ -108,7 +108,7 @@ 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 need to either add the function or mixin to your repo or replace any instances of them with the CSS custom property or value equivalent. +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 value equivalents