From 9c56b93b3b14cf8d9460b27f705e0877ddf4fd18 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Sun, 28 Apr 2024 13:01:29 +0200
Subject: [PATCH] Document button order guidelines

---
 packages/css/src/components/dialog/README.md  |  7 +++++
 .../src/components/Dialog/Dialog.docs.mdx     |  7 +++++
 .../src/components/Dialog/Dialog.stories.tsx  | 28 +++++++++++++++++++
 3 files changed, 42 insertions(+)

diff --git a/packages/css/src/components/dialog/README.md b/packages/css/src/components/dialog/README.md
index a95ad63d24..b1b75cc307 100644
--- a/packages/css/src/components/dialog/README.md
+++ b/packages/css/src/components/dialog/README.md
@@ -10,6 +10,13 @@ A Dialog allows the user to focus on one task or a piece of information by poppi
 - Use a dialog for short and non-frequent tasks.
   Consider using the main flow for regular tasks.
 
+## The order of buttons
+
+If your Dialog needs more than one button, put the one for the primary action first and other buttons behind it.
+Sighted users will read the primary action first, in line with the natural reading order.
+The same goes for users of screen readers, who will hear the primary action first, and users of a keyboard, who will focus the primary action first.
+Additionally, this approach keeps the order of buttons consistent on both narrow and wide screens: if the buttons don’t fit next to each other, they get stacked vertically, where having the primary action on top makes the most sense.
+
 ## Keyboard Support
 
 | key         | function                                                         |
diff --git a/storybook/src/components/Dialog/Dialog.docs.mdx b/storybook/src/components/Dialog/Dialog.docs.mdx
index 695b7275f4..59df1161f2 100644
--- a/storybook/src/components/Dialog/Dialog.docs.mdx
+++ b/storybook/src/components/Dialog/Dialog.docs.mdx
@@ -21,3 +21,10 @@ Content taller than the dialog itself will scroll.
 Click or tap the button to open a dialog.
 
 <Canvas of={DialogStories.TriggerButton} />
+
+## Vertically Stacked Buttons
+
+If the buttons don’t fit next to each other, they will stack vertically and stretch to the full width.
+View this example in a narrow window, enlarge your browser’s text size, or [use the ‘Phone’ size of the preview](?path=/story/components-containers-dialog--vertical-buttons&globals=viewport:phone).
+
+<Canvas of={DialogStories.VerticalButtons} />
diff --git a/storybook/src/components/Dialog/Dialog.stories.tsx b/storybook/src/components/Dialog/Dialog.stories.tsx
index 197e674404..c4086a376c 100644
--- a/storybook/src/components/Dialog/Dialog.stories.tsx
+++ b/storybook/src/components/Dialog/Dialog.stories.tsx
@@ -129,3 +129,31 @@ export const TriggerButton: Story = {
     ),
   ],
 }
+
+export const VerticalButtons: Story = {
+  args: {
+    actions: (
+      <>
+        <Button type="submit">Ja, ik wil doorgaan</Button>
+        <Button onClick={closeDialog} variant="tertiary">
+          Nee, toch maar terug
+        </Button>
+      </>
+    ),
+    open: true,
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ backgroundColor: '#0006', position: 'absolute', width: '100%', height: '100%' }}>
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      story: { height: '32em' },
+    },
+    viewport: { defaultViewport: 'phone' },
+  },
+}