From 403cc0b6108ed94ec9375557f9180f91c7cf2ffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= <crishpeen@gmail.com>
Date: Thu, 2 Nov 2023 11:18:33 +0100
Subject: [PATCH] Docs(web, web-twig, web-react): Document ModalHeader and
 ModalFooter usage recommendations #DS-1033

---
 packages/web-react/src/components/Modal/README.md          | 7 +++++++
 packages/web-twig/src/Resources/components/Modal/README.md | 7 +++++++
 packages/web/src/scss/components/Modal/README.md           | 7 +++++++
 3 files changed, 21 insertions(+)

diff --git a/packages/web-react/src/components/Modal/README.md b/packages/web-react/src/components/Modal/README.md
index e0815b8b2a..e616becaf3 100644
--- a/packages/web-react/src/components/Modal/README.md
+++ b/packages/web-react/src/components/Modal/README.md
@@ -131,6 +131,9 @@ Also, all properties of the [`<article>` element][mdn-article] and [`<form>` ele
 
 ModalHeader contains the title of the dialog and the close button.
 
+ℹ️ We strongly recommend providing the ModalHeader in every use case to ensure the dialog is accessible
+and allows users to easily close it.
+
 ```jsx
 <ModalHeader>Modal Title</ModalHeader>
 ```
@@ -189,6 +192,10 @@ secondary actions are optional.
 👉 Please note the actions are _visually_ ordered from right to left from the tablet breakpoint up. However, the
 _actual_ order in code is followed when users tab over the interface.
 
+ℹ️ We strongly recommend including the ModalFooter with at least one primary action in every use case to facilitate
+user interaction and ensure consistent spacing within the dialog. Should the ModalFooter be omitted, please ensure
+to compensate for the lost spacing by applying utility spacing classes to the ModalBody.
+
 ```jsx
 <ModalFooter>
   <Button color="primary">Primary action</Button>
diff --git a/packages/web-twig/src/Resources/components/Modal/README.md b/packages/web-twig/src/Resources/components/Modal/README.md
index 3f1b3842ec..f253f952f5 100644
--- a/packages/web-twig/src/Resources/components/Modal/README.md
+++ b/packages/web-twig/src/Resources/components/Modal/README.md
@@ -135,6 +135,9 @@ are allowed when the `elementType` is set to `form`.
 
 ModalHeader contains the title of the dialog and the close button.
 
+ℹ️ We strongly recommend providing the ModalHeader in every use case to ensure the dialog is accessible
+and allows users to easily close it.
+
 ```twig
 <ModalHeader modalId="modal-example" titleId="modal-example-title">
   Title of the Modal
@@ -202,6 +205,10 @@ secondary actions are optional.
 👉 Please note the actions are _visually_ ordered from right to left from the tablet breakpoint up. However, the
 _actual_ order in code is followed when users tab over the interface.
 
+ℹ️ We strongly recommend including the ModalFooter with at least one primary action in every use case to facilitate
+user interaction and ensure consistent spacing within the dialog. Should the ModalFooter be omitted, please ensure
+to compensate for the lost spacing by applying utility spacing classes to the ModalBody.
+
 ```twig
 <ModalFooter>
   <Button color="primary">Primary action</Button>
diff --git a/packages/web/src/scss/components/Modal/README.md b/packages/web/src/scss/components/Modal/README.md
index f2d88ec8bf..ad576a2afe 100644
--- a/packages/web/src/scss/components/Modal/README.md
+++ b/packages/web/src/scss/components/Modal/README.md
@@ -102,6 +102,9 @@ the class, the dialog shrinks to fit the height of its content (if smaller than
 
 ModalHeader contains the title of the dialog and the close button.
 
+ℹ️ We strongly recommend providing the ModalHeader in every use case to ensure the dialog is accessible
+and allows users to easily close it.
+
 ```html
 <div class="ModalHeader">
   <h2 id="example_1_title" class="ModalHeader__title">Modal Title</h2>
@@ -154,6 +157,10 @@ secondary actions are optional.
 👉 Please note the actions are _visually_ ordered from right to left from the tablet breakpoint up. However, the
 _actual_ order in code is followed when users tab over the interface.
 
+ℹ️ We strongly recommend including the ModalFooter with at least one primary action in every use case to facilitate
+user interaction and ensure consistent spacing within the dialog. Should the ModalFooter be omitted, please ensure
+to compensate for the lost spacing by applying utility spacing classes to the ModalBody.
+
 ```html
 <div class="ModalFooter ModalFooter--right">
   <div class="ModalFooter__actions">