Make WordPress Core

Opened 17 months ago

Last modified 8 months ago

#48644 new enhancement

Establish guidelines for button order

Reported by: drw158 Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Administration Keywords: needs-design-feedback
Focuses: ui, accessibility Cc:


This issue has been moved from GitHub to Trac to increase visibility. Original GitHub discussion: https://github.com/WordPress/gutenberg/issues/7534#issuecomment-549980093

There is a need to establish guidelines for button group position and button order within the group. There are two patterns that need to be documented:

  • A pattern for the button group position. It's OK for the group position to be different based on context ( e.g. right-aligned group in dialogs). This also includes making sure that related buttons are in close proximity (existing trac issue: #40822).
  • A pattern for button order. A consistent button order is important for accessibility so that the first and second actions are predictable throughout the UI (e.g. confirm is always first and cancel is always second).

Important to note that currently the WordPress Component documentation aligns buttons to the right, with the primary action second in the visual order:


Button group placement

This one is a bit easier because as explained above, it's OK for the group position to be different based on context. Usually you want the buttons on the left for screens with forms because that’s where the eye travels. Same logic can be applied to dialogs as well — actions are usually on the right because that’s where the eye travels. We can figure out what patterns to standardize and document them.

Button order

Platform conventions

For dialogs: on Windows, primary is always first. For Apple and Google, primary is always second:


In some cases primary first is the ideal order, but sometimes primary second is the ideal order. This is where we are blocked. If we deviate and have inconsistent ordering, then this is not ideal from an a11y point of view.

Button order options

Option A


  • Primary action is always first (to the left), regardless of button alignment
  • Secondary action is to the right of the primary action

The disadvantage here is that it’s in conflict with the idea that primary or confirming actions suggest forward motion and secondary or dismissive actions suggest backward motion. Sometimes it can be subtle like:

  • Ok (forward) and Cancel (backward)
  • Agree (forward) and Disagree (backward)

Sometimes it’s more literal like:

  • Continue (forward) and Cancel (backward)
  • Next (forward) and Back (backward)

If the primary action is the first action, it can look wrong and unnatural:


Here’s a real example in WP Admin, of where I think Option A falls short:


Notice in the second dialog how the “Go Back” button is on the right, when it should be on the left to indicate backward motion.

Additionally, in a NUX or wizard type of interface where there are multiple steps, it usually makes sense to have a "Back" and "Next" button (Next is usually the primary action). It would look unnatural if the Back button was on the right.

Option B


  • Primary action is always second (to the right), regardless of button alignment
  • Secondary action is to the left of the primary action

The disadvantage here is that it feels “unnatural” for the primary action to be second in a settings form context. It seems like the primary action should be the leftmost one because that’s where the eye travels.

Option C


  • The visual and DOM button order is different, depending on button group alignment
  • If button group is aligned to the right, the primary action is second (to the right)
  • If button group is aligned to the left, the primary action is first (to the left)

More reading:

Change History (7)

#1 @drw158
17 months ago

Additional thoughts:

I think option C feel most natural to me personally.

I think option A could work if we restrict what types of words we use for the secondary action. For example, we could say that you shouldn't use words that describe literal forward or backward motion (e.g. back, go back, next).

Here are two real examples of option A in the wild:



Ultimately we want to avoid situations like this:


I almost pressed the “Clear” button because I thought it would be a submit button, based on the placement.

#2 @SergeyBiryukov
17 months ago

  • Component changed from General to Administration

#3 @melchoyce
17 months ago

I’m generally a fan of option C, but I don’t know how much of that is my own bias.

With the caveat that we should scope language and not include anything directional, I think option A might make the most sense for core. So, for that code editor warning, we could do [ I understand ] [ Cancel ] instead.

Related: #45972

#4 @melchoyce
17 months ago

  • Milestone changed from Awaiting Review to 5.4

This ticket was mentioned in Slack in #design by karmatosed. View the logs.

16 months ago

#6 @karmatosed
15 months ago

  • Milestone changed from 5.4 to Future Release

Noting after the design team discussed this we are putting to a future milestone, we will get to this but right now it's not going to happen in 5.4.

This ticket was mentioned in Slack in #design by estelaris. View the logs.

8 months ago

Note: See TracTickets for help on using tickets.