Create compact components for specialized tasks
Create compact components for specialized, minute tasks to appropriately represent their importance in the admin.
Shopify Polaris · all subjects
layout
41 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Size reflects task importance
Do not contradict the importance of a task with its size in the admin. Component size should reflect the relative importance of the task it performs.
Group similar data in the same card
Group similar data points or tasks in the same card to establish visual relationships.
Nest inset shapes and surfaces
Nest inset shapes and surfaces to create visual hierarchy through reduced border radius, creating a nesting effect.
Emphasis creates visual hierarchy
In the Shopify admin, larger, heavier, and contrasting elements attract attention and create visual rhythm. Smaller, lighter, and more subtle elements are work-oriented and provide detailed information. Use size, weight, and contrast to establish hierarchy in the admin.
Use weight and contrast to introduce UI sections
Use weight and contrast to introduce sections of the UI to establish visual hierarchy.
Divider lines usage restriction
Divider lines are used to delimit rows of information in data and index tables. Divider lines should not be used to create visual hierarchy or separation outside of index tables.
Software-oriented sizing for admin components
The Shopify admin is more like software rather than a website, so elements need to be sized appropriately based on their job. Compact elements add detail, and larger elements command more attention. Surfaces adapt to these components and offer an optimized view of the admin.
Space and proximity principle in layout
Space plays a vital role in establishing connections between items. The principle of proximity states that the closer objects are, the stronger their perceived relationship. Grouping similar items together helps merchants understand which elements are related and helps them make faster decisions.
Adjust padding in nested tables
Tables and lists that exist within another container follow slightly different spacing guidelines. Horizontal padding is adjusted to give more space for data, and to avoid having too much empty space overall.
Nest tables in cards when there is other content
Nest tables in cards or other containers when there is other content in that card.
Avoid nesting table as only card content
Avoid nesting a table in a card if it is the only content of that card.
Shaped elements contain design elements in containers
Shaped elements contain other design elements within a container that has a certain shape. These elements can live on surfaces or on backgrounds and are often smaller and serve a single purpose, like badges. Shaped elements often do not have an elevation and their shapes are considered to either be target zones if they are interactive, or serve as a visual indicator to make them easier to scan.
Pay attention to spacing in smaller shaped elements
Pay attention to spacing when creating smaller elements. This includes using different sizes per side to achieve visual balance.
Adjust size of shaped elements with siblings
Adjust the size of shaped elements so they work well with their siblings, like in the case of a button next to an input field.
Breaking alignment with visual keylines
Breaking alignment or spacing may be required in some rare instances. Depending on the layout of the page, alignments may be mathematically inconsistent, but will be visually aligned. Use imaginary keylines to create neatly aligned containers in the UI if spacing is inconsistent within each container. Different alignment should be applied to separate containers, and never within the same container.
Nesting surfaces with smaller border radius
Reduce the border radius of inset surfaces in order to create a nested look. Inset surfaces should have a smaller border radius than their parent container to create visual hierarchy and a sense that the interface is purpose-built.
Surfaces in admin contain other elements
Surfaces in the admin contain other elements like badges and text. Cards, popovers, modals and other such components are surfaces that are used to build the admin.
Dividing surfaces with nested surfaces
Nested surfaces can be grouped together within another surface to achieve visual separation between different parts of a component. Group nested surfaces together to create visual separation rather than using horizontal divider lines for non-table surfaces.
Divider lines reserved for data and index tables
Divider lines are reserved for data and index tables. Do not use horizontal lines to divide a surface that isn't a data or index table.
Avoid nested surfaces for data tables
Building data or index tables with nested surfaces can make them feel inefficient. Use horizontal dividers for tables instead.
Grid or list pattern prioritized when dividing surfaces
When dividing surfaces, prioritize a grid or list pattern to organize the layout.
Avoid breaking symmetry when grouping surfaces
Avoid breaking symmetry when grouping surfaces together. Maintain visual balance when organizing nested surfaces within a parent container.
Do not use equal or larger border radius for nested elements
Do not make all nested elements have the same, or larger, border radius than their parent.
Do not change border radius of buttons or badges when nesting
Do not change the border radius of elements like buttons or badges when nesting them within other surfaces.
Density principle in Pro design language
Density in the interface adapts to the task: high density is used in data-rich environments, while low density is employed in focused, detailed areas. Space is optimized while maintaining high usability.
Layout guidance in app design guidelines
Learn more about Layout in the app design guidelines for broader layout principles.
Version 11 layout components - alpha release status
Version 11 introduces new layout components as an alpha release. The components and Figma components are available, but significant developments could still occur. Users are encouraged to understand what's changing, start using the layout updates, and provide feedback. Teams should coordinate with the Polaris team to determine the best approach for their situation.
Stack and Card components removed in Version 11
The original Stack and Card components have been removed from Polaris in Version 11 and replaced with LegacyStack and LegacyCard. These legacy components are planned to be replaced with the new Card and VerticalStack (renamed to BlockStack in v12) components in the next major release.
AlphaCard renamed to Card
AlphaCard has been renamed to Card in Version 11 to reduce confusion with component names being tied to component lifecycle stages.
Polaris layout component usage was only 20%
Before the Version 11 changes, Polaris only provided two layout components, and even within Polaris components themselves, the existing layout components were used only 20% of the time. This limitation prompted the creation of new, more flexible layout components.
Future migration tools for layout components
Codemod transformations are planned to help users migrate from LegacyCard to Card, LegacyStack to BlockStack, and TextContainer to BlockStack.
layout/custom-property-disallowed-list stylelint rule
The layout/custom-property-disallowed-list stylelint rule disallows the use of legacy layout custom properties. Do not use custom properties like var(--p-choice-size) for layout purposes; use components like Checkbox instead.
layout/function-disallowed-list rule
The stylelint rule layout/function-disallowed-list disallows the use of internal Sass layout functions. Use hard coded pixel or rem values for width and height instead of legacy mixins, variables, or spacing tokens. For example, use 'height: 56px;' instead of 'height: top-bar-height();'.
Use components instead of layout CSS properties
When implementing layouts, use Polaris layout components like InlineGrid instead of writing layout properties directly in CSS. This is enforced by the layout/property-disallowed-list stylelint rule.
Box border radius props renamed in v12
Box border radius properties have been renamed to align with CSS border radius constituent properties. borderRadiusEndStart becomes borderEndStartRadius, borderRadiusEndEnd becomes borderEndEndRadius, borderRadiusStartStart becomes borderStartStartRadius, and borderRadiusStartEnd becomes borderStartEndRadius.
HorizontalGrid component renamed to InlineGrid
The HorizontalGrid component is renamed to InlineGrid in v12. Directional components now use Inline and Block naming conventions based on CSS logical properties. Also rename HorizontalGridProps to InlineGridProps.
HorizontalStack component renamed to InlineStack
The HorizontalStack component is renamed to InlineStack in v12. Directional components now use Inline and Block naming conventions based on CSS logical properties. Also rename HorizontalStackProps to InlineStackProps.
Page divider prop removed in v12
The Page component's divider prop is removed because page dividers are no longer a pattern in the new Polaris design language. If a divider is needed, use the Divider component instead.
VerticalStack component renamed to BlockStack
The VerticalStack component is renamed to BlockStack in v12. Directional components now use Inline and Block naming conventions based on CSS logical properties. Also rename VerticalStackProps to BlockStackProps.
Dividers removed from Polaris components in v12
Dividers have been removed across Polaris components, notably from Page and LegacyCard. Spacing should be used to create visual hierarchy. If dividers are needed, use the Divider component to add them back where necessary.