feat: Start-align Dialog buttons and place the primary button first

packages/css/src/components/button/button.scss

@@ -15,6 +15,7 @@
   font-family: var(--ams-button-font-family);
   font-size: var(--ams-button-font-size);
   gap: var(--ams-button-gap);
+  justify-content: center;
   line-height: var(--ams-button-line-height);
   outline-offset: var(--ams-button-outline-offset);
   padding-block: var(--ams-button-padding-block);

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 the 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.
+Also, this approach keeps the order of buttons consistent on both narrow and wide screens: if the buttons do not fit next to each other, they get stacked vertically with the primary action on top.
+
 ## Keyboard Support
 
 | key         | function                                                         |

packages/css/src/components/dialog/dialog.scss

@@ -3,8 +3,6 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/breakpoint";
-
 .ams-dialog {
   background-color: var(--ams-dialog-background-color);
   border: var(--ams-dialog-border);
@@ -48,11 +46,13 @@
 
 .ams-dialog__footer {
   display: flex;
-  flex-direction: column;
-  grid-gap: var(--ams-dialog-footer-gap);
+  flex-wrap: wrap; // [1]
+  gap: var(--ams-dialog-footer-gap);
+  margin-inline-end: auto; // [1]
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    flex-direction: row;
-    justify-content: end;
+  > * {
+    flex: auto; // [1]
   }
 }
+
+// [1] This combination stacks the buttons vertically and stretches them, until they fit next to each other.

storybook/src/components/Dialog/Dialog.docs.mdx

@@ -21,3 +21,18 @@ Content taller than the dialog itself will scroll.
 Click or tap the button to open a dialog.
 
 <Canvas of={DialogStories.TriggerButton} />
+
+Some basic example code to open and close a dialog:
+
+```ts
+const openDialog = () => (document.querySelector("#openDialog") as HTMLDialogElement)?.showModal();
+
+const closeDialog = (e: MouseEvent<HTMLButtonElement>) => e.currentTarget.closest("dialog")?.close();
+```
+
+## 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

@@ -5,26 +5,31 @@
 
 import { Button, Dialog, Heading, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
+import { MouseEvent } from 'react'
+
+const closeDialog = (event: MouseEvent<HTMLButtonElement>) => {
+  return event.currentTarget.closest('dialog')?.close()
+}
 
 const meta = {
   title: 'Components/Containers/Dialog',
   component: Dialog,
   args: {
-    title: 'Weet u het zeker?',
-    children: (
-      <Paragraph>
-        Weet u zeker dat u door wilt gaan met het uitvoeren van deze actie? Alle niet-opgeslagen data zal worden
-        verwijderd.
-      </Paragraph>
-    ),
     actions: (
       <>
-        <Button variant="tertiary" onClick={(event) => event.currentTarget.closest('dialog')?.close()}>
-          Terug
+        <Button type="submit">Doorgaan</Button>
+        <Button onClick={closeDialog} variant="tertiary">
+          Stoppen
         </Button>
-        <Button type="submit">Verder</Button>
       </>
     ),
+    children: (
+      <Paragraph>
+        Weet u zeker dat u door wilt gaan met het uitvoeren van deze actie? Dat verwijdert gegevens die nog niet
+        opgeslagen zijn.
+      </Paragraph>
+    ),
+    title: 'Niet alle gegevens zijn opgeslagen',
   },
   argTypes: {
     actions: {
@@ -58,10 +63,9 @@ export const Default: Story = {
 
 export const WithScrollbar: Story = {
   args: {
-    open: true,
-    title: 'Privacyverklaring gemeente Amsterdam',
+    actions: <Button onClick={closeDialog}>Sluiten</Button>,
     children: [
-      <Heading size="level-4" key={1}>
+      <Heading level={2} size="level-5" key={1}>
         Algemeen
       </Heading>,
       <Paragraph key={2}>
@@ -82,7 +86,7 @@ export const WithScrollbar: Story = {
         ook wijzigingen zijn in de wijze van het verwerken van persoonsgegevens. Wij raden u daarom aan om regelmatig
         deze pagina te bekijken. Deze pagina wordt doorlopend geactualiseerd.
       </Paragraph>,
-      <Heading size="level-4" key={6}>
+      <Heading level={2} size="level-5" key={6}>
         Geldende wet- en regelgeving en reikwijdte
       </Heading>,
       <Paragraph key={7}>
@@ -92,6 +96,8 @@ export const WithScrollbar: Story = {
         vinden op de website van Autoriteit Persoonsgegevens.
       </Paragraph>,
     ],
+    open: true,
+    title: 'Privacyverklaring gemeente Amsterdam',
   },
   decorators: [
     (Story) => (
@@ -109,14 +115,6 @@ export const WithScrollbar: Story = {
 export const TriggerButton: Story = {
   args: {
     id: 'openDialog',
-    actions: (
-      <>
-        <Button variant="tertiary" autoFocus onClick={(event) => event.currentTarget.closest('dialog')?.close()}>
-          Terug
-        </Button>
-        <Button type="submit">Verder</Button>
-      </>
-    ),
   },
   decorators: [
     (Story) => (
@@ -129,3 +127,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' },
+  },
+}