Version 12

This version introduces Shopify's new admin design language, refined tokens, aligned component APIs, and an updated Figma UI kit.
Illustration of a hand drawing a four pointed star

Upgrade to v12

Follow our migration guide to upgrade Polaris from v11 to v12.

What's changing

The design language

Polaris version 12 introduces a new design language for Shopify's admin. This includes a style uplift for all of our components, updates to our token values, and a new web font, Inter.

Pro design language

"Pro", in Shopify's context, refers to a design language that prioritizes efficiency and intuitive interactions, catering to the daily tasks merchants perform everyday.

  • Assign meaning: Visual language is clear for merchants.
  • Increase density: Space is optimized while maintaining high usability.
  • Craft juicy interactions: Interfaces incorporate a sense of realness.
  • Make it predictable: Objects with similar appearance share a common behavior.

Read more about Polaris' Pro design language to start designing in the new language.

Token refinement

The version 12 updates aim to create an intentional set of tokens that clearly communicates intent so that builders have exactly what they need to apply the new design language on their surfaces. To do this, v12 introduces primitive and semantic token layers.

For more information on how to migrate from v11 tokens, check out the migration guide.

Primitive tokens

Primitive tokens are generic keys for the base values of a token scale. Primitive tokens are not context dependent and can be used anywhere in the admin. For example, --p-space-100 is a primitive space token.

Semantic tokens

Semantic tokens are references to base values that are used in specific contexts within the admin. These tokens should never be used for anything other than the concept they’re referencing. When no semantic token is a good fit, a primitive token should be used instead. For example, --p-space-table-cell-padding is a semantic token.

Updated token resources

Component API simplification

The version 12 breaking component changes aim to simplify inconsistent and complicated component APIs. For a comprehensive list on all component changes and how to migrate from v11's component APIs, check out the migration guide.

At a high level the API changes aimed to simplify, consolidate, and align by:

  • Renaming directional components to use Inline and Block which are defined by CSS logical properties
  • Renaming border radius properties to align with CSS border radius constituent properties
  • Renaming various color control props to tone and space control props to gap. This creates more consistent APIs across components
  • Consolidating boolean props to a single variant prop on various components to make logical combinations more intentional

Figma UI Kit

The Polaris components, styles, and icons libraries have been updated to reflect the new design language, updated tokens, and component API changes.

Figma variables

The kits have been updated to use Figma variables for color, space, and size. Color variables are accessible via fill, stroke, and text color menus in the right panel. Space variables are accessible via auto layout's gap and padding.


    On this page