Add design guidelines documentation to readme.

README.md

@@ -26,7 +26,6 @@ in [Wolt](https://wolt.com/) products, this UI component offers a visually
 appealing and user-friendly modal sheet with multiple pages, motion animation
 for page transitions, and scrollable content within each page.
 
-# Table of Contents
 - [Examples](#examples)
   * [Coffee Maker Example](#coffee-maker-example)
   * [Playground Example](#playground-example)
@@ -40,6 +39,25 @@ for page transitions, and scrollable content within each page.
   * [Imperative and Declarative Navigation](#imperative-and-declarative-navigation)
   * [Dynamic Pagination](#dynamic-pagination)
   * [State Management Integration](#state-management-integration)
+- [Design Guidelines](#design-guidelines)
+  * [Overview](#overview)
+  * [Breakpoints](#breakpoints)
+    + [Modal Types](#modal-types)
+  * [Safe Areas](#safe-areas)
+    + [iOS](#ios)
+    + [Android](#android)
+  * [Scroll Logic](#scroll-logic)
+    + [Scroll Logic Layouts](#scroll-logic-layouts)
+  * [Modal Sheet Layouts](#modal-sheet-layouts)
+    + [Alert](#alert)
+    + [Dialog](#dialog)
+    + [Side Sheet](#side-sheet)
+    + [Bottom Sheet](#bottom-sheet)
+    + [Full Bottom Sheet](#full-bottom-sheet)
+  * [Design Considerations](#design-considerations)
+  * [Example Implementations](#example-implementations)
+    + [On Media Example](#on-media-example)
+    + [Breakpoint Adaptation](#breakpoint-adaptation)
 - [Understanding the page elements](#understanding-the-page-elements)
   * [Navigation bar widgets](#navigation-bar-widgets)
   * [Top bar and top bar title](#top-bar-and-top-bar-title)
@@ -52,6 +70,8 @@ for page transitions, and scrollable content within each page.
   * [Utilizing the Figma File](#utilizing-the-figma-file)
 - [Customizable Animations](#customizable-animations)
   * [Default Animation Style Specifications](#default-animation-style-specifications)
+    + [Pagination Animation](#pagination-animation)
+    + [Scrolling Animation](#scrolling-animation)
   * [Example Configuration](#example-configuration)
 - [Usage of WoltModalSheet Pages](#usage-of-woltmodalsheet-pages)
   * [SliverWoltModalSheetPage](#sliverwoltmodalsheetpage)
@@ -62,8 +82,12 @@ for page transitions, and scrollable content within each page.
   * [Managing Navigation Stack](#managing-navigation-stack)
     + [Adding Pages to the Stack](#adding-pages-to-the-stack)
     + [Modifying Existing Pages](#modifying-existing-pages)
+      - [Replace a specific page](#replace-a-specific-page)
+      - [Replace or update the current page](#replace-or-update-the-current-page)
+      - [Remove a specific page](#remove-a-specific-page)
+      - [Add or replace pages](#add-or-replace-pages)
   * [Navigation Between Pages](#navigation-between-pages)
-    + [Moving Previous or Next](#moving-previous-or-next)
+    + [Direct navigation](#direct-navigation)
     + [Pushing Pages](#pushing-pages)
     + [Popping Page](#popping-page)
   * [Dynamic Navigation with ValueNotifiers](#dynamic-navigation-with-valuenotifiers)
@@ -145,6 +169,119 @@ such as Bloc and Provider
 </br>
 </br>
 
+## Design Guidelines
+
+This section outlines the design guidelines for the modal sheet component, including breakpoints, safe areas, scroll logic, and behavior across different devices. The guidelines are based on the Wolt design system specs.
+
+### Overview
+
+The modal sheet component is used to display critical information or interactive elements to users in a non-intrusive way. This component adapts to different screen sizes and orientations, ensuring a consistent and accessible user experience.
+
+### Breakpoints
+
+The modal sheet component adjusts its layout based on the following breakpoints:
+
+- **Breakpoint Large**: Width ≥ 1400px
+- **Breakpoint Medium**: 768px ≤ Width < 1400px
+- **Breakpoint Small**: 524px ≤ Width < 768px
+- **Breakpoint XSmall**: Width < 524px
+
+![Breakpoints](https://github.com/woltapp/wolt_modal_sheet/blob/main/doc/breakpoints_design_guidelines.png?raw=true)
+
+#### Modal Types
+
+- **Alert**: Used for critical information that requires immediate attention.
+- **Dialog**: Used for single user actions or to convey information related to changes in state (success, errors).
+- **Side Sheet**: Used to focus users' attention on a specific task while keeping the context visible.
+- **Bottom Sheet**: Used for additional options or actions, and can be used instead of a dialog in smaller screen sizes.
+- **Full Bottom Sheet**: Used to present content that requires full screen height, and can be used instead of a side sheet in smaller screen sizes.
+
+### Safe Areas
+The Modal Sheet supports safe areas for all compatible devices. See below the safe area considerations.
+
+#### iOS
+
+1. **iPhone without Notch**:
+    - Status Bar Height: 20 points
+    - Safe Area Insets:
+        - Top: 20 points
+        - Bottom: 0 points (unless there's a home indicator)
+
+2. **iPhone with Notch (iPhone X and later)**:
+    - Status Bar Height: 44 points (varies with device)
+    - Safe Area Insets:
+        - Top: 44 points
+        - Bottom: 34 points (home indicator area)
+
+#### Android
+
+1. **Standard Devices**:
+    - Status Bar Height: Approximately 24 dp (varies with screen density and device)
+    - Safe Area Insets:
+        - Top: 24 dp (status bar)
+        - Bottom: Varies (on-screen navigation bars, if any)
+
+2. **Devices with Notch (Display Cutout)**:
+    - Status Bar Height: Varies depending on the notch size
+    - Safe Area Insets:
+        - Top: Varies with notch (retrieved using DisplayCutout API)
+        - Bottom: Varies (on-screen navigation bars, if any)
+
+### Scroll Logic
+
+The modal sheet component supports different scrolling behaviors to ensure usability and accessibility of the content:
+
+- **Non-scrollable Modals**: For content that fits within the viewport, no scrolling is required. The entire modal content is visible without interaction.
+- **Scrollable Modals**: When content exceeds the viewport height, the modal becomes scrollable. Users can scroll through the content while the modal's header and action buttons remain fixed for easy access.
+
+#### Scroll Logic Layouts
+
+- **Short Content**: Displayed fully within the viewport without scrolling.
+- **Medium Content**: Scrolls vertically if the content exceeds the available height but keeps action buttons fixed at the bottom.
+- **Long Content**: Utilizes full vertical scrolling. The header remains sticky at the top while action buttons are sticky at the bottom for continuous access.
+
+### Modal Sheet Layouts
+
+#### Alert
+- Used to display information requiring immediate user attention.
+- Adapts to different breakpoints to ensure visibility and accessibility.
+- Must be dismissed by user interaction to ensure the alert is acknowledged.
+
+#### Dialog
+- Should be dedicated to completing a single task or state change information (success, errors).
+- Scales with breakpoints to maintain usability.
+- Provides clear actions for users to acknowledge or dismiss the dialog.
+
+#### Side Sheet
+- Used to focus users' attention on specific tasks while keeping context visible.
+- Spans the full height of the viewport.
+
+#### Bottom Sheet
+- Provides additional options or actions without leaving the current context.
+- Auto height adjustment for optimal content display.
+- Can be modal or persistent. Modal bottom sheets are dismissed by a user action, while persistent ones remain until manually dismissed.
+
+#### Full Bottom Sheet
+- Utilized for content that requires full screen height.
+- Appears as an overlay, occupying the entire vertical viewport.
+- Ideal for complex tasks that require more space and user attention.
+
+### Design Considerations
+
+- **Accessibility**: Ensure all modal sheets are accessible by supporting screen readers and keyboard navigation. It is important to add close affordances either as a close button in the navigation bar and an additional screen reader close affordance as part of the scrim (grayed area).
+- **Visibility**: Modals have a clear visual distinction from the background to ensure they are easily noticeable.
+- **Responsiveness**: Modals adapt seamlessly to different screen sizes and orientations.
+
+### Example Implementations
+
+#### On Media Example
+- Modals should be translucent, ensuring the background remains visible to provide context.
+
+![On Media](https://github.com/woltapp/wolt_modal_sheet/blob/main/doc/on_media_design_guidelines.png?raw=true)
+
+#### Breakpoint Adaptation
+- Modals adapt to various breakpoints seamlessly to maintain usability and accessibility across different devices and screen sizes.
+
 ## Understanding the page elements
 
 Each element within the WoltModalSheet has a role to play, offering context,