Beta access to Shopify's new design language

Polaris is developing version 12 for release in September. To help apps match Shopify's new design language, this version is available in an early beta. This beta will automatically update out-of-the-box/mainline Polaris components, with some additional work to update your custom components to seamlessly match Shopify's design. The steps below will assist you in making these updates using our tools and tokens.
You can access the beta now or simply wait for the stable release in September
(be sure to read 'what might break' below).

Timeline

The Polaris beta releases will continue until the stable public version 12, scheduled for the end of September. We may publish updates to the beta at key development milestones for your development and testing environments. Refer to the table below for the timeline of each milestone:

What might break during beta

We are actively developing this release and will continue to make breaking changes to the beta release until September. Our main areas of focus, listed below, will undergo significant changes. To ensure the best possible version 12, Polaris may also make breaking changes to other areas not yet listed.

Areas we are actively working on:

• Overall tokens system sense-check
• Shadow and bevel tokens
• Border color mappings
• Component props, deduplication, alignment, sense check
• The new web font integration
• Typography hierarchy mappings
• Documentation
• Migration tooling

Still want to dive in early?

We're excited about the new design language and understand if you want to quickly see how your app will look (particularly if you're applying to be a Built for Shopify app). Be aware that this is a beta and introduces changes that may break your app implementations, particularly custom styling. You will need to review your app's UI and manually patch fixes.

To prepare for Polaris version 12 make sure you're on the latest version 11. It's quick to update from v10 to v11 with our migrator tool and migration guide.

To install the v12 beta version run the following command:

Example
npm install @shopify/polaris@beta

Or, if you prefer yarn, use the following command instead:

Example
yarn add @shopify/polaris@beta

To assist you, we have prepared a collection of tips, documentation, and our own experience to help you on this early journey.

Design philosophy

• Hierarchy primarily through typography reduces cognitive load and makes the important content easier to find
• Using black and white reduces noise and ensures color is used for signifiers and affordances instead of as decoration instead of decoration
• Increased density enables a fuller picture of the task at hand
• Visual dimension clearly distinguishes layers of importance and interactive elements
• Delightful, tactile interactivity makes taking action feel powerful and gratifying

Read more about the design philosophy in the blog post Uplifting Shopify Polaris.

To see the new design language component by component, check out our Storybook. To turn the new design language on in Storybook go to: Addon panel (bottom) > Feature flags tab and Toggle polarisSummerEditions2023

Common UI updates and fixes to consider after upgrading to the Polaris beta

A new web font

The new design language comes with a web font called Inter via Google Fonts. The beta references this font but doesn't load it. This will come later.

Example
<link rel="preconnect" href="https://fonts.googleapis.com/" />
<link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900&display=swap" />

Heading size

The LegacyCard now also enforces that h1 and h2 content is headingSm (--p-font-size-80-experimental). If you want to use custom heading sizes, please refactor LegacyCard to Card.

Icons

Major and minor icon sizes are now identical. You may need to update custom icons in your app as they may look much larger than Polaris icons now. All icons still maintain the 20x20 viewbox.

Dividers

We removed dividers across Polaris components, most noticeably in Page and LegacyCard. We now recommend using spacing to create a visual hierarchy. If you must use a divider, use the Divider component to add them back in where needed.

Buttons

Primary buttons went from green to black in the new design language.

Example
<Button primarySuccess>It's not easy being green</Button>

Buttons beside inputs

Default buttons have decreased in height and no longer match the height of some inputs, namely TextField and Select. To get a buttons matching the height of input fields, use the large size by using the large size variant of Button.

Example
- <TextField connectedRight={<Button icon={DeleteMajor} />} />
+ <TextField connectedRight={<Button icon={DeleteMajor} size="large" />} />

LegacyCard

Spacing and visual hierarchy

The LegacyCard now has much tighter spacing and does not have dividers between sections and subsections. This may result in some visual hierarchy/padding issues depending on how your cards are composed. You can resolve this in a number of ways:

• recommended – Use Card and VerticalStack to compose a new card layout
• Remove any custom content spacing wrappers and use <LegacyCard.Section />, <LegacyCard.Header />, or <LegacyCard.Section flush /> instead. Issues involving a lack of top or bottom padding on the card is likely caused by this.
• Update all custom content padding using --p-space-500 to use --p-space-400. This includes content wrapped in a LegacyStack

  Example
  - spacing='loose'
  + spacing={undefined}

  or for HorizontalStack

  Example
  - gap='5'
  + gap='4'

• Add back dividers using Divider where needed
• As a last resort, you can add space with Box or remove space with Bleed.

Z-Index

The new design language introduces a shadow bevel in numerous components. The following component's children cannot be above the bevel's z-index elevation:

Net new component variants

Example
<Avatar size="xl-experimental" />
<Avatar size="2xl-experimental" />

<Badge status='info-strong-experimental' />
<Badge status='success-strong-experimental' />
<Badge status='warning-strong-experimental' />
<Badge status='critical-strong-experimental' />
<Badge status='attention-strong-experimental' />
<Badge status='read-only-experimental' />
<Badge status='enabled-experimental' />
<Button primarySuccess />
// not new variant but the styling is new
// Lots of card icons were updated to this variant from the non-primary variant
<Button icon={SomeIcon} primary plain />

Custom elements

Custom elements that were styled to look like the previous Polaris design language will need to be updated. Take the opportunity to put custom styles and components on mainline Polaris using our components and tokens. See a list of new tokens and the mapping our current tokens to our new once below.

CSS Specificity

Some overrides of Polaris styles may not have a high enough specificity anymore while our library uses a beta flag. For example, this has been seen in css overrides of icon color in Button. To resolve the issue, you can bump the specificity of an override class.

Token and API changes

Common token swaps

We've swapped out several different tokens across the board to create the new design language. If you're using these tokens in stylesheets or as component props, they may need to be updated to conform to the new language.

Net new tokens

Color

Shadow

Font

Border

Space