Document button order guidelines

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                                                         |

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} />

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' },
+  },
+}