Common action pattern updates

.changeset/cool-otters-invent.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated common action pattern guidance

polaris.shopify.com/content/patterns/common-actions/variants/best-practices.mdx

@@ -14,9 +14,11 @@ keywords:
 
     <Stack gap="400">
 
-    ## Icons and labels
+    ## Content
 
     Actions should always clearly communicate their purpose by using a text label, an icon, or a combination of both.
+
+    See the [actionable language guidelines](/content/actionable-language#buttons) for more detail.
 
     </Stack>
 
@@ -42,7 +44,7 @@ keywords:
 
     ![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.
+    Add unnecessary words to the action label. Instead, use context and placement to communicate the outcome of an action.
 
   </Medium>
 
@@ -215,3 +217,86 @@ keywords:
   </Medium>
 
 </LayoutSection>
+
+
+<LayoutSection card>
+
+  <ExtraLarge>
+
+    <Text>
+
+      <Stack gap="400">
+
+      ## Platform considerations
+
+      Use interactions native to the device and type of input the merchant is using.
+
+      </Stack>
+
+    </Text>
+
+  </ExtraLarge>
+
+  <Text>
+
+    <Stack gap="400">
+
+    ### Desktop
+
+    Actions on desktop and mobile should consider both cursor and touch interactions, but the primary interaction for the desktop is cursor-based. Take advantage of added real-estate and interactions by using progressive disclosure to expose actions in context when the merchant needs them.
+
+    </Stack>
+
+  </Text>
+
+  <Small variant="do">
+
+    ![An image showing two icon only actions in a hover state with supporting tooltips. There's an add action with the tooltip "Add item" and a remove action the tooltip "Remove item".](/images/patterns/common-actions/common-actions-best-practices-desktop-tooltip@2x.png)
+
+    Clarify icon only actions with a tooltip using the verb + noun format for the label.
+
+  </Small>
+
+  <Small variant="do">
+    <video width="100%" height="auto" controls playsInline muted loop>
+      <source
+        src="/images/patterns/common-actions/common-actions-best-practices-desktop-tooltip-delay.mp4"
+        type="video/mp4"
+      />
+    Delay the appearance of tooltips attached to common actions as they can be intrusive.
+    </video>
+
+    Delay the appearance of tooltips attached to common actions as they can be intrusive.
+
+  </Small>
+
+  <Text>
+  </Text>
+
+  <Large variant="do">
+
+    ![An image of two cards with items displaying actions on hover.](/images/patterns/common-actions/common-actions-best-practices-desktop-hover@2x.png)
+
+    Show list item actions like edit, delete, copy, and remove on hover.
+
+  </Large>
+
+  <Text>
+
+    <Stack gap="400">
+
+    ### Mobile
+
+    The primary interaction for the mobile is touch-based. Optimize for touch enabled devices by considering placement and target size of actions.
+
+    </Stack>
+
+  </Text>
+
+  <Large>
+
+    ![An image showing tags on desktop and responsive web.](/images/patterns/common-actions/common-actions-best-practices-mobile@2x.png)
+
+  </Large>
+
+</LayoutSection>

polaris.shopify.com/content/patterns/common-actions/variants/overview.mdx

@@ -30,45 +30,53 @@ url: /patterns/common-actions/overview
 
     ![Two tertiary buttons with the circle plus icon and an Add {object} label.](/images/patterns/common-actions/types/common-action-types-add-circle-plus-icon@2x.png)
 
-    Use the circle plus icon in activators that don’t have a defined container like tertiary buttons.
+    Use the circle plus icon in buttons that don’t have a defined container like tertiary buttons.
 
   </Medium>
 
   <Medium variant="do">
 
     ![Two secondary buttons with the plus icon and an Add {object} label.](/images/patterns/common-actions/types/common-action-types-add-plus-icon@2x.png)
 
-    Use the plus icon when a button has a defined shape or filled background.
+    Use the plus icon when a button has a defined shape or filled background. The plus icon supports the action while balancing the weight of the element with the rest of the UI.
 
   </Medium>
 
   <Medium variant="do">
 
-    ![A single select option list of customers with an add customer action at the bottom of the list of options.](/images/patterns/common-actions/types/common-action-types-add-do-bottom-list@2x.png)
+    ![An image of two cards with a few list items and the add action at the bottom.](/images/patterns/common-actions/types/common-action-types-add-list-bottom@2x.png)
 
-    Place add actions at the bottom of a list of items or options.
+    Place add actions at the bottom of a list unless the list will likely be long. For example, a table or list of selected resources.
 
   </Medium>
 
-  <Medium variant="dont">
+  <Medium variant="do">
+
+    ![A select list of options with an add option at the botto of the list, outside of the scrollable area.](/images/patterns/common-actions/types/common-action-types-add-select-list-bottom@2x.png)
+
+    Place add actions at the bottom of a list of selectable options. For example, when picking a collection or tag to add to a product. Keep the action visible by placing it outside of the scrollable area.  
 
-    ![A card with a header and an add action to the right of the card title. The card has a list of items in the body.](/images/patterns/common-actions/types/common-action-types-add-dont-top-list@2x.png)
+  </Medium>
+
+  <Medium variant="do">
 
-    Place add actions at the top of a list of items or options.
+    ![Two cards each with long lists of resources in a viewable state with a main add action in the list header.](/images/patterns/common-actions/types/common-action-types-add-list-top@2x.png)
 
+    Place add actions in the header in long lists of resources.
+
   </Medium>
 
   <Medium variant="do">
 
-    ![A table with an Add location action in the card header to the right.](/images/patterns/common-actions/types/common-action-types-add-do-top-table@2x.png)
+    ![A table of locations with the add action in the card header above the table.](/images/patterns/common-actions/types/common-action-types-add-table-top@2x.png)
 
-    Place add actions associated with a table in the card or page header. This keeps the action discoverable.
+    Place add actions associated with a table in the card, table, or page header.
 
   </Medium>
 
   <Medium variant="dont">
 
-    ![A table with selectable items, pagination, and input fields. There is an add products action in the card footer to the right.](/images/patterns/common-actions/types/common-action-types-add-dont-bottom-table@2x.png)
+    ![A table of products with an add action at the bottom of the table.](/images/patterns/common-actions/types/common-action-types-add-table-bottom@2x.png)
 
     Place add actions at the bottom of a table. This risks them getting lost and can cause confusion.
 
@@ -94,29 +102,59 @@ url: /patterns/common-actions/overview
 
     ![The polaris copy icon in a neutral and hover state with a “Copy item” tooltip.](/images/patterns/common-actions/types/common-action-types-copy-copy-icon@2x.png)
 
-    Use the copy icon with a tertiary icon button for strings of text.
+    Use the clipboard icon with a tertiary icon button for copying a string of text.
 
   </Small>
 
   <Small variant="do">
 
     ![The polaris link icon in a neutral and hover state with a “Copy link" tooltip.](/images/patterns/common-actions/types/common-action-types-copy-link-icon@2x.png)
 
-    Use the link icon with a tertiary icon button for deep links and URLs.
+    Use the link icon with a tertiary icon button for copying deep links and URLs.
 
   </Small>
 
-  <Text>
+  <Medium variant="do">
 
-  </Text>
+    <video width="100%" height="auto" controls playsInline muted loop>
+      <source
+        src="/images/patterns/common-actions/types/common-action-types-copy-hover.mp4"
+        type="video/mp4"
+      />
+      Provide feedback inline using a confirmation check icon post-click or tap.
+    </video>
 
-  <Large variant="do">
+    Show copy actions on hover for cursor interactions. See the [copy to clipboard](https://storybook.polaris.shopify.com/?path=/story/all-components-button--copy-to-clipboard) example.
 
-    ![A card with a customer email displaying a "checkmark" icon with a tooltip displaying a "Copied" label to indicate the email has been successfully copied to the clipboard.](/images/patterns/common-actions/types/common-action-types-copy-copied-feedback-tooltip@2x.png)
+  </Medium>
 
-    Use a confirmation “copied” tooltip appearing post-click or tap.
+  <Medium variant="do">
 
-  </Large>
+    <video width="100%" height="auto" controls playsInline muted loop>
+      <source
+        src="/images/patterns/common-actions/types/common-action-types-copy-copied-feedback-tooltip.mp4"
+        type="video/mp4"
+      />
+      Provide feedback inline using a confirmation check icon post-click or tap.
+    </video>
+
+    Provide feedback inline using a confirmation check icon post-click or tap.
+
+  </Medium>
+
+    <Medium variant="do">
+
+    <video width="100%" height="auto" controls playsInline muted loop>
+      <source
+        src="/images/patterns/common-actions/types/common-action-types-copy-copied-feedback-toast.mp4"
+        type="video/mp4"
+      />
+      Use a confirmation “copied to clipboard” toast message when “copy” is within an action list.
+    </video>
+
+    Use a confirmation “copied to clipboard” toast message when the action is within an action list.
+
+  </Medium>
 
 </LayoutSection>
 
@@ -134,35 +172,34 @@ url: /patterns/common-actions/overview
 
   </Text>
 
-  <Small variant="do">
+  <Large>
 
-    ![A list of action with a delete action at the bottom using the destructive styling along with the "delete" icon.](/images/patterns/common-actions/types/common-action-types-delete-do-list-of-actions@2x.png)
+    ![A row of buttons in different variations.](/images/patterns/common-actions/types/common-action-types-delete@2x.png)
 
-    Use the delete icon with a critical item in a list of actions.
+  </Large>
 
-  </Small>
 
-  <Small variant="dont">
+  <Medium variant="do">
 
-    ![A list of actions all using the default styling with no icons.](/images/patterns/common-actions/types/common-action-types-delete-dont-list-of-actions@2x.png)
+    ![A list of action with a delete action at the bottom using the destructive styling along with the "delete" icon.](/images/patterns/common-actions/types/common-action-types-delete-do-list-of-actions@2x.png)
 
-    Use default styling and standalone text for delete actions within a list of actions.
+    Use the delete icon with a destructive item in an [action list](https://polaris.shopify.com/components/lists/action-list?example=action-list-with-destructive-item).
 
-  </Small>
+  </Medium>
 
   <Medium variant="do">
 
-    ![A list of menu items with each item displaying a delete icon using the tertiary icon button style.](/images/patterns/common-actions/types/common-action-types-delete-action-inline@2x.png)
+    ![A list of action with a delete action at the bottom using the destructive styling along with the "delete" icon.](/images/patterns/common-actions/types/common-action-types-delete-do-list-of-actions-bottom@2x.png)
 
-    Place delete actions inline to the right of a list item. Default to the delete icon with a tertiary icon button.
+    Always place delete actions at the bottom of an action list.
 
   </Medium>
 
-    <Medium variant="caution">
+  <Medium variant="do">
 
-    ![A list of menu items with each item displaying a delete icon using the tertiary critical icon button style.](/images/patterns/common-actions/types/common-action-types-delete-caution-many-destructive-buttons@2x.png)
+    ![Two icon only delete buttons with one in a hover state with a "Delete item" tooltip displayed.](/images/patterns/common-actions/types/common-action-types-delete-icon@2x.png)
 
-    Avoid overusing buttons with critical styles within a single view. Overusing the critical color can dilute the meaning and importance of the action.
+    Use the delete icon for delete actions in lists.
 
   </Medium>
 
@@ -174,19 +211,41 @@ url: /patterns/common-actions/overview
 
   </Medium>
 
+  <Medium variant="do">
+
+    ![A list of menu items with each item displaying a delete icon using the tertiary icon button style.](/images/patterns/common-actions/types/common-action-types-delete-action-inline@2x.png)
+
+    Place list item delete actions inline to the right. Default to a tertiary button with the delete icon.
+
+  </Medium>
+
+  <Medium variant="do">
+
+    <video width="100%" height="auto" controls playsInline muted loop>
+      <source
+        src="/images/patterns/common-actions/types/common-action-types-delete-action-inline-hover.mp4"
+        type="video/mp4"
+      />
+      Display list item delete actions on hover when using a cursor.
+    </video>
+
+    Display list item delete actions on hover when using a cursor.
+
+  </Medium>
+
   <Medium variant="dont">
 
-    ![An image of a modal with two primary buttons. Save uses the default primary button style and delete uses the primary critical button style.](/images/patterns/common-actions/types/common-action-types-delete-two-primary-buttons@2x.png)
+    ![A list of menu items with each item displaying a delete icon using the tertiary critical icon button style.](/images/patterns/common-actions/types/common-action-types-delete-dont-fill-destructive-buttons@2x.png)
 
-    Pair primary critical and primary buttons together.
+    Don’t overuse critical styled buttons within a single view as it can dilute the meaning and importance of the action.
 
   </Medium>
 
   <Medium variant="dont">
 
-    ![A list of locations with each item displaying a delete action inline to the right using a primary critical button style.](/images/patterns/common-actions/types/common-action-types-delete-dont-fill-destructive-buttons@2x.png)
+    ![An image of a modal with two primary buttons. Save uses the default primary button style and delete uses the primary critical button style.](/images/patterns/common-actions/types/common-action-types-delete-two-primary-buttons@2x.png)
 
-    Use buttons with critical styles for list item delete actions.
+    Don’t pair primary critical buttons with other button variants and tones that look jarring and create visual competition between elements.
 
   </Medium>
 
@@ -360,7 +419,7 @@ url: /patterns/common-actions/overview
 
     ![A list of collections with one item in a hover state with the option to remove it displayed inline to the right using the "x" icon.](/images/patterns/common-actions/types/common-action-types-remove-on-hover@2x.png)
 
-    Show remove actions on hover on non touch enabled devices in dense UIs.
+    Show remove actions on hover when the merchant is using a curosr to navigate.
 
   </Medium>