Don't: use color to decorate or distract
Color should not be used to decorate or to distract merchants from performing tasks.
Shopify Polaris · all subjects
design-tokens
100 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Black and white interface creates neutral backdrop for color impact
The Shopify admin interface uses a black and white color scheme intentionally to create a neutral backdrop. This monochromatic design causes elements that incorporate color to gain heightened visual impact and prominence.
Do: use strong, vivid colors to grab attention for important matters
Use strong, vivid colors to grab attention to things that matter most, such as critical unsaved changes or important alerts.
Don't: diminish messaging with subdued or grayscale colors
Do not contradict or diminish messaging by using subdued colors or grayscale, especially for important communications.
Color purpose in Polaris: must support message or status
Color usage in Polaris must have a clear purpose. Each use of color is tied to a specific meaning: red signifies critical errors, green represents success messages, and blue draws attention to tips and offers. Color must support identifying important information, not be used as decoration (decoration is exclusive to illustration).
Color role specificity: red for errors, green for success, blue for tips and offers
In the Shopify admin, red signifies critical errors, green represents success messages, and blue is used to draw attention to tips and offers.
Do: use color to support different states merchants need to know about
Color should be used to display and communicate different states that merchants need to be informed about, such as paid, fulfilled, in progress, partially paid, or unfulfilled states.
Link color usage in text
Link color is used exclusively for text links that appear in lines and paragraphs of text. Link color follows the same logic as text color: it can only be used with its corresponding background or surface colors in the same color role, but can generally be used on any other background or surface if contrast is sufficient. Use link color for text links and text links that include icons. Link color can be used to style text buttons as an alternative to using the appropriate color role and component.
Icon color usage for standalone icons
Icon colors are used exclusively for standalone icons. These colors are tailored to meet color contrast ratios for interactive elements that do not include text. Icon colors should only be used on their corresponding background and surface colors but can generally be used on any other background or surface if contrast is sufficient. Use icon colors to style an icon that is standalone. Do not use icon colors to style text, as the color contrast might not be sufficient; instead style the entire icon and text composition using the text color.
Combining different color roles
Elements with different color roles can coexist alongside each other, enhancing merchants' comprehension of complex patterns when appropriately utilized in component combinations. In some cases, the superposition of elements with different color roles is necessary, like using a critical icon button on a default card. These combinations may require additional testing to check for proper color contrast. Meaningful combinations of color roles can enhance a merchant's experience. Avoid creating color role combinations that look too jarring or that create visual competition between elements.
Colors outside color roles are for illustration only
The creation of new color roles is tied to the Shopify admin. Some colors available in the color palette are not yet tied to a color role. Usage of these colors is strictly reserved for illustration work. In illustrations, any color of the color palette can be used. Diagrams, however, need to respect color role usage if they represent an abstracted view of the admin.
Disabled color scheme consistency
Some elements may require a disabled state. The color scheme for disabled elements is intentionally consistent throughout the admin interface, generally avoiding the use of distinct colors for each color role. Use the disabled color scheme for disabled elements. Do not use opacity or any other means to communicate disabled states.
Color relationships define UI usage
Color relationships between UI concepts define how color is used in the Shopify admin. While color roles define the value of each concept of UI that the color styles, the relationships between these concepts determine the overall color usage pattern.
Background color usage rules
Background colors are used as the baseline of all UI in the admin. Background colors can only have other elements of any other color except for other background colors above them. Multiple background colors can exist in the same viewport only if they exist side by side. Background colors should always be used in every admin interface but should not be applied to surfaces or individual elements.
Surface color usage and hierarchy
Surface colors are the background color for elements with the highest level of prominence, like a card or a banner. Surface colors are the most versatile in the color system and can have many elements sit on top of them to create complex components and patterns. Surface colors come with various hierarchical levels and can be used to increase or decrease emphasis on specific areas of the UI. Use surface colors for all surfaces including cards, tables, banners, and modals. Do not mix multiple color role surfaces in the same component, as this creates jarring color combinations when nesting components.
Fill color purpose and constraints
Fill is the background color for elements with a smaller surface area like a button or a badge. Fills are usually the most vibrant color in an interface and sit on backgrounds and surfaces, sometimes sitting on top of other fills. Fills come with their explicit text and icon colors called 'on-fill'. Use fills on smaller surface areas and on elements that pull a merchant's attention. Do not use fills on large components or as backgrounds for entire interfaces. Do not mix fills with text colors that are not 'on-fill', as these combinations might not pass minimum contrast ratio requirements.
Border color usage for data organization
Borders are used primarily in data tables to enhance visual structure and organization of large amounts of information. They visually separate and contain elements and can be used to delineate rows or define the space of nested tables. Use borders for tables and divided surfaces that look like tables to make data easier to read. Use borders when a data table is nested within a card. Do not use borders to delineate information sections; instead check the 'Dividing surfaces' guidance.
Text color accessibility and on-fill constraint
Text color can be used on any text element and any icon element that accompanies text. Text colors are designed to be fully accessible in terms of contrast on their corresponding backgrounds and surfaces and should only be used in tandem with them, but can generally be used on any other background or surface if contrast is sufficient. Text color that exists on a fill has its own 'on-fill' color. This relationship is strict and 'on-fill' text can only be used on its corresponding 'fill' color. Do not use text 'on-fill' colors on anything else but its corresponding fill color. Use text color to create visual hierarchy by using default, secondary, or tertiary role colors when available. Do not use any other color except for text colors for any text that is part of the UI.
Use consistent shadow and bevel styles
Use consistent shadow and bevel styles across the interface to maintain visual harmony and make the interface feel more cohesive. Do not use different styles for similar elements, as this can confuse merchants about the hierarchy and interactivity of the elements.
Shadows and bevels indicate interactivity
Shadows and bevels create the illusion that an element is raised above the rest of the interface, indicating that it's interactive or important. Use shadows and bevels to indicate important interactions, making buttons and other important interactive elements appear more tactile, obvious, and inviting to click.
Avoid overusing shadows and bevels
Do not overuse shadows or bevels, as they will make the interface look cluttered and confusing. Shadows and bevels are meant to be used sparingly and consistently.
Decrease brightness when element is pushed down in Z index
Decrease the brightness of an element when it's being pushed down in the Z index. When a button is pressed, it goes down and should appear darker.
Increase brightness when element is pushed up in Z index
Increase the brightness of an element when it's being pushed up in the Z index. When a page is active, it goes up and should appear brighter.
Layering to organize interface and guide focus
Use layering to organize the interface and guide merchant focus. Higher layers should be used for more important or interactive elements. Keep most elements on the same layer to establish a visual baseline, and allow for purposeful use of layering, when necessary, to denote importance or interactivity.
Avoid too many layers on one screen
Do not use too many layers in one screen, as it can confuse merchants and make the interface difficult to navigate.
Layering not the primary tool for emphasis
Do not resort to layering as the initial tool for emphasis. Explore other visual techniques first to highlight elements without disrupting the layering system.
Use gray background to de-emphasize contained information
Use a gray background to de-emphasize contained information. This will divert merchants' attention towards more important information, as the muted background visually recedes, pushing the contained content into the background.
Avoid bright colors for container backgrounds
Do not use bright or contrasting colors for container backgrounds or borders. This distracts merchants from the main content and creates a cluttered UI.
Avoid unique styles for surfaces like inset shadows
Do not use unique styles for surfaces, like inset shadows. This makes the interface noisy and creates confusing information hierarchy.
Shadows and layering create visual hierarchy
Use a combination of shadows and layering to create a sense of realism and hierarchy in the interface, guiding merchants' attention and indicating interactivity.
Component-specific shadow tokens
Components such as buttons require component-specific shadow tokens to visually exhibit their unique tactility. Component-specific shadow tokens are assigned to each variant of the button. These tokens reside in a separate token collection and should only be utilized for the specific component they are named after.
Shadow token pairing pattern
When combining the bevel token with elevation tokens, builders can achieve a desired visual distinction necessary to create contrast between an elevated surface and its background. The bevel token adds dimensionality to the element, while elevation tokens provide a drop shadow effect that creates the perception of distance. To implement this pairing, assign the bevel token as a pseudo class with absolute positioning and set the mix-blend-mode CSS property to luminosity to create the desired effect.
Shadow token pairing implementation code
The following Sass code demonstrates token pairing implementation: position: relative; box-shadow: $boxShadow; border-radius: $borderRadius; border: $border; &::before { content: $content; position: absolute; top: 0; left: 0; right: 0; bottom: 0; z-index: $zIndex; box-shadow: var(--p-shadow-bevel-100); border-radius: $borderRadius; pointer-events: none; mix-blend-mode: luminosity; }
Polaris component shadow token assignments
The following Polaris components use these shadow tokens: Account connection, Card, Data table, Empty states, Fullscreen bar, Index table, Media card, Resource list, Setting toggle, Top bar: --p-shadow-100, --p-shadow-bevel-100 Banner, Callout card: --p-shadow-200, --p-shadow-bevel-100 Action list, Option list, Color picker, Date picker, Popover, Tooltip: --p-shadow-300, --p-shadow-bevel-100 Toast: --p-shadow-400, --p-shadow-bevel-100 Modal: --p-shadow-600, --p-shadow-bevel-100 Search: --p-shadow-600
Shadow token scales: elevation, inset, and bevel
Primitive shadow tokens are categorized into three sets. Elevation tokens visually represent a shadow being cast on a surface below the element, simulating elevation. Inset tokens demonstrate an inner shadow creating the impression of an embedded element. Bevel tokens provide a dimensional appearance to an element, enhancing its perceived shape and structure.
Shadow token structure and scale
Shadow tokens are declared with the shadow token group name. The scales offer comprehensive ranges in increments of 100, and the base value is set at 100.
Interaction states definition and purpose
Interaction states communicate the status of an element in the interface, establish confidence once an action is taken, and suggest the ability (or inability) to interact with the element.
Interaction states design principle: keep things consistent
Consistent treatments for interaction feedback create recognizable patterns. If an interaction produces different feedback across the Shopify admin, it deteriorates the integrity of the pattern and risks confusing merchants.
Hidden signifiers for interaction states
Hidden signifiers reveal clues only when the merchant interacts with the element, such as hovering or using tab navigation to see if a button is clickable.
Negative signifiers for interaction states
Negative signifiers show that an action appears inactive (like a grayed out button that doesn't respond to hover) because it isn't available for the merchant to use.
Explicit signifiers for interaction states
Explicit signifiers direct merchants to do the intended action through content, such as 'Sort' or 'Save' text on buttons.
Interaction states design principle: be subtle but clear
Successful interaction feedback is informative, not decorative. Avoid elaborate transitions that create visual noise or intense color changes. Distracting animation can create disturbance and make an interface unpleasant to use.
Pro design language definition
Pro is a design language that prioritizes efficiency and intuitive interactions, catering to daily merchant tasks. It uses space efficiently to allow merchants to view more data at once, avoids verbosity, and makes the interface action-driven with intuitive icons for swift navigation. It combines motion, color, and depth to create a responsive and dynamic interface with clear affordances.
Color meaning in Pro design language
Strong meaning is associated with color use in the Pro design language. Red means danger, green means go. Color roles are heightened in the interface and add a layer of detail that merchants can quickly understand and master.
Figma design resources available
Shopify provides Figma community resources for Polaris including a Component UI kit, Style Library, and Icon Library. The Component UI kit is at https://www.figma.com/community/file/1293611962331823010/polaris-components, the Style Library is at https://www.figma.com/community/file/1293614121185734569/polaris-styles, and the Icon Library is at https://www.figma.com/community/file/1293614863849914283/polaris-icons.
Semantic tokens definition
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 are referencing. When no semantic token is a good fit, a primitive token should be used instead. Example: --p-space-table-cell-padding is a semantic token.
Pro design language principles
The Pro design language in Polaris prioritizes efficiency and intuitive interactions for daily merchant tasks. Its core principles are: 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), and Make it predictable (objects with similar appearance share common behavior).
Primitive tokens definition
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. Example: --p-space-100 is a primitive space token.
Line height token values
Line height tokens and their values: | New token | Value | Old token | Old value | |---|---|---|---| | --p-line-height-1 | 16 | --p-font-line-height-1 | 16 | | --p-line-height-2 | 20 | --p-font-line-height-2 | 20 | | --p-line-height-3 | 24 | --p-font-line-height-3 | 24 | | --p-line-height-4 | 28 | --p-font-line-height-4 | 28 | | --p-line-height-5 | 32 | --p-font-line-height-5 | 32 | | --p-line-height-6 | 40 | --p-font-line-height-6 | 36 | | --p-line-height-7 | 48 | --p-font-line-height-7 | 44 |
Font size token naming convention updated
Font size tokens now use increments of 100 for variants: --p-font-size-75 (12px), --p-font-size-100 (14px, base), --p-font-size-200 (16px), --p-font-size-300 (20px), --p-font-size-400 (24px), --p-font-size-500 (32px), --p-font-size-600 (28px), --p-font-size-700 (40px). This numeric system allows for easy extension above and below the base.
Font size token migration table
Font size tokens mapping: | New token | Old token | px value | rem value | |---|---|---|---| | --p-font-size-75 | --p-font-size-1 | 12 | 0.75 | | - | --p-font-size-2 | 13 | 0.8125 | | --p-font-size-100 | --p-font-size-3 | 14 | 0.875 | | - | --p-font-size-4 | 15 | 0.9375 | | --p-font-size-200 | --p-font-size-5 | 16 | 1 | | - | --p-font-size-6 | 17 | 1.0625 | | --p-font-size-300 | --p-font-size-7 | 20 | 1.25 | | - | --p-font-size-8 | 21 | 1.3125 | | --p-font-size-400 | --p-font-size-9 | 24 | 1.50 | | - | --p-font-size-10 | 26 | 1.625 | | - | --p-font-size-11 | 27 | 1.6875 | | --p-font-size-600 | --p-font-size-12 | 28 | 1.75 | | --p-font-size-500 | - | 32 | 2 | | --p-font-size-700 | - | 40 | 2.5 |
Tokens definition and purpose
Tokens are variables that represent design decisions such as color, typography, and spacing, in a consistent and reusable way.
Tokens documentation location
Tokens are documented in the Polaris design system with order priority 8, an eye dropper icon, and a table of contents navigation component.
How to import breakpoint media query Sass variables
To use breakpoint media query Sass variables in your project, import the media-queries.scss file from @shopify/polaris-tokens: @import 'path/to/node_modules/@shopify/polaris-tokens/dist/scss/media-queries';
Mobile-first design strategy recommended for breakpoints
Polaris encourages developers to adopt a mobile-first strategy and use the 'up' media query direction (min-width) wherever possible. The 'down' media queries are currently supported but the mobile-first approach with 'up' is preferred.
Breakpoint token Sass variable naming convention
Polaris breakpoint tokens generate Sass variables using the pattern $p-breakpoints-{alias}-{direction}, where alias is one of xs, sm, md, lg, or xl, and direction is one of up, down, or only. For example: $p-breakpoints-md-up, $p-breakpoints-md-down, $p-breakpoints-md-only.
Breakpoint media query variables reference
The following Sass variables are available for responsive media queries: $p-breakpoints-xs-up: (min-width: 0em); $p-breakpoints-xs-down: (max-width: -0.0025em); $p-breakpoints-xs-only: (min-width: 0em) and (max-width: 30.6225em); $p-breakpoints-sm-up: (min-width: 30.625em); $p-breakpoints-sm-down: (max-width: 30.6225em); $p-breakpoints-sm-only: (min-width: 30.625em) and (max-width: 47.9975em); $p-breakpoints-md-up: (min-width: 48em); $p-breakpoints-md-down: (max-width: 47.9975em); $p-breakpoints-md-only: (min-width: 48em) and (max-width: 64.9975em); $p-breakpoints-lg-up: (min-width: 65em); $p-breakpoints-lg-down: (max-width: 64.9975em); $p-breakpoints-lg-only: (min-width: 65em) and (max-width: 89.9975em); $p-breakpoints-xl-up: (min-width: 90em); $p-breakpoints-xl-down: (max-width: 89.9975em); $p-breakpoints-xl-only: (min-width: 90em);
Z-index tokens available in Polaris
Polaris provides z-index design tokens organized under the 'zIndex' category. These tokens are documented and available for use in components and layouts. The tokens are rendered through a TokenList component that maps through the zIndex token array, with each token displaying its name and category as 'z-index'.
Design Token Autocomplete feature overview
The Polaris for VS Code extension provides design token autocomplete suggestions for the Polaris Design Tokens. It automatically works for CSS and Sass files, shows preview design token values in autocomplete descriptions, displays color previews for all color tokens, and provides relevant code completions based on the current line of code.
How to trigger design token autocomplete
To trigger the design token autocomplete feature in the Polaris for VS Code extension, open a CSS or Sass file from your project, start typing the CSS property you want to set (for example 'color:'), then type the extension trigger characters '--' which will bring up the relevant autocomplete tokens associated with the CSS property typed.