From 3ef047792e527124e722c9f9cdd4191177ab7e2e Mon Sep 17 00:00:00 2001 From: Laura Griffee Date: Fri, 26 May 2023 17:26:56 -0600 Subject: [PATCH 1/3] Create a tokens what's new page --- .../content/whats-new/version-11-tokens.md | 310 ++++++++++++++++++ 1 file changed, 310 insertions(+) create mode 100644 polaris.shopify.com/content/whats-new/version-11-tokens.md diff --git a/polaris.shopify.com/content/whats-new/version-11-tokens.md b/polaris.shopify.com/content/whats-new/version-11-tokens.md new file mode 100644 index 00000000000..869e7925b8f --- /dev/null +++ b/polaris.shopify.com/content/whats-new/version-11-tokens.md @@ -0,0 +1,310 @@ +--- +title: Version 11 Tokens +description: Crafting a more robust and cohesive token system in Polaris. +imageUrl: /images/updates/alias-tokens.png +keywords: + - tokens + - color + - colors + - depth + - shadow + - legacy + - motion + - shape + - border + - spacing + - space + - z-index +--- + +![Chart of new color token names and values](/images/updates/alias-tokens.png) + +--- + +## Why are we making changes? + +We are currently in the process of reworking our token values to give product teams more flexibility and leverage. Before Polaris v9, our tokens were difficult to reference and modify, which led many product teams to hard code their own values. After consolidating our tokens in Polaris v9 and v10, we're refining and evolving them in v11 to start aligning them with our new design vision. This includes removing tokens, renaming tokens/groups, and overhauling values. These changes will set our system up for implementing a more robust and cohesive token system in subsequent major versions. + +## What's changing + +### Colors ➡️ Color + +We completely overhauled our color token values, naming conventions, and architecture. Please read our [What’s New Version 11 Color](https://polaris.shopify.com/whats-new/version-11-color) section for more in depth information about these changes. + +_Find more in-depth information on migrating color tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#color)._ + +| Deprecated Token | Replacement Value | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--p-text-warning` | `--p-color-text-caution` | +| `--p-text-success` | `--p-color-text-success` | +| `--p-text-subdued-on-dark` | `--p-color-text-inverse-subdued` | +| `--p-text-subdued` | `--p-color-text-subdued` | +| `--p-text-primary-pressed` | `--p-color-text-primary` | +| `--p-text-primary-hovered` | `--p-color-text-primary-hover` | +| `--p-text-primary` | `--p-color-text-primary` | +| `--p-text-on-primary` | `--p-color-text-on-color` | +| `--p-text-on-interactive` | `--p-color-text-on-color` | +| `--p-text-on-dark` | `--p-color-text-inverse` | +| `--p-text-on-critical` | `--p-color-text-on-color` | +| `--p-text-highlight` | `--p-color-text-info` | +| `--p-text-disabled` | `--p-color-text-disabled` | +| `--p-text-critical` | `--p-color-text-critical` | +| `--p-text` | `--p-color-text` | +| `--p-surface-warning-subdued-pressed` | `--p-color-bg-caution-subdued-active` | +| `--p-surface-warning-subdued-hovered` | `--p-color-bg-caution-subdued-hover` | +| `--p-surface-warning-subdued` | `--p-color-bg-caution-subdued` | +| `--p-surface-warning` | `--p-color-bg-warning` | +| `--p-surface-success-subdued-pressed` | `--p-color-bg-success-subdued-active` | +| `--p-surface-success-subdued-hovered` | `--p-color-bg-success-subdued-hover` | +| `--p-surface-success-subdued ` | `--p-color-bg-success-subdued` | +| `--p-surface-success` | `--p-color-bg-success` | +| `--p-surface-subdued` | `--p-color-bg-subdued` | +| `--p-surface-selected-pressed` | `--p-color-bg-interactive-subdued-active` | +| `--p-surface-selected-hovered` | `--p-color-bg-interactive-subdued-hover` | +| `--p-surface-selected` | `--p-color-bg-interactive-selected` | +| `--p-surface-search-field-dark` | `--p-color-bg-inverse` | +| `--p-surface-search-field` | `--p-color-bg-inset` | +| `--p-surface-primary-selected-pressed` | `--p-color-bg-primary-subdued-active` | +| `--p-surface-primary-selected-hovered` | `--p-color-bg-primary-subdued-hover` | +| `--p-surface-primary-selected` | `--p-color-bg-primary-subdued-selected` | +| `--p-surface-pressed-dark` | `--p-color-bg-inverse-active` | +| `--p-surface-pressed` | `--p-color-bg-active` | +| `--p-surface-neutral-subdued-dark` | `--p-color-bg-inverse` | +| `--p-surface-neutral-subdued` | `--p-color-bg-subdued` | +| `--p-surface-neutral-pressed` | `--p-color-bg-strong-active` | +| `--p-surface-neutral-hovered` | `--p-color-bg-strong-hover` | +| `--p-surface-neutral-disabled` | `--p-color-bg-disabled` | +| `--p-surface-neutral` | `--p-color-bg-strong` | +| `--p-surface-hovered-dark` | `--p-color-bg-inverse-hover` | +| `--p-surface-hovered` | `--p-color-bg-hover` | +| `--p-surface-highlight-subdued-pressed` | `--p-color-bg-info-subdued-active` | +| `--p-surface-highlight-subdued-hovered` | `--p-color-bg-info-subdued-hover` | +| `--p-surface-highlight-subdued` | `--p-color-bg-info-subdued` | +| `--p-surface-highlight` | `--p-color-bg-info` | +| `--p-surface-disabled` | `--p-color-bg-disabled` | +| `--p-surface-depressed` | `--p-color-bg-inset` | +| `--p-surface-dark` | `--p-color-bg-inverse` | +| `--p-surface-critical-subdued-pressed` | `--p-color-bg-critical-subdued-active` | +| `--p-surface-critical-subdued-hovered` | `--p-color-bg-critical-subdued-hover` | +| `--p-surface-critical-subdued-depressed` | `--p-color-bg-critical` | +| `--p-surface-critical-subdued` | `--p-color-bg-critical-subdued` | +| `--p-surface-critical` | `--p-color-bg-critical` | +| `--p-surface-attention` | `--p-color-bg-caution` | +| `--p-surface` | `--p-color-bg` | +| `--p-shadow-color-picker-dragger` | `rgba(33, 43, 54, 0.32)` | +| `--p-shadow-color-picker` | `rgba(0, 0, 0, 0.5)` | +| `--p-overlay` | `rgba(255, 255, 255, 0.5)` | +| `--p-interactive-pressed-on-dark` | `--p-color-text-interactive-inverse` | +| `--p-interactive-pressed` | For `color` properties: `--p-color-text-interactive-active`
For `background` properties: `--p-color-bg-interactive-active`
For `border` properties: `--p-color-border-interactive-active`
For `fill` properties: `--p-color-icon-interactive-active` | +| `--p-interactive-on-dark` | `--p-color-text-interactive-inverse` | +| `--p-interactive-hovered` | For `color` properties: `--p-color-text-interactive-hover`
For `background` properties: `--p-color-bg-interactive-hover`
For `border` properties: `--p-color-border-interactive-hover`
For `fill` properties: `--p-color-icon-interactive-hover` | +| `--p-interactive-disabled` | For `color` properties: `--p-color-text-interactive-disabled`
For `background` properties: `--p-color-bg-interactive-disabled`
For `border` properties: `--p-color-border-interactive-disabled`
For `fill` properties: `--p-color-icon-interactive-disabled` | +| `--p-interactive-critical-pressed` | `--p-color-text-critical-active` | +| `--p-interactive-critical-hovered` | `--p-color-bg-critical-strong-hover` | +| `--p-interactive-critical-disabled` | `--p-color-text-disabled` | +| `--p-interactive-critical` | For `color` properties: `--p-color-text-critical`
For `background` properties: `--p-color-bg-critical`
For `border` properties: `--p-color-border-critical`
For `fill` properties: `--p-color-icon-critical` | +| `--p-interactive` | For `color` properties: `--p-color-text-interactive`
For `background` properties: `--p-color-bg-interactive`
For `border` properties: `--p-color-border-interactive`
For `fill` properties: `--p-color-icon-interactive` | +| `--p-icon-warning` | `--p-color-icon-caution` | +| `--p-icon-success` | `--p-color-icon-success` | +| `--p-icon-subdued` | `--p-color-icon-subdued` | +| `--p-icon-pressed` | `--p-color-icon-active` | +| `--p-icon-on-primary` | `--p-color-icon-on-color` | +| `--p-icon-on-interactive` | `--p-color-icon-on-color` | +| `--p-icon-on-dark` | `--p-color-icon-inverse` | +| `--p-icon-on-critical` | `--p-color-icon-on-color` | +| `--p-icon-hovered` | `--p-color-icon-hover` | +| `--p-icon-highlight` | `--p-color-icon-info` | +| `--p-icon-disabled` | `--p-color-icon-disabled` | +| `--p-icon-critical` | `--p-color-icon-critical` | +| `--p-icon-attention` | `--p-color-icon-caution` | +| `--p-icon` | `--p-color-icon` | +| `--p-hint-from-direct-light` | `rgba(0, 0, 0, 0.15)` | +| `--p-focused` | `--p-color-border-interactive-focus` | +| `--p-divider-dark` | `--p-color-border-inverse` | +| `--p-divider` | `--p-color-border-subdued` | +| `--p-decorative-two-text` | `rgba(73, 11, 28, 1)` | +| `--p-decorative-two-surface` | `rgba(255, 196, 176, 1)` | +| `--p-decorative-two-icon` | `rgba(175, 41, 78, 1)` | +| `--p-decorative-three-text` | `rgba(0, 47, 25, 1)` | +| `--p-decorative-three-surface` | `rgba(146, 230, 181, 1)` | +| `--p-decorative-three-icon` | `rgba(0, 109, 65, 1)` | +| `--p-decorative-one-text` | `rgba(61, 40, 0, 1)` | +| `--p-decorative-one-surface` | `rgba(255, 201, 107, 1)` | +| `--p-decorative-one-icon` | `rgba(126, 87, 0, 1)` | +| `--p-decorative-four-text` | `rgba(0, 45, 45, 1)` | +| `--p-decorative-four-surface` | `rgba(145, 224, 214, 1)` | +| `--p-decorative-four-icon` | `rgba(0, 106, 104, 1)` | +| `--p-decorative-five-text` | `rgba(79, 14, 31, 1)` | +| `--p-decorative-five-surface` | `rgba(253, 201, 208, 1)` | +| `--p-decorative-five-icon` | `rgba(174, 43, 76, 1)` | +| `--p-border-warning-subdued` | `--p-color-border-caution-subdued` | +| `--p-border-warning` | `--p-color-border-caution` | +| `--p-border-success-subdued` | `--p-color-border-success-subdued` | +| `--p-border-success` | `--p-color-border-success` | +| `--p-border-subdued` | `--p-color-border-subdued` | +| `--p-border-shadow-subdued` | `--p-color-border-input` | +| `--p-border-shadow` | `--p-color-border-input` | +| `--p-border-on-dark` | `--p-color-border-inverse` | +| `--p-border-neutral-subdued` | `--p-color-border-strong` | +| `--p-border-hovered` | `--p-color-border-hover` | +| `--p-border-highlight-subdued` | `--p-color-border-info-subdued` | +| `--p-border-highlight` | `--p-color-border-info` | +| `--p-border-disabled` | `--p-color-border-disabled` | +| `--p-border-depressed` | `--p-color-border-inverse` | +| `--p-border-critical-subdued` | `--p-color-border-critical-subdued` | +| `--p-border-critical-disabled` | `--p-color-border-disabled` | +| `--p-border-critical` | `--p-color-border-critical` | +| `--p-border` | `--p-color-border` | +| `--p-background-selected` | `--p-color-bg-app-selected` | +| `--p-background-pressed` | `--p-color-bg-app-active` | +| `--p-background-hovered` | `--p-color-bg-app-hover` | +| `--p-background` | `--p-color-bg-app` | +| `--p-backdrop` | `rgba(0, 0, 0, 0.5)` | +| `--p-action-secondary-pressed-dark` | `--p-color-bg-inverse-active` | +| `--p-action-secondary-pressed` | `--p-color-bg-subdued-active` | +| `--p-action-secondary-hovered-dark` | `--p-color-bg-inverse-hover` | +| `--p-action-secondary-hovered` | `--p-color-bg-subdued-hover` | +| `--p-action-secondary-disabled` | `--p-color-bg-disabled` | +| `--p-action-secondary-depressed` | `--p-color-bg-inset-strong` | +| `--p-action-secondary` | `--p-color-bg-subdued` | +| `--p-action-primary-pressed` | `--p-color-bg-primary-active` | +| `--p-action-primary-hovered` | `--p-color-bg-primary-hover` | +| `--p-action-primary-disabled` | `--p-color-bg-disabled` | +| `--p-action-primary-depressed` | `--p-color-bg-primary-active` | +| `--p-action-primary` | For `color` properties: `--p-color-text-primary`
For `background` properties: `--p-color-bg-primary`
For `border` properties: `--p-color-border-primary`
For `fill` properties: `--p-color-icon-primary` | +| `--p-action-critical-pressed` | `--p-color-bg-critical-strong-active` | +| `--p-action-critical-hovered` | `--p-color-bg-critical-strong-hover` | +| `--p-action-critical-disabled` | `--p-color-bg-disabled` | +| `--p-action-critical-depressed` | `--p-color-bg-critical-strong-active` | +| `--p-action-critical` | `--p-color-bg-critical-strong` | + +### Depth ➡️ Shadow + +We reworked our shadow values so that they have a more consistent scale and higher contrast. We also updated the token group name to improve clarity. + +_Find more in-depth information on migrating shadow tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#shadow)._ + +| Deprecated Token | Replacement Value | +| ---------------------------------- | --------------------- | +| `--p-shadow-transparent` | `--p-shadow-none` | +| `--p-shadow-faint` | `--p-shadow-sm` | +| `--p-shadow-base` | `--p-shadow-md` | +| `--p-shadow-deep` | `--p-shadow-md` | +| `--p-shadow-button` | `--p-shadow-sm` | +| `--p-shadow-top-bar` | `--p-shadow-sm` | +| `--p-shadow-card` | `--p-shadow-md` | +| `--p-shadow-popover` | `--p-shadow-xl` | +| `--p-shadow-layer` | `--p-shadow-2xl` | +| `--p-shadow-modal` | `--p-shadow-2xl` | +| `--p-shadows-inset-button` | `--p-shadow-none` | +| `--p-shadows-inset-button-pressed` | `--p-shadow-inset-md` | + +### Legacy + +We removed this token group since these tokens do not fit into our new design vision. + +_Find more in-depth information on migrating legacy tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#legacy)._ + +| Deprecated Token | Replacement Value | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--p-override-loading-z-index` | `--p-z-index-6` | +| `--p-choice-size` | `20px` / `1.25rem` | +| `--p-icon-size-small` | `8px` / `0.5rem` | +| `--p-icon-size-medium` | `20px` / `1.25rem` | +| `--p-choice-margin` | `--p-space-025` | +| `--p-control-border-width` | `--p-border-width-2` | +| `--p-banner-border-default` | `inset 0 var(--p-border-width-1) 0 0 var(--p-color-border-strong), inset 0 0 0 (--p-border-width-1) var(--p-color-border-strong)` | +| `--p-banner-border-success` | `inset 0 var(--p-border-width-1) 0 0 var(--p-color-border-success-subdued), inset 0 0 0 (--p-border-width-1) var(--p-color-border-success-subdued)` | +| `--p-banner-border-highlight` | `inset 0 var(--p-border-width-1) 0 0 var(--p-color-border-info-subdued), inset 0 0 0 (--p-border-width-1) var(--p-color-border-info-subdued)` | +| `--p-banner-border-warning` | `inset 0 var(--p-border-width-1) 0 0 var(--p-color-border-caution-subdued), inset 0 0 0 (--p-border-width-1)var(--p-color-border-caution-subdued)` | +| `--p-banner-border-critical` | `inset 0 var(--p-border-width-1) 0 0 var(--p-color-border-critical-subdued), inset 0 0 0 (--p-border-width-1) var(--p-color-border-critical-subdued)` | +| `--p-thin-border-subdued` | `var(--p-border-width-1) solid var(--p-color-border-subdued)` | +| `--p-text-field-spinner-offset` | `2px` / `0.125rem` | +| `--p-text-field-focus-ring-offset` | `-4px` / `-0.25rem` | +| `--p-button-group-item-spacing` | `calc(-1 * var(--p-space-025))` | +| `--p-range-slider-thumb-size-base` | `16px` / `1rem` | +| `--p-range-slider-thumb-size-active` | `24px` / `1.5rem` | +| `--p-frame-offset` | `0` | + +### Motion + +We added a “motion” prefix to all token names to ensure consistency with other token group naming conventions. + +_Find more in-depth information on migrating motion tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#motion)._ + +| Deprecated Token | Replacement Value | +| ---------------------------- | ----------------------------------- | +| `--p-linear` | `--p-motion-linear` | +| `--p-ease-in-out` | `--p-motion-ease-in-out` | +| `--p-ease-out` | `--p-motion-ease-out` | +| `--p-ease-in` | `--p-motion-ease-in` | +| `--p-ease` | `--p-motion-ease` | +| `--p-duration-0` | `--p-motion-duration-0` | +| `--p-duration-50` | `--p-motion-duration-50` | +| `--p-duration-100` | `--p-motion-duration-100` | +| `--p-duration-150` | `--p-motion-duration-150` | +| `--p-duration-200` | `--p-motion-duration-200` | +| `--p-duration-250` | `--p-motion-duration-250` | +| `--p-duration-300` | `--p-motion-duration-300` | +| `--p-duration-350` | `--p-motion-duration-350` | +| `--p-duration-400` | `--p-motion-duration-400` | +| `--p-duration-450` | `--p-motion-duration-450` | +| `--p-duration-500` | `--p-motion-duration-500` | +| `--p-duration-5000` | `--p-motion-duration-5000` | +| `--p-keyframes-bounce` | `--p-motion-keyframes-bounce` | +| `--p-keyframes-fade-in` | `--p-motion-keyframes-fade-in` | +| `--p-keyframes-pulse` | `--p-motion-keyframes-pulse` | +| `--p-keyframes-spin` | `--p-motion-keyframes-spin` | +| `--p-keyframes-appear-above` | `--p-motion-keyframes-appear-above` | +| `--p-keyframes-appear-below` | `--p-motion-keyframes-appear-below` | + +### Shape ➡️ Border + +We removed border values that no longer fit into our new design vision. We also updated the token group name to improve clarity. + +_Find more in-depth information on migrating border tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#border)._ + +| Deprecated Token | Replacement Value | +| ---------------------------- | ------------------------------------------------------------- | +| `--p-border-radius-base` | `--p-border-radius-1` | +| `--p-border-radius-large` | `--p-border-radius-2` | +| `--p-border-radius-half` | `--p-border-radius-full` | +| `--p-border-base` | `var(--p-border-width-1) solid var(--p-color-border-subdued)` | +| `--p-border-dark` | `var(--p-border-width-1) solid var(--p-color-border)` | +| `--p-border-transparent` | `var(--p-border-width-1) solid transparent` | +| `--p-border-divider` | `var(--p-border-width-1) solid var(--p-color-border-subdued)` | +| `--p-border-divider-on-dark` | `var(--p-border-width-1) solid var(--p-color-border-inverse)` | + +### Spacing ➡️ Space + +We updated the token group name to ensure consistency between token groups. + +### Z-index + +We changed the token name prefix from “z” to “z-index” to improve naming clarity. + +_Find more in-depth information on migrating z-index tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#z-index)._ + +| Deprecated Token | Replacement Value | +| ---------------- | ----------------- | +| `--p-z-1` | `--p-z-index-1` | +| `--p-z-2` | `--p-z-index-2` | +| `--p-z-3` | `--p-z-index-3` | +| `--p-z-4` | `--p-z-index-4` | +| `--p-z-5` | `--p-z-index-5` | +| `--p-z-6` | `--p-z-index-6` | +| `--p-z-7` | `--p-z-index-7` | +| `--p-z-8` | `--p-z-index-8` | +| `--p-z-9` | `--p-z-index-9` | +| `--p-z-10` | `--p-z-index-10` | +| `--p-z-11` | `--p-z-index-11` | +| `--p-z-12` | `--p-z-index-12` | + +## What’s next? + +We plan to continue refining and evolving our token system to better align with our design vision and provide more flexibility for product teams. This will include further consolidating and streamlining token groups, as well as introducing new tokens to support emerging design patterns and use cases. + +## Resources + +- [Tokens](https://polaris.shopify.com/tokens) +- [What’s New Version 11 Color](https://polaris.shopify.com/whats-new/version-11-color) From 576ee253c9dad5f3d18e2f608ec40ab39934b369 Mon Sep 17 00:00:00 2001 From: Laura Griffee Date: Fri, 26 May 2023 17:31:26 -0600 Subject: [PATCH 2/3] Add changeset --- .changeset/friendly-candles-raise.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/friendly-candles-raise.md diff --git a/.changeset/friendly-candles-raise.md b/.changeset/friendly-candles-raise.md new file mode 100644 index 00000000000..b2a49268c28 --- /dev/null +++ b/.changeset/friendly-candles-raise.md @@ -0,0 +1,5 @@ +--- +'polaris.shopify.com': minor +--- + +Created a "What's new" page for v11 token changes. From 86d9f26411523966f6fe153ea4ee748ac0c06060 Mon Sep 17 00:00:00 2001 From: Laura Griffee Date: Tue, 30 May 2023 10:22:58 -0600 Subject: [PATCH 3/3] Tweak wording --- polaris.shopify.com/content/whats-new/version-11-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/polaris.shopify.com/content/whats-new/version-11-tokens.md b/polaris.shopify.com/content/whats-new/version-11-tokens.md index 869e7925b8f..8127b05910b 100644 --- a/polaris.shopify.com/content/whats-new/version-11-tokens.md +++ b/polaris.shopify.com/content/whats-new/version-11-tokens.md @@ -29,7 +29,7 @@ We are currently in the process of reworking our token values to give product te ### Colors ➡️ Color -We completely overhauled our color token values, naming conventions, and architecture. Please read our [What’s New Version 11 Color](https://polaris.shopify.com/whats-new/version-11-color) section for more in depth information about these changes. +We completely overhauled our color token values, naming conventions, and architecture. Please read our [What’s New Version 11 Color](https://polaris.shopify.com/whats-new/version-11-color) section for more detailed information about these changes. _Find more in-depth information on migrating color tokens from v10 to v11 in our [migration guide](https://github.com/Shopify/polaris/blob/main/documentation/guides/migrating-from-v10-to-v11.md#color)._