More editing

articles/building-apps/presentation-layer/design/responsiveness.adoc

@@ -4,6 +4,12 @@ description:
 order: 20
 ---
 
+// TODO The following terms should be explained somewhere (not necessarily on this page):
+// - Viewport
+// - Overlay
+// - Navbar
+// - Hamburger menu
+
 
 = Responsiveness
 :toclevels: 2
@@ -20,17 +26,17 @@ You can optimize a user interface for a small touchscreen in different ways, dep
 
 The most lightweight option is to reduce the number of features on smaller screens. This works for applications that are primarily used on the desktop, and whose mobile UI is used only from time to time to access read-only data or simple workflows. For instance, users may not need to do system administration and heavy data entry on their mobiles. 
 
-In the following example, you can see two variants of the same user interface. On the left is the desktop variant with all the features. On the right is the mobile variant with less filters.
+In the following example, you can see two variants of the same user interface. On the left is the desktop variant with all the features. On the right is the mobile variant with less filters:
 
 [link=images/responsiveness1.png]
 image::images/responsiveness1.png[Desktop UI on the left; Mobile UI with less filters on the right]
 
 
-=== Build a Responsive System
+=== Build a Responsive UI
 
 The next option is to adapt the entire user interface to be mobile friendly. To make this easy, you should base the UI on a design system that takes responsiveness into account. In practice, you use CSS https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries[media queries] and https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries[container queries] to make responsive UI building blocks. To reduce the need for one-off, view specific overrides, the building blocks should adapt to the viewport size independently.
 
-In the following example, the mobile variant of the user interface contains all the filters of the desktop variant. To adapt to the smaller viewport, the filter panel shows up as an overlay that the user can show and hide as needed. 
+In the following example, the mobile variant of the user interface contains all the filters of the desktop variant. To adapt to the smaller viewport, the filter panel shows up as an overlay that the user can show and hide as needed:
 
 [link=images/responsiveness2.png]
 image::images/responsiveness2.png[Desktop UI on left; Mobile UI with filter panel as overlay on right]
