Upgrade to v12
Follow our migration guide to upgrade Polaris from v11 to v12.
The design language
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.
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 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 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 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.