Establish guidelines for button order

[drw158]

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:

• ​Where to put buttons on forms by Adam Silver
• ​OK-Cancel or Cancel-OK? The Trouble With Buttons by NN/g

[drw158]

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.

[melchoyce]

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

[karmatosed]

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.

[joyously]

I think having the primary button first is better, because

• people don't read, so the standard flow is the default (seeing the primary before secondary reinforces that it is primary)
• for screen readers, it would be read first, so it's more efficient
• for keyboard users, it's one less tab, so it's more efficient

Keep in mind that you mentioned left and right, but it should work for RTL also, so just think of it in terms of text direction like first and last.

[chaion07]

Thanks @drw158 for reporting this. We recently reviewed this during a ​design triage session. Based on the feedback from the team we also feel like Option C is a more sensible choice. Upon further research a few other resources came to our discovery. This ​article from Invisionapp is quite handy although it focuses more on the mobile devices. We also feel that this can lead us towards creating a proper scope for new guidelines to be added to the existing ones. Cheers!

[joedolson]

In discussion in the accessibility bug scrub, we feel that this would be a very valuable commitment; inconsistency is a real annoyance across the admin.

I'm generally in favor of Option C, as well; @rcreators is more in favor of primary always first.

Practically speaking, I think we should choose the option that involves the least churn. Users have a fair amount of muscle memory involved in their behaviors, so if we can be consistent with a minimum number of changes, I'm in favor of that.