` element. [Docs][
## ModalFooter
+ModalFooter is the place for actions represented by the Button component. While there always must be a primary Button,
+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.
+
+```jsx
+
+ Primary action
+ Secondary action
+
+```
+
+### Footer Description
+
+Optionally, you can add a description to the footer:
+
+```jsx
+
…
+```
+
+### Footer Alignment
+
+ModalFooter can be aligned to the right (default), center, or left. These values come from the
+[dictionary][dictionary-alignment]. Using a corresponding alignment option will align the footer actions accordingly:
+
+- `right` (default)
+- `center`
+- `left`
+
+```jsx
+
…
+```
+
### API
| Name | Type | Default | Required | Description |
| ------------------ | --------------------------------------------- | ------- | -------- | ----------------------------- |
| `alignmentX` | [AlignmentX dictionary][dictionary-alignment] | `right` | ✕ | ModalFooter alignment |
| `children` | `ReactNode` | — | ✕ | Children node |
+| `description` | `string` | `null` | ✕ | Optional Footer Description |
| `UNSAFE_className` | `string` | — | ✕ | ModalFooter custom class name |
| `UNSAFE_style` | `CSSProperties` | — | ✕ | ModalFooter custom style |
-The rest of the properties are based from type of `HTMLElement`. [Docs][HTMLElementDocs]
+The rest of the properties are based on the type of `HTMLElement`. [Docs][HTMLElementDocs]
+
+## Opening the Modal
+
+Use a hook to open your Modal, e.g.:
+
+```jsx
+const [isOpen, setOpen] = useState(false);
+const toggleModal = () => setOpen(!isOpen);
+const handleClose = () => setOpen(false);
+
+
+ Open Modal
+ ;
+```
## Scrolling Long Content
-When Modals become too long for the user's viewport or device, they automatically scroll independent of the page itself.
+When Modals become too long for the user's viewport or device, they automatically scroll independently of the page itself.
+
+### Scrolling with ScrollView
To make content overflow more obvious to users, you can wrap the `ModalBody` content in a [ScrollView][scroll-view] that
takes over the responsibility for scrolling and provides visual overflow decorators, e.g.:
@@ -142,6 +244,51 @@ takes over the responsibility for scrolling and provides visual overflow decorat
```
+## Full Example
+
+When you put it all together:
+
+```jsx
+import {
+ Button,
+ Modal,
+ ModalBody,
+ ModalDialog,
+ ModalFooter,
+ ModalHeader,
+ ScrollView,
+} from '@lmc-eu/spirit-web-react/components';
+
+const [isOpen, setOpen] = useState(false);
+const toggleModal = () => setOpen(!isOpen);
+const handleClose = () => setOpen(false);
+
+
+ Open Modal
+
+
+
+
+ Title of the Modal
+
+ Modal body
+
+
+
+ Submit
+
+
+ Cancel
+
+
+
+
+```
+
[DialogElementDocs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
[ArticleElementDocs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article
[FormElementDocs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
@@ -149,3 +296,4 @@ takes over the responsibility for scrolling and provides visual overflow decorat
[HTMLElementDocs]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[dictionary-alignment]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#alignment
[scroll-view]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/src/components/ScrollView/README.md
+[mdn-dialog]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
diff --git a/packages/web-twig/src/Resources/components/Modal/README.md b/packages/web-twig/src/Resources/components/Modal/README.md
index f2c9af59d9..c5fb330b56 100644
--- a/packages/web-twig/src/Resources/components/Modal/README.md
+++ b/packages/web-twig/src/Resources/components/Modal/README.md
@@ -1,6 +1,6 @@
# Modal
-This is Twig implementation of the [Modal] component.
+This is the Twig implementation of the [Modal] component.
Modal is a composition of several subcomponents:
@@ -12,19 +12,17 @@ Modal is a composition of several subcomponents:
## Modal
-### Examples:
+Modal establishes the top layer with a backdrop. Under the hood it uses the [`
` element][mdn-dialog] which
+provides several accessibility advantages.
```twig
-
- …
-
…
```
-👉 Please note the `titleId` attribute is linked to the title inside
-[Modal Header](#modalheader) and provides an accessible name for the dialog.
+👉 Please note the `titleId` attribute is linked to the title inside the [Modal Header](#modalheader) and provides an
+accessible name for the dialog.
### API
@@ -34,27 +32,79 @@ Modal is a composition of several subcomponents:
| `titleId` | `string` | `null` | ✕ | ID of the title inside ModalHeader |
On top of the API options, you can add `data-*` or `aria-*` attributes to
-further extend component's descriptiveness and accessibility. Also, UNSAFE styling props are available,
+further extend the component's descriptiveness and accessibility. Also, UNSAFE styling props are available,
see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
These attributes will be passed to the topmost HTML element of the component.
## ModalDialog
-ModalDialog is the actual dialog window, a place for the header, body, and
-footer of the dialog.
-
-### Examples:
+ModalDialog is the actual dialog window, a place for the header, body, and footer of the dialog.
```twig
…
+```
+
+### Forms in Modal
-
+Modal can also contain interactive content like forms. For such cases, you may find it convenient to use the `