@@ -40,57 +46,61 @@ image::images/responsiveness2.png[Desktop UI on left; Mobile UI with filter pane
 
 If the mobile variant of your user interface is as important as the desktop variant, you should start by designing the mobile variant. This approach is called "mobile first". The user experience on mobile becomes more natural without the burden of an existing desktop design. Once the mobile UI is ready, you adapt it to larger viewport sizes for the desktop variant.
 
-The following example shows a UI design that was first made for mobile, and then adapted to the desktop. The use case is the same as in the earlier examples, but the desktop variant is based on the mobile variant and not vice versa.
+The following example shows a UI design that was first made for mobile, and then adapted to the desktop. The use case is the same as in the earlier examples, but the desktop variant is based on the mobile variant and not vice versa:
 
 [link=images/responsiveness3.png]
 image::images/responsiveness3.png[Mobile UI with a list of cards on left; Desktop UI with a list of cards on right]
 
 Adapting a mobile user interface to the desktop is not only about adjusting the size of elements. For instance, a workflow may consist of a series of smaller steps on the mobile that can be combined on the desktop.
 
 
-=== Separate User Interfaces
+=== Build Separate UIs
 
 The approaches covered so far have been compromises: either the mobile UI is a variant of the desktop UI or vice versa. When the best possible user experience is required for both, you should develop the user interfaces independently from each other. However, this doubles the effort and amount of UI code. You may also need to create separate backend services for each UI, making the application more complex. This in turn makes it more expensive to add new features and make changes.
 
 Because of this, you should aim for a responsive user interface, and only create separate versions for the parts where it is needed. For instance, QR code scanning, or a full-screen map, may benefit from having their own UI implementations for mobile and desktop.
 
-The following example shows a mobile UI that relies on swipe gestures, while the desktop version has totally different interaction patterns.
+The following example shows a mobile UI that relies on swipe gestures, while the desktop version has totally different interaction patterns:
 
 [link=images/responsiveness4.png]
-image::images/responsiveness4.png[Mobile UI with touch slider on the left; Desktop UI with data grid on the right]
+image::images/responsiveness4.png[Mobile UI with a touch slider on the left; Desktop UI with a data grid on the right]
+
 
+=== Design for Fluid Screen Sizes
 
-=== What Screen Sizes Should I Design for?
+Avoid designing explicitly for any specific screen resolution like 1920x1080 or “iPhone 22 Pro”. Even if your users have a specific hardware setup they would still benefit from being able to resize their browser window to half screen, or use browser zoom. The design tool canvas needs to have some size, but consider that to be fluid. Also, the browser window is often smaller than the screen resolution. Push yourself to test how your design adapts to larger and smaller sizes.
 
-Avoid designing explicitly for any specific screen resolution like 1920x1080 or “iPhone 22 Pro”. Even if your users are known to have a very specific hardware setup they would still benefit from being able to resize their browser window to half screen or use browser zoom. The design tool artboard needs to have some size, but consider that to be fluid. Push yourself to test how your design adapts to larger and smaller sizes. Especially note that the browser window tends to be much narrower than the screen resolution. Image below demonstrates that on a 1270x900 screen roughly 75% of height is actually available for the browser content.
+The following image demonstrates that only 75% of the height is actually available for the browser content on a 1270x900 screen:
 
 image::images/responsiveness-browser-size.png[Height of browser content area is 697px while screen height is 900px]
 
 
-== Responsive Features in Vaadin Components
+== Responsive Features in Vaadin
 
-Some of the components have responsive features built into them. For example the image below shows that the position of the Date Picker's overlay is changed to optimize for touchscreen devices.
+Some <<{articles}/components#,Vaadin components>> have responsive features built into them. For example, the position of the <<{articles}/components/date-picke#,Date Picker's>> overlay is changed to optimize for touchscreen devices. This is demonstrated in the following image, with the desktop version on the left, and the mobile version on the right:
 
 image::images/responsiveness-date-picker.png[Left field has overlay below field; Right shows overlay docked to bottom of viewport]
 
+The following table contains an overview of the responsive features of each component:
+
 [cols="1,2"]
 |===
-|Component|Responsive features
-
-|App Layout|Navigation drawer can be displayed as an overlay or bottom navbar. Drawer automatically collapses to hamburger menu on small viewports.
-|Dashboard|Reflow content automatically to optimize use of available space.
-|Charts|All chart types can be configured to fill any available space. Charts will scale in real time when container size changes.
-|Dialog, Confirm Dialog|Button toolbar changes to vertical layout when space is limited.
-|Context Menu|Overlay is displayed as fixed to bottom of screen on mobile sizes.
-|CRUD|Editor is always shown as an overlay on small viewports.
-|Date Picker|Overlay is displayed as fixed to bottom of screen on mobile sizes.
-|Email Field|Email specific touchscreen keyboard is used if provided by OS.
-|Form Layout|By default, contents displayed in two columns are shown in a single column on mobile sizes.
-|Menu Bar|Overflow menu appears when items don't fit in the width of the element.
-|Number Field|Number specific touchscreen keyboard is used if provided by OS
-|Password Field|Mobile browsers can display the typed character for a moment before obscuring it.
-|Select|Overlay is displayed as fixed to bottom of screen on mobile sizes.
-|Tabs|Horizontal scroll buttons appear when tabs don't fit in the width of the element. Container is horizontally scrollable.
+|Component|Responsive Features
+
+|<<{articles}/components/app-layout#,App Layout>>|The navigation drawer can be displayed as an overlay or bottom navbar. The drawer automatically collapses to a hamburger menu on small viewports.
+|<<{articles}/components/board#,Board>>|The layout is automatically optimized and adjusted based on the screen size.
+|<<{articles}/components/charts#,Charts>>|All chart types can be configured to fill any available space. Charts scale in real time when the container size changes.
+|<<{articles}/components/context-menu#,Context Menu>>|The menu is fixed to the bottom of the screen on small viewports.
+|<<{articles}/components/crud#,CRUD>>|The editor is always shown as an overlay on small viewports.
+|<<{articles}/components/date-picker#,Date Picker>>|The calendar is fixed to the bottom of the screen on small viewports.
+|<<{articles}/components/dialog#,Dialog>>, <<{articles}/components/confirm-dialog#,Confirm Dialog>>|The button toolbar changes to a vertical layout when space is limited.
+|<<{articles}/components/email-field#,Email Field>>|An email specific touchscreen keyboard is used if provided by the OS.
+|<<{articles}/components/form-layout#,Form Layout>>|The label positions and number of columns are adjusted based on the screen size.
+|<<{articles}/components/menu-bar#,Menu Bar>>|An overflow menu appears when items don't fit into the width of the menu bar.
+|<<{articles}/components/number-field#,Number Field>>|A number specific touchscreen keyboard is used if provided by the OS.
+|<<{articles}/components/password-field#,Password Field>>|Mobile browsers can display the typed character for a moment before obscuring it.
+|<<{articles}/components/select#,Select>>|The overlay is fixed to bottom of the screen on small viewports.
+|<<{articles}/components/tabs#,Tabs>>|Horizontal scroll buttons appear when tabs don't fit into the width of the tab bar. The tab bar is also horizontally scrollable.
 |===