Discuss "page actions" on resource details layout pattern

[johanstromqvist]

Goal: We want a standardized layout pattern for details pages, including clarity where to place common page actions such as duplicate, archive and delete.

Problem: Common details pages, such as Products, Orders, and Customers, currently lack consistent placement of such actions.

Examples

Section	Example
Product detail
Customer detail header
Customer detail footer

More examples

Products

## Products Products has no page actions in "More actions", but `duplicate` in common actions, and `archive`, `delete` and `save` in footer actions.

Orders

## Orders Orders has `cancel order` and `archive` in "More actions", and no footer actions

Customers

## Customers Customers has TWO `delete` actions, one in "More actions" and one in the footer. Plus the destructive button has wrong styling.

Discounts

## Discounts Discounts has no "More actions", but `duplicate` among common actions and `delete` in footer actions

Exploration

Log of previous suggestions

v0.4 

v0.3

v0.2

v0.1

Goals

It must be very easy and intuitive to find recurring page actions on pages that looks similar. Pages may vary to some degree depending on its purpose, but frequently recurring page actions must default to a standardized placement. Any exceptions should be made with great caution.

• No footer actions
• No save action
• Default to including a "More actions" and place all page actions there

TODOs

• Visualize the suggested default pattern in Figma
• Talk to various SMEs from Products, Orders, etc, to see if there are any concerns and insight
  • Link to Admin UX post in Workplace
• Consider feedback, set minimal scope, create issues
• Update the content and assets on the pattern page

[nickpresta]

Another example - page actions on Custom Reports:

Things I noticed:

• No icons for any actions
• No "More actions" overflow menu -- all actions are visible at all times
• Destructive action ("Delete") isn't styled any differently

[designrichly]

This likely sits outside scope but as a place to consolidate issues with More actions: currently app actions can't be translated. E.g. Translate & Adapt says 'Localize', regardless of what language your admin is in.

[jakemoves]

@tatianau would be able to articulate this more completely, but there are a11y issues with page actions. When a page action opens a modal, I think it's currently impossible to return focus to the correct element on modal close. If we're standardizing on page actions, let's add a requirement to pass an activator or activatorRef in, so keyboard users don't have their focus sent back to the top left every time they use a page action that involves a modal.

[jakemoves]

Leaving separate comments for different topics: this work would be an excellent candidate for Fable testing, when we have a prototype or PR. #accessibility can help get that organized!

[jakemoves]

Is there a limit to the number of 'common actions', or is it driven by breakpoints? It would make sense to me to support more than two 'common actions' being exposed as buttons (rather than actionlist items that require a drill-down).

[tatianau]

there are a11y issues with page actions

(cc @oksanashopify @maxariss for context)

I second @jakemoves's point - the issues with focus not returning to the activator are prevalent across the Admin, the Products section alone has at least three occurrences (1, 2, 3), and all the issues across Admin sections have the same root cause:

• In many places they can be easily fixed by providing an activator ref to the modals they open.
• However, in case of the Page component's secondary actions, there is currently no way to do that other than creating a custom version of More actions component to pass to Page's secondaryActions which as a workaround has its own implications.
  • Adding a requirement to pass an activator or activatorRef to the secondaryActions as @jakemoves suggested could be the way to provide the ability to fix it system-wide.

Is there a limit to the number of 'common actions', or is it driven by breakpoints? It would make sense to me to support more than two 'common actions' being exposed as buttons (rather than actionlist items that require a drill-down).

@jakemoves AFAIK, there is no fixed limit - the number of secondary actions that are shown to the left of the More actions dropdown is dictated by the available real estate on the page and it changes on window resize or across different screens / page zoom levels, the actions that didn't fit into the available space get collapsed into the dropdown.

---

@johanstromqvist would the problem benefit from creating a GH discussion where folks can share opinions and thread the feedback to each proposal / question individually?

[johanstromqvist]

Great input, friends! Much appreciated.

Regarding the layout pattern itself

