border width tokens for outlines
Use var(--p-border-width-025) for standard outline width and var(--p-border-width-050) for focus outline width.
Shopify Polaris · all subjects
design-tokens
100 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
focus-ring replacement pattern
Instead of @include focus-ring, use the following pattern: &:focus { outline: var(--p-border-width-050) solid var(--p-color-border-focus); outline-offset: var(--p-space-050); }
focus border color token
Use var(--p-color-border-focus) for focus state outline color.
focus outline offset token
Use var(--p-space-050) for the outline-offset property in focus states.
high-contrast-outline at-rule deprecated
The @include high-contrast-outline() legacy Sass mixin is disallowed. Instead, use outline: var(--p-border-width-025) solid transparent;
focus-ring at-rule has no equivalent token yet
The @include focus-ring at-rule does not currently have an equivalent token or component. If necessary, add a stylelint ignore comment until Polaris provides a solution.
Use design tokens for border radius
Use var(--p-border-radius-200) and other design token variables instead of hard-coded rem or pixel values like 0.5rem for border-radius properties.
Use design tokens for border width
Use var(--p-border-width-050) and other design token variables instead of hard-coded pixel values like 2px for border-width properties.
Use CSS custom properties instead of color mixins
For icon fill color, use var(--p-color-icon-secondary) CSS custom property instead of the @include recolor-icon() mixin.
Disallow legacy color mixins in stylelint-polaris
The color/at-rule-disallowed-list rule disallows use of legacy color mixins. Instead of using @include recolor-icon(--p-text-secondary), use CSS custom properties like var(--p-color-icon-secondary) directly in the property value.
Use CSS custom properties for colors instead of hex values
When styling Polaris components, use CSS custom property variables (such as var(--p-color-text) for text color or var(--p-color-icon) for icon color) instead of writing hex color values directly (such as #202223 or #5c5f62).
Color variable naming convention
Polaris color variables follow the naming pattern var(--p-color-[purpose]-[state]). Examples include var(--p-color-text-disabled) for disabled text color and var(--p-color-bg-fill-inverse-hover) for inverse background fill color on hover.
Custom properties with --p- prefix must be valid Polaris tokens
When using the --p- prefix in custom property declarations, the property value must reference a valid Polaris token. For example, use var(--p-font-size-400) but not var(--p-fontsize-200).
Non-prefixed custom properties example: OSUI animation
Custom properties can be defined without Polaris prefixes when needed. For example, --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse; is valid.
Custom property prefixes allowed
Custom properties in Polaris must use one of three allowed prefixes: --p-, --pc-, or --polaris-version-. Properties not using these prefixes are allowed.
Private --pc- tokens should not be used in declarations
Declaration property values should not use private --pc-* tokens. Instead, use public --p-* tokens. For example, use var(--p-color-bg-fill-inverse) instead of var(--pc-button-color-depressed).
Motion duration design token usage
For transition duration in CSS, use the design token variable var(--p-motion-duration-200) instead of hardcoding a millisecond value like 200ms.
Correct shadow custom property syntax
Shadow custom properties should be used in box-shadow declarations using the syntax: box-shadow: var(--p-shadow-300);
Shadow custom property naming: use numbered scale not legacy names
Use the numbered shadow custom property scale like --p-shadow-300 instead of legacy named properties like --p-shadow-deep. The stylelint rule shadow/custom-property-disallowed-list enforces this by disallowing legacy shadow custom properties.
Use shadow design tokens instead of drop-shadow function
Polaris requires the use of shadow design tokens like var(--p-shadow-300) instead of built-in CSS shadow functions such as filter: drop-shadow(). The correct approach is to use CSS custom properties for shadows.
text-shadow property is disallowed
The text-shadow property is disallowed in Polaris. Instead of using text-shadow, ensure the text has proper contrast with the background so that it is readable without a shadow.
space/global-disallowed-list stylelint rule
The space/global-disallowed-list stylelint rule disallows the use of legacy spacing Sass APIs. Specifically, developers should not use `@type map $spacing-data: $polaris-spacing;`
Font-size token variable naming
Font-size design tokens follow the naming pattern var(--p-font-size-*) where * is a number like 300. For example: var(--p-font-size-300).
Line-height token variable naming
Line-height design tokens follow the naming pattern var(--p-font-line-height-*) where * is a number like 600. For example: var(--p-font-line-height-600).
z-index must use Polaris tokens, not numeric values
z-index declarations must use Polaris z-index tokens like var(--p-z-index-1) instead of numeric values like 1. This rule is enforced by the z-index/declaration-property-value-allowed-list stylelint rule in Polaris.
Correct z-index token syntax
The correct syntax for using z-index tokens in Polaris is var(--p-z-index-1) where the token name follows the pattern --p-z-index-[number].
Shadow token migration step 1: 20 token replacements
Shadow token migration step 1 maps 20 deprecated tokens. Examples: --p-shadow-inset-lg to --p-shadow-inset-200, --p-shadow-inset-md to --p-shadow-inset-200, --p-shadow-inset-sm to --p-shadow-inset-100, --p-shadow-none to --p-shadow-0, --p-shadow-xs to --p-shadow-100, --p-shadow-sm to --p-shadow-200, --p-shadow-md to --p-shadow-300, --p-shadow-lg to --p-shadow-400, --p-shadow-xl to --p-shadow-500, --p-shadow-2xl to --p-shadow-600, --p-shadow-bevel-experimental to --p-shadow-bevel-100, --p-shadow-card-sm-experimental to --p-shadow-100, --p-shadow-card-md-experimental to --p-shadow-200, --p-shadow-card-lg-experimental to --p-shadow-300, --p-shadow-button-experimental to --p-shadow-button, --p-shadow-button-hover-experimental to --p-shadow-button-hover, --p-shadow-button-disabled-experimental to inset 0 0 0 1px rgba(227, 227, 227, 1), --p-shadow-button-primary-strong-experimental to --p-shadow-button-primary, --p-shadow-button-primary-strong-inset-experimental to --p-shadow-button-primary-inset, --p-shadow-button-primary-strong-hover-experimental to --p-shadow-button-primary-hover, --p-shadow-border-inset-experimental to --p-shadow-border-inset.
Shadow token migration step 2: 3 context-dependent manual replacements
Shadow token migration step 2 requires manual context-dependent migration for 3 tokens: --p-shadow-button-primary-experimental has two options depending on context: --p-shadow-button-primary-critical or --p-shadow-button-primary-success; --p-shadow-button-primary-hover-experimental has two options: --p-shadow-button-primary-critical-hover or --p-shadow-button-primary-success-hover; --p-shadow-button-inset-experimental has two options: --p-shadow-button-primary-critical-inset or --p-shadow-button-primary-success-inset.
Space token migration: 16 token replacements
Space token migration maps 16 deprecated tokens to new values. Complete mapping: --p-space-05 to --p-space-050, --p-space-1 to --p-space-100, --p-space-1_5-experimental to --p-space-150, --p-space-2 to --p-space-200, --p-space-3 to --p-space-300, --p-space-4 to --p-space-400, --p-space-5 to --p-space-500, --p-space-6 to --p-space-600, --p-space-8 to --p-space-800, --p-space-10 to --p-space-1000, --p-space-12 to --p-space-1200, --p-space-16 to --p-space-1600, --p-space-20 to --p-space-2000, --p-space-24 to --p-space-2400, --p-space-28 to --p-space-2800, --p-space-32 to --p-space-3200.
Polaris tokens package: renamed utilities
In @shopify/polaris-tokens, two utilities were renamed: getCustomPropertyNames renamed to getThemeVarNames, createVar renamed to createVarName.
Polaris tokens package: deprecated types
The following types are deprecated in @shopify/polaris-tokens: BreakpointsAliasDirectionMediaConditions, BreakpointsMediaConditions, MetaBreakpointsTokenGroup, Tokens (replaced by Theme).
Polaris tokens package: all JSON exports deprecated
All JSON exports from @shopify/polaris-tokens are deprecated: @shopify/polaris-tokens/json/border.json, @shopify/polaris-tokens/json/breakpoints.json, @shopify/polaris-tokens/json/color.json, @shopify/polaris-tokens/json/font.json, @shopify/polaris-tokens/json/height.json, @shopify/polaris-tokens/json/motion.json, @shopify/polaris-tokens/json/shadow.json, @shopify/polaris-tokens/json/space.json, @shopify/polaris-tokens/json/text.json, @shopify/polaris-tokens/json/width.json, @shopify/polaris-tokens/json/zIndex.json. Instead, import themes and use JSON.stringify on the theme you need.
Polaris tokens package: tokens object replaced by useTheme hook
The tokens object should no longer be imported directly. Instead use the useTheme hook from @shopify/polaris to access token values. If direct access is needed, import defaultTheme from @shopify/polaris-tokens. Example: import {useTheme} from @shopify/polaris; const theme = useTheme(); access tokens via theme.space['100'] instead of tokens.space['1'].
Inter web font must be loaded for v12
The new design language uses the Inter web font. Polaris references this font but does not load it. Apps must load the font from Shopify CDN by adding link tags to the app's head element. The preconnect link should reference https://cdn.shopify.com/ and the stylesheet link should reference https://cdn.shopify.com/static/fonts/inter/v4/styles.css.
Polaris tokens package: deprecated utilities
The following utilities in @shopify/polaris-tokens are deprecated and should be copied from v11 if needed: createExact, createMetadata, getKeyframeNames, getUnit, isKeyOf, rem, removeMetadata, toEm, tokensToRems.
Polaris v12 border token replacements
Border tokens have been renamed: --p-border-radius-0-experimental to --p-border-radius-0, --p-border-radius-05 to --p-border-radius-050, --p-border-radius-1 to --p-border-radius-100, --p-border-radius-1_5-experimental to --p-border-radius-150, --p-border-radius-2 to --p-border-radius-200, --p-border-radius-3 to --p-border-radius-300, --p-border-radius-4 to --p-border-radius-400, --p-border-radius-5 to --p-border-radius-500, --p-border-radius-6 to --p-border-radius-750, --p-border-width-1 to --p-border-width-025, --p-border-width-1-experimental to --p-border-width-0165, --p-border-width-2 to --p-border-width-050, --p-border-width-2-experimental to --p-border-width-025, --p-border-width-3 to --p-border-width-050, --p-border-width-4 to --p-border-width-100, --p-border-width-5 to --p-border-width-100.
Polaris v12 color token migration is stepped
Color token migration in v12 must be run in 4 sequential steps due to overlapping token names and context-dependent manual migrations. Each step has specific token mappings and validation RegExp patterns.
Color token migration from v11 to v12: complete replacement table
A comprehensive table maps deprecated color custom properties to their v12 replacements. The table includes background color tokens (--p-color-bg-* family), text color tokens (--p-color-text-* family), border color tokens (--p-color-border-* family), icon color tokens (--p-color-icon-* family), and avatar color tokens. Examples: --p-color-bg replaced by --p-color-bg-surface, --p-color-text-subdued replaced by --p-color-text-secondary, --p-color-icon-interactive replaced by --p-color-icon-emphasis, --p-color-avatar-background-experimental replaced by --p-color-avatar-bg-fill. The complete mapping includes over 100 deprecated tokens with their exact replacement values.
Font token migration step 1: 8 token replacements
The font migration requires 4 sequential steps to avoid overlapping token names. Step 1 replacements: --p-font-size-70-experimental to --p-font-size-275, --p-font-size-80-experimental to --p-font-size-325, --p-font-size-100 to --p-font-size-350, --p-font-size-700 to --p-font-size-1000, --p-font-line-height-075-experimental to --p-font-line-height-300, --p-font-line-height-1 to --p-font-line-height-400, --p-font-line-height-2 to --p-font-line-height-500, --p-font-line-height-3 to --p-font-line-height-600, --p-font-line-height-4 to --p-font-line-height-700, --p-font-line-height-5 to --p-font-line-height-800, --p-font-line-height-6 to --p-font-line-height-1000, --p-font-line-height-7 to --p-font-line-height-1200.
Font token migration step 4: 2 token replacements
Step 4 of font migration: --p-font-size-75 replaced by --p-font-size-300, --p-font-size-200 replaced by --p-font-size-400.