-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[polaris.shopify.com] Add common action pattern guidelines (#11720)
Fixes https://github.com/Shopify/polaris-internal/issues/1454 ### What's in the PR - Common action guidelines scoped a subset of actions mainly focused within cards and list - Best practices that apply to all common actions - Actions: `Add`, `Copy`, `Delete`, `Edit`, `Pin`, `More actions`, `Remove` ### How to 🎩 🖥 [Local development instructions](https://github.com/Shopify/polaris/blob/main/README.md#install-dependencies-and-build-workspaces) 🗒 [General tophatting guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md) 📄 [Changelog guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog) ### 🎩 checklist - [ ] Tested a [snapshot](https://github.com/Shopify/polaris/blob/main/documentation/Releasing.md#-snapshot-releases) - [ ] Tested on [mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing) - [ ] Tested on [multiple browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers) - [ ] Tested for [accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md) - [ ] Updated the component's `README.md` with documentation changes - [ ] [Tophatted documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md) changes in the style guide --------- Co-authored-by: Jess Telford <jess.telford@shopify.com>
- Loading branch information
1 parent
831a683
commit 97184dc
Showing
62 changed files
with
616 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
'polaris.shopify.com': minor | ||
--- | ||
|
||
Added common action guidance. |
19 changes: 19 additions & 0 deletions
19
polaris.shopify.com/content/patterns/common-actions/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
--- | ||
title: Common actions | ||
description: Standardizing recurring actions gives merchants a predictable way to complete common tasks. | ||
lede: Standardizing recurring actions gives merchants a predictable way to complete common tasks. | ||
icon: ColorIcon | ||
previewImg: /images/patterns/common-actions/common-actions-cover-image.png | ||
keywords: | ||
- common actions | ||
- actions | ||
hideChildren: true | ||
showTOC: true | ||
status: New | ||
url: /patterns/common-actions | ||
variants: | ||
- 'variants/overview.mdx' | ||
- 'variants/best-practices.mdx' | ||
--- | ||
|
||
<Variants variants={frontmatter.variants} /> |
217 changes: 217 additions & 0 deletions
217
polaris.shopify.com/content/patterns/common-actions/variants/best-practices.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,217 @@ | ||
--- | ||
title: Best practices | ||
url: /patterns/common-actions/best-practices | ||
description: Standardizing recurring actions gives merchants a predictable way to complete common tasks. | ||
lede: Standardizing recurring actions gives merchants a predictable way to complete common tasks. | ||
keywords: | ||
- common actions | ||
- actions | ||
--- | ||
|
||
<LayoutSection card> | ||
|
||
<Text> | ||
|
||
<Stack gap="400"> | ||
|
||
## Icons and labels | ||
|
||
Actions should always clearly communicate their purpose by using a text label, an icon, or a combination of both. | ||
|
||
</Stack> | ||
|
||
</Text> | ||
|
||
<Large variant="do"> | ||
|
||
![An image showing icons used for common actions add, edit, delete, remove, copy.](/images/patterns/common-actions/common-actions-best-practices-icons@2x.png) | ||
|
||
Use icons in place of text for common actions. Leveraging pre-existing knowledge will improve clarity and help reduce clutter, since these icons require no text label. | ||
|
||
</Large> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing a list with a short label that describes the content in the list: "Add payment method".](/images/patterns/common-actions/common-actions-best-practices-short-labels@2x.png) | ||
|
||
Keep labels short and concise. | ||
|
||
</Medium> | ||
|
||
<Medium variant="dont"> | ||
|
||
![An image showing a list with a long label: "Add options like size and color.](/images/patterns/common-actions/common-actions-best-practices-long-labels@2x.png) | ||
|
||
Add unnecessary words to the action label. Instead, use the surrounding context and placement to communicate the outcome of an action. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing two actions with the icon aligned to the left of the label.](/images/patterns/common-actions/common-actions-best-practices-icons-left@2x.png) | ||
|
||
Place icons to the left of an action’s label. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing three buttons with the icons representing the action verb.](/images/patterns/common-actions/common-actions-best-practices-icons-represent-verb@2x.png) | ||
|
||
Use an icon that represents the verb when a label includes multiple words. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing two buttons: "Print shipping label" and "Send account invite" with both using specialized icons to represent complex concepts.](/images/patterns/common-actions/common-actions-best-practices-icon-specialized-action@2x.png) | ||
|
||
Use the appropriate icon to reinforce the message when referring to a specialized or complex action. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing text labels following the verb noun formatting and highlighting what the object type is for each; "Add customer", "Edit address", "Delete products", "Copy email".](/images/patterns/common-actions/common-actions-best-practices-label-reflect-object@2x.png) | ||
|
||
Reflect the object type in the action’s label using the verb + noun format. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing a list of actions with the most common actions paired with an icon and appropriate sytling.](/images/patterns/common-actions/common-actions-best-practices-actions-in-list@2x.png) | ||
|
||
Use an icon along with the text label for common actions displayed within an action list. | ||
|
||
</Medium> | ||
|
||
</LayoutSection> | ||
|
||
<LayoutSection card> | ||
|
||
<Text> | ||
|
||
<Stack gap="400"> | ||
|
||
## Visual hierarchy | ||
|
||
Style and placement help visually communicate the importance of an action on the page. | ||
|
||
</Stack> | ||
|
||
</Text> | ||
|
||
<Large variant="do"> | ||
|
||
![An image showing secondary and tertiary buttons in a card and a list.](/images/patterns/common-actions/common-actions-visual-hierarchy-secondary-tertiary@2x.png) | ||
|
||
Use secondary or tertiary buttons to give actions less emphasis while making them accessible for as many users as possible. | ||
|
||
</Large> | ||
|
||
<Text> | ||
|
||
Actions in editors need an additional level of emphasis to attract merchant attention and establish hierarchy between elements. | ||
|
||
</Text> | ||
|
||
<Large variant="do"> | ||
|
||
![An image showing add actions in the Online Store Editor.](/images/patterns/common-actions/common-actions-visual-hierarchy-actions-in-editors@2x.png) | ||
|
||
Use the emphasis color role for actions in editors. | ||
|
||
</Large> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing a card with primary and secondary buttons in the card footer.](/images/patterns/common-actions/common-actions-visual-hierarchy-filled-buttons@2x.png) | ||
|
||
Use buttons with a contained or filled background to help merchants identify which action they’ll most likely want within a given view. | ||
|
||
</Medium> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing a table using remove icon only tertiary buttons for each table row.](/images/patterns/common-actions/common-actions-visual-hierarchy-tertiary-buttons@2x.png) | ||
|
||
Use a tertiary icon button for items and rows in a list or table. | ||
|
||
</Medium> | ||
|
||
<Medium variant="dont"> | ||
|
||
![An image showing a card with ten different actions using the secondary button style.](/images/patterns/common-actions/common-actions-visual-hierarchy-limit-contained-buttons@2x.png) | ||
|
||
Use too many contained or filled buttons within a view as they can degrade hierarchy and cause confusion. | ||
|
||
</Medium> | ||
|
||
</LayoutSection> | ||
|
||
<LayoutSection card> | ||
|
||
<Text> | ||
|
||
<Stack gap="400"> | ||
|
||
## Interactivity | ||
|
||
Elements that are visually similar behave consistently throughout the interface. Consistency in behavior reduces confusion and cognitive load for merchants. | ||
|
||
</Stack> | ||
|
||
</Text> | ||
|
||
<Large> | ||
|
||
![An image showing a variety of button styles in different states.](/images/patterns/common-actions/common-actions-interactivity-button-space@2x.png) | ||
|
||
</Large> | ||
|
||
<Medium variant="do"> | ||
|
||
![An image showing visible focus rings when interacting using the keyboard.](/images/patterns/common-actions/common-actions-interactivity-focus-with-keyboard@2x.png) | ||
|
||
Make focus rings visible when a merchant is using the keyboard to interact with the UI. | ||
|
||
</Medium> | ||
|
||
<Medium variant="dont"> | ||
|
||
<video width="100%" height="auto" controls playsInline muted loop> | ||
<source | ||
src="/images/patterns/common-actions/common-actions-interactivity-focus-with-cursor.mp4" | ||
type="video/mp4" | ||
/> | ||
Don't make focus rings visible when a merchant is using a cursor to interact with elements. | ||
</video> | ||
|
||
Make focus rings visible when a merchant is using a cursor to interact with elements. | ||
|
||
</Medium> | ||
|
||
<Medium variant="dont"> | ||
|
||
<video width="100%" height="auto" controls playsInline muted loop> | ||
<source | ||
src="/images/patterns/common-actions/common-actions-interactivity-disabled-styles.mp4" | ||
type="video/mp4" | ||
/> | ||
Use disabled styles for elements that the merchant can interact with. | ||
</video> | ||
|
||
Use disabled styles for elements that the merchant can interact with. | ||
|
||
</Medium> | ||
|
||
<Medium variant="dont"> | ||
|
||
![An image showing a text button using the emphasis color as the only indicator of interactivity.](/images/patterns/common-actions/common-actions-interactivity-color-alone@2x.png) | ||
|
||
Rely on color alone to indicate interactivity. | ||
|
||
</Medium> | ||
|
||
</LayoutSection> |
Oops, something went wrong.