• Our priority is to document a details layout pattern with recommendations that are most beneficial to merchants
• The general direction of how and where page actions are grouped seems supported by core
• We can continue our plans to promote this pattern and fix the broken interactions in parallel
• Product teams can update their respective details pages at their own discretion to the degree that it's feasible
• We'll continue to incorporate future improvements to the pattern once it's published

Issues

• App actions in "More actions" can't be translated. @designrichly would you mind creating an issue for that?
• Focus not returning to the activator in "More actions". @tatianau would you mind creating an issue for that one?

Feel free to create any discussions that you think are helpful. I will use this issue for what concerns the pattern documentation, but I'm happy to contribute and pick up insights in other issues and discussions too.

[ry5n]

I’ve always wanted to do something like this (I think Jesse BC did too), so I’m generally 👍

Howver, there’s a risk that many merchants won’t know where to look for the actions once they’ve moved. What’s currently in that “More actions” menu is often just app actions. If a merchant doesn’t use apps, or isn’t used to using this menu, the support impact of this change could be significant.

This is the kind of thing where I’d be tempted to do some kind of usability testing and/or try some kind of change management intervention. We don’t have good patterns for this kind of thing, but maybe putting something discrete where page actions used to be (not a banner!) to help guide users through the change.

[ry5n]

(Also, I’d suggest putting the core actions like duplicate and delete above any app actions in the menu)

[LA1CH3]

I want to second @ry5n 's comment. As an example, anecdotally I have heard some merchants frustrated with the new index table filtering UI, because it significantly changed their mental modal of the index table and how they could perform searching/filtering. I think we'd want to avoid the same here.

Is there any mechanism in place to signify these new updates to the user? Maybe leveraging a local storage key or similar, and the first time they view this new experience, pop up some notification/modal banner with "Hey! Just FYI, we moved all the page actions under "More actions" now.", instead of merchants having to search once they realize the buttons aren't there anymore.

Anyways, thats a bit unrelated to this specific topic but just something I wanted to agree with. In general I am in favor of this change, but one thing I wanted to bring up for the products page: on small viewport sizes, we collapse the "share" action (along with our other secondary actions) all into the "More actions" dropdown.

Adding additional menu items here could make this menu quite long. Maybe its not too much of an issue, but figured I would bring it up.

[johanstromqvist]

Great points!

Agree on recurring page actions in the top of the list. ✅

there’s a risk that many merchants won’t know where to look for the actions once they’ve moved. What’s currently in that “More actions” menu is often just app actions.

1. Our primary goal right now is to make sure that 1P and 3P build new pages according to this pattern. In this pursuit, the suggested pattern feels safe.
2. Any new merchant joining Shopify would benefit from the consolidated pattern, so that's another incentive to proceed imo.
3. I agree that there's a risk for existing merchants to be confused on existing pages. However, I perceive this risk as low, that it's reasonably easy to fix when it occurs, and that merchants would benefit over time. But please check my assessment of that:
   a. Common places like "Orders" and "Customers" already keep actions like duplicate, archive and delete in "More actions", so for resource management in general and for this layout specifically this placement is already familiar. We are not introducing something new, rather consolidating unhelpful variation into the best established solution.
   b. The placement on the page and type of overflow menu is familiar from both the admin and other software. It also gathers all page actions in one sensible place. It would be a reasonable place to look, an unsurprising place to find these actions, and an easy adjustment to make.
   c. Compared to the current inconsistency, I think it's fair to assume that the suggested pattern would reduce cognitive load in the long term despite temporary confusion.

[johanstromqvist]

Also great points!

Is there any mechanism in place to signify these new updates to the user?

Since this an initiative to document what layout pattern to use in this context, I'd like to keep the scope to that and let each 1P product team consider the specific implications on their respective pages if and when they make updates. I agree that it would be great to communicate what changes on a page, but I don't know what would be the appropriate solution to the different pages.

Adding additional menu items here could make [the product] menu quite long.

