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).


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:

Initial beta release, update to early adopters who want to opt in12.0.0-beta.0July 26
Incremental beta releases12.0.0-beta.1
July – September
Polaris release with stable API, robust documentation and tooling12.0.0End of September

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:

npm install @shopify/polaris@beta

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

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.

<link rel="preconnect" href="" />
<link rel="preconnect" href="" crossorigin="anonymous" />
<link href=";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.


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.


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.


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

<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.

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


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
    - spacing='loose'
    + spacing={undefined}
    or for HorizontalStack
    - 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.


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:

ComponentBevel z-index
(children cannot be above this)

Net new component variants

<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.

Old tokenNew tokenExample usage
--p-spacing-5 (20px)--p-spacing-4 (16px)Padding in Card, gap between Card
<LegacyStack vertical spacing="loose"><LegacyStack vertical>Gap between Card
<Text variant="headingMd"><Text variant="headingSm">Any headings in Card
--p-font-size-100 (14px)--p-font-size-80-experimental (13px)Body font size
--p-color-icon-interactive--p-color-iconActionList icon
--p-border-width-1--p-border-width-1-experimentalInput border widths
--p-border-width-1--p-border-width-2-experimentalInput border width active states
--p-shadow-md--p-shadow-xsCard, TopBar, IndexTable, ResourceList, DataTable, EmptyState, FullscreenBar
--p-shadow-xl--p-shadow-mdPopover, DatePicker, Tooltip, ContextualSaveBar, OptionList
--p-shadow-2xl--p-shadow-2xlModal, Search bar
--p-shadow-inset-md--p-shadow-inset-mdActive/Selected basic Button, Secondary action
--p-shadow-none--p-shadow-noneTo remove shadow

Net new tokens

Token nameExample usage
--p-color-bg-backdrop-experimentalVideoThumbnail timestamp background
--p-color-bg-secondary-experimentalFilter Button background
--p-color-bg-input-hover-experimentalTextFields, Select, Checkbox, and DropZone hover state
--p-color-bg-input-active-experimentalTextFields, Select, and DropZone active state
--p-color-bg-transparent-experimentalPlain primary Button disabled state, and Tabs default state
--p-color-bg-transparent-subdued-experimentalNeutral Badge
--p-color-bg-transparent-hover-experimentalTabs hover state
--p-color-bg-transparent-active-experimentalTabs active state
--p-color-bg-transparent-disabled-experimentalTextFields, Select, DropZone, Button (default), Page secondary action, Pagination disabled state
--p-color-bg-transparent-secondary-disabled-experimentalCheckbox + RadioButton in a disabled state
--p-color-bg-transparent-primary-disabled-experimentalButton primary disabled (all primary button variants)
--p-color-bg-transparent-primary-experimental'Checkbox + RadioButton in a active, read only state
--p-color-bg-success-strong-hover-experimentalButton primary success hover state
--p-color-bg-success-strong-active-experimentalButton primary success active state
--p-color-bg-warning-subdued-experimentalBanner in Card with warning status, Badge with warning status
--p-color-bg-warning-strong-experimentalBanner title with warning status, Badge strong with warning status
--p-color-border-input-active-experimentalActive TextFields, Select, RadioButton, Checkbox, DropZone
--p-color-border-critical-strong-experimentalError state for TextFields, Select, Checkbox, DropZone
--p-color-text-warning-experimentalBadge and Banner with warning status
--p-color-text-critical-hover-experimentalButton plain destructive
--p-color-icon-info-strong-experimentalBanner with info status
--p-color-icon-warning-strong-experimentalBanner with warning status
--p-color-icon-success-strong-experimentalBanner with success status
--p-color-icon-critical-strong-experimentalBanner with critical status, Page secondary destructive actions, Button destructive (default, plain, & plain icon only)
--p-color-icon-critical-strong-hover-experimentalButton destructive plain + plain icon only
--p-color-icon-critical-strong-active-experimentalButton destructive plain + plain icon only
--p-color-avatar-background-experimentalAvatar default background color
--p-color-avatar-color-experimentalAvatar default icon color
--p-color-avatar-style-one-background-experimentalAvatar style one background color
--p-color-avatar-style-one-color-experimentalAvatar style one icon/text color
--p-color-avatar-style-two-background-experimentalAvatar style two background color
--p-color-avatar-style-two-color-experimentalAvatar style two icon/text color
--p-color-avatar-style-three-background-experimentalAvatar style three background color
--p-color-avatar-style-three-color-experimentalAvatar style three icon/text color
--p-color-avatar-style-four-background-experimentalAvatar style four background color
--p-color-avatar-style-four-color-experimentalAvatar style four icon/text color
--p-color-avatar-style-five-background-experimentalAvatar style five background color
--p-color-avatar-style-five-color-experimentalAvatar style five icon/text color
Token nameExample usage
--p-shadow-bevel-experimentalAn add-on shadow effect commonly paired with shadow-xs through to shadow-2xl
--p-shadow-button-experimentalBasic (default) Button default state
--p-shadow-button-disabled-experimentalBasic (default) Button disabled state
--p-shadow-button-primary-strong-inset-experimentalPrimary Button active/inset state
--p-shadow-button-primary-strong-hover-experimentalPrimary Button hover state
--p-shadow-button-primary-strong-experimentalPrimary Button default state
--p-shadow-button-primary-experimentalSuccess/Destructive primary Button default state
--p-shadow-button-primary-hover-experimentalSuccess/Destructive primary Button hover state
--p-shadow-button-inset-experimentalSuccess/Destructive primary Button active/inset state
--p-shadow-border-inset-experimentalThumbnail inset shadow
--p-shadow-button-hover-experimentalBasic (default) Button hover state
Token nameExample usage
--p-font-size-70-experimental (11px)TopBar user menu message
--p-font-size-80-experimental (13px)Body font size
--p-font-line-height-075-experimental (12px)Paired with --p-font-size-70-experimental
--p-font-letter-spacing-tightest-experimentalText variant heading3xl
--p-font-letter-spacing-tighter-experimentalText variant heading2xl
--p-font-letter-spacing-tight-experimentalText variant headingXl and headingLg
--p-font-letter-spacing-normal-experimentalSets letter spacing to 0
--p-font-weight-extra-semibold-experimental (650)Text variant headingLg
--p-font-family-sans-experimentalSets the font family to Inter
Token nameExample usage
--p-border-radius-1_5-experimental (6px)Avatar (medium + small), Thumbnail (extra small)
--p-border-width-1-experimental (.66px)TextField, Select, RadioButton, Checkbox, DropZone, search field
--p-border-width-2-experimental (1px)Table rows and active TextField, Select, RadioButton, Checkbox, DropZone, search field
Token nameExample usage
--p-space-150 (6px)Action list item vertical padding