I think long lists are acceptable to some degree, but something that should be monitored by each page owner. If we would encounter very long lists often, then that would imply that there's an unmet systemic need that we would want to look into.

[rox163]

For draft orders - I like the look of the suggested pattern. We dont have many app links so for now the list length isnt an issue. We have surfaced 2 common actions - duplicate and share; however our delete action is in the footer atm as draft orders arent really manually deleted much.

[ry5n]

Our primary goal right now is to make sure that 1P and 3P build new pages according to this pattern. In this pursuit, the suggested pattern feels safe.

I see, I missed that. In that case, it does feel safe.

So that merchants have a consistent place to find things, I’d suggest a plan for follow-up steps, after first publishing guidelines:

2. Revisit high-traffic existing pages and add the page actions to “more actions“ (without removing them from the footer yet)
3. Remove them from the footer with some non-interruptive nudge that they’ve moved

[raquelbreternitz]

I'm loving this conversation!

on small viewport sizes, we collapse the "share" action (along with our other secondary actions) all into the "More actions" dropdown.

Small thing, but I wanted to suggest in this case that we consolidate "share" into one action within the list that then pops up a modal (or something of the sort) with all the different share options, to assist in the "long action lists" problem.

[designrichly]

• App actions in "More actions" can't be translated. @designrichly would you mind creating an issue for that?

@johanstromqvist we've got this guy. Want it moved to another board?

[johanstromqvist]

@designrichly

Great! No, not necessarily. I wanted to exclude it from the scope of the layout pattern documentation without losing it. Keep it in store-localization if that's where it needs to be fixed. I assume the component itself is fine, but feel free to create an issue in polaris if there is anything that needs the team's attention.

[gothammm]

I wanted to add another example: Variants Detail page.

Desktop View:

Mobile View:

Screen.Recording.2023-01-19.at.13.39.04.mov

• Maybe unrelated but in the mobile view, if a product has a lot of variants, the variants list seems to be somewhat blocking the form view, and since the list itself is scrollable, its a bit confusing (sometimes you end up scrolling the page, sometimes the variant list). I was hoping if the variants list can be collapsed or placed elsewhere?

[johanstromqvist]

Thanks for all the great input friends! Below is what I would like to proceed to include in our Resource details layout pattern documentation.

@nickpresta @designrichly @jakemoves @tatianau @ry5n @LA1CH3 @rox163 @raquelbreternitz @gothammm Please give this a thumbs up or comment if you have any concerns or suggestions.

Rough guidelines

• No footer actions
• Place all page actions in the secondaryActions prop in the Page component
• Arrange the actions the following way
  • Page specific actions first (e.g. Preview for Products, and Print packing slips for Orders)
  • Recurring page actions second (duplicate, archive, delete)
  • App actions third
• Actions being visible in the header or hidden in "More actions" is behaviour build into the Page component
• Omit any recurring action that isn't relevant on the page

Further initiatives

• Encourage feature teams to change after the pattern is published. Help them manage the change.
• Track down how app actions are integrated and make sure they are placed last

[designrichly]

I think this is looking great. Here's a thought to consider: I'm representing an app (Translate & Adapt) which relies on More actions throughout admin, there's a realistic chance of getting relegated far down.

Here's a screenshot of a store with a long title, that pushes all page actions into More actions, including Share:

Localize, our action, could end up pretty far down.

Here is that same menu on mobile:

Merchants may use app actions over and over again - more than they use some of Shopify's out of the box ones. E.g. I'm personally not convinced how helpful Share is.

A thought to toy with (which I recognise pushes scope) is pinning app actions. We do this for apps in the navigation when they get used a lot:

And Amazon has a helpful pattern along these lines to bookmark commonly used navigation items:

Something like that feels like it might be helpful for heavy app users:

Thoughts?

[LA1CH3]

@johanstromqvist I am in agreement with your proposed pattern but I would again bring up the "Share" list. I think for this pattern to work we might need to include something in the documentation to not have page-specific actions bury recurring actions. In the case of "Share", which is currently a flat list of "Copy link", "Facebook", "Twitter", etc., that would be six items listed before the user sees "Archive" and "Delete".

I think @raquelbreternitz suggestion of "Share" with a modal or something similar would be necessary for this pattern to work effectively. I see your screenshot only includes a single "Share" item so maybe that becomes part of the Product Details Page initial implementation of this pattern.

[jameswfindlater]

@johanstromqvist not against this in principle - I think your logic is sound. However as a heads up there is an ongoing project focused directly on improving and building out app actions.

One the key things that's looking to be done there is to allow that list of app actions to be searchable (it can grow unmanageably long in a lot of instances). Curious how you would see us integrating search into this pattern?

[johanstromqvist]

Thanks friends! Great value. Please keep it coming.

Just to be clear, the purpose of the pattern documentation is to inform 1P and 3P builders to make great decisions quickly. In this case, to use the details layout pattern when merchants would expect it, and to implement it in a way that would maintain high quality and consistency.

That means that the critical decisions that builders make when using it is our primary concern. When it comes to page actions, that means (1) to not create a footer with actions, and (2) to arrange secondary actions in whatever order we suggest (not final). Builders will not be able to influence the behaviour or functionality of the list.

The list itself and its behaviour is managed by various 1P teams. Any future improvements to the layout pattern, to the "More action" list itself, or to any other element on the page are super welcome, and we'll be happy to update the pattern docs when that happens. We'll also try to help teams to conform to the recommended pattern after we've published it. I'm sure there are unknown unknows that we'll discover along the way, but we'll figure it out.

Regarding order of actions

@designrichly

Merchants may use app actions over and over again - more than they use some of Shopify's out of the box ones.

I think this is key. I assume the apps merchants install are typically more intentional and more frequently used. Is there insight or data that could support this? Not absolutely necessary, but would take some complexity out of the decision.

Regarding share actions

@LA1CH3 @designrichly
Agree that share actions are claiming too much space. This is on our radar. @raquelbreternitz is currently tracking down the team that owns it, and the Polaris team could potentially reconsider the behaviour of an actionGroup becoming flat when nested (which seems to be another angle of the problem).

Regarding pinning actions

@designrichly
Good idea! Giving such flexibility to merchants would definitely increase tolerance and lower error proneness. Would you mind creating an issue for that in polaris? Can't promise priority right now, but would be great to assess all the undesired consequences of too long lists.

Regarding search inside the list

@jameswfindlater
I'm very positive to your team's ideas and I would be happy to consult on any specific matter. I assume "search" is a solution to the lacking scaling capabilities of the list. If we think we might need search functionality among our secondary actions, perhaps it's worth questioning if that's the right way to show actions in the first place.

[designrichly]

Will do 👍

[jameswfindlater]

@johanstromqvist

I assume "search" is a solution to the lacking scaling capabilities of the list

No I wouldn't say that. The amount of app actions that show there is governed by the amount of applicable apps that a merchant has installed, and sometimes that's a lot. It's not something we can directly control or curate beyond app guidelines on appropriate use. So offering the ability to search them once they're above a certain amount seems like table stakes in terms of scaling capabilities.

Also for certain apps these links will be a merchant's access point to pretty important 1P/3P functionality, so I don't think we should think of them in the same breadth as things like archive, duplicate etc. I know we already do this in some instances but I don't think it's good idea to double down on it.

[designrichly]

Will do 👍

#8152

[johanstromqvist]

Here's a summary of our short term plans

1. Deprecate the PageActions component (backlog)
2. Omitting page actions (footer) from the resource details layout pattern image [1]
3. Implying placement in the resource details layout code example [2]
4. Add explicit placement guidance (backlog)

The general switch is from footer to header. We're not making an effort to guide specific order in secondary actions right now.

Polaris patterns – Resource details layout

[1] pattern image	[2] code example