From f05e854f924949c8eb1328a628715224e2a4ebb6 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 7 Sep 2023 16:22:32 -0400 Subject: [PATCH 01/37] add first draft of docs --- docs/layout/dynamic-font-scaling.md | 102 ++++++++++++++++++++++++++++ docs/layout/global-stylesheets.md | 2 +- sidebars.js | 1 + 3 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 docs/layout/dynamic-font-scaling.md diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md new file mode 100644 index 00000000000..53b38a00764 --- /dev/null +++ b/docs/layout/dynamic-font-scaling.md @@ -0,0 +1,102 @@ +# Dynamic Font Scaling + +Dynamic Font Scaling is a feature that allows users to choose the size of the text displayed on the screen. This helps users who need larger text for better readability, and it also accommodates users who can read smaller text. + +## Enabling Dynamic Font Scaling in Ionic + +:::note +This feature is currently opt-in on iOS. However, it will be enabled by default starting in Ionic 8 at which point the following CSS will no longer be necessary. +::: + +Dynamic Font Scaling is already enabled by default on Android. Developers can enable it on iOS by setting the following CSS globally: + +```css +html { + --ion-dynamic-type: var(--ion-default-dynamic-font); +} +``` + +Under the hood, Ionic sets the following CSS on iOS devices to enable Dynamic Font Scaling: + +```css +html { + font: var(--ion-dynamic-type); +} +``` + +Developers should ensure that the [typography.css](./global-stylesheets#typographycss) file is imported. + +## Integrating Custom Components with Dynamic Font Scaling + +Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any pixel font sizes to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically 16px. + +For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. + +Developers should also audit their applications and make any other changes necessary to support larger font sizes. One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. As a result, it may be necessary to change properties such as `width` and `height` to `min-width` and `min-height`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. + +Also note that any Ionic components that have had their font sizes overridden should also be audited to use `rem` units. + +## Using a Custom Font Family with Dynamic Font Scaling + +We recommend using the default fonts in Ionic as they are designed to look good at any size and ensure consistency with other mobile apps. However, developers can use a custom font family with Dynamic Font Scaling via CSS: + +```css +html { + --ion-dynamic-type: var(--ion-default-dynamic-font); + --ion-font-family: "Comic Sans"; +} +``` + +## How Dynamic Font Scaling works in Ionic + +All Ionic components that define font sizes use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. + +### iOS + +Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically#overview). To do this, Ionic sets the [font](https://developer.mozilla.org/en-US/docs/Web/CSS/font) of the root element to an Apple-defined text style. For consistency, Ionic uses the [body](https://developer.apple.com/documentation/uikit/uifont/textstyle/1616682-body) text style. + +Using the Apple-defined text style enables Dynamic Type, allowing all text in Ionic components to scale according to the system-level preference. Note that these Apple-defined fonts only work on Apple devices. As a result, these fonts will not work on Android devices even if your app is using `'ios'` mode. + +Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. For example, content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` or `ion-footer`. Additionally, certain components will have minimum font sizes so they remain readable. + +### Android + +The Android Web View's font scaling mechanism is always enabled in web content and will automatically scale the computed font sizes. This means that any maximum or minimum font sizes specified will still be scaled even if the final font size does not align with the maximum or minimum font sizes specified. + +For example, if Android has a font scale of 1.3 (i.e. The font size should be increased 30%) and the maximum font size for an element is `20px`, the computed font size for the element will actually be `26px` because Android will account for the system-level font scale since `20px * 1.3 = 26px`. + +## How to change the font size on a device + +Font scaling preferences are configured on a per-device basis by the user. This allows the user to scale the font for all applications that support this behavior. This guide shows how to enable font scaling for each platform. + +### iOS + +Font scaling on iOS can be configured in Settings > Accessibility > Display & Text Size > Larger Text. The slider on that page allows users to make the text larger or smaller across all apps that support font scaling. + +Users can also tap the "Large Accessibility Sizes" switch to access more font scale options. + +### Android + +Font scaling on Android can be configured in Settings > Accessibility > Display size and text. The "Font size" slider on that page allows users to make the text larger or smaller across all apps that support font scaling. + +## Troubleshooting + +### Maximum and minimum font sizes are not being respected on Android + +The Android Web View scales the computed font sizes by the system-level font scale preference. This means that actual font sizes may be larger or smaller than the font sizes defined in [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min), [max()](https://developer.mozilla.org/en-US/docs/Web/CSS/max), or [clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp). + +### Font sizes are larger/smaller even with Dynamic Font Scaling disabled + +Ionic components define font sizes using [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) even when Dynamic Font Scaling is disabled. This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. As a result, if the font size of `html` changes, the computed font size of all Ionic components will change too. + +### Scaled Ionic iOS component font sizes do not exactly match native iOS equivalents + +Certain native iOS components such as the Action Sheet make use of private font scales that Ionic does not have access to. While we try to stay as close as possible to the native behavior, some components may render slightly larger or smaller than their native counterparts. + +### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling + +The root element's default font size is typically 16px. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style which has a default font size 17px](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications). Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. + +:::note +iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. +::: \ No newline at end of file diff --git a/docs/layout/global-stylesheets.md b/docs/layout/global-stylesheets.md index 0078859a52b..a271094eafe 100644 --- a/docs/layout/global-stylesheets.md +++ b/docs/layout/global-stylesheets.md @@ -34,7 +34,7 @@ Applies styles to `` and defaults `box-sizing` to `border-box`. It ensures #### typography.css -Typography changes the font-family of the entire document and modifies the font styles for heading elements. It also applies positioning styles to some native text elements. +Typography changes the font-family of the entire document and modifies the font styles for heading elements. It also applies positioning styles to some native text elements. This file is necessary for [Dynamic Font Scaling](./dynamic-font-scaling) to work. #### normalize.css diff --git a/sidebars.js b/sidebars.js index c08a43ada8f..3b98d432c71 100644 --- a/sidebars.js +++ b/sidebars.js @@ -41,6 +41,7 @@ module.exports = { }, 'layout/global-stylesheets', 'layout/css-utilities', + 'layout/dynamic-font-scaling' ], }, { From 2ef4ef235c2c75f651dde48c4c673978e9d90cdd Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 7 Sep 2023 16:24:28 -0400 Subject: [PATCH 02/37] clarity --- docs/layout/dynamic-font-scaling.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 53b38a00764..44d4d42d027 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -57,7 +57,11 @@ Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Ty Using the Apple-defined text style enables Dynamic Type, allowing all text in Ionic components to scale according to the system-level preference. Note that these Apple-defined fonts only work on Apple devices. As a result, these fonts will not work on Android devices even if your app is using `'ios'` mode. -Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. For example, content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` or `ion-footer`. Additionally, certain components will have minimum font sizes so they remain readable. +Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. This means a few things: + +1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` or `ion-footer`. +2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. +3. Components such as `ion-tab-bar` and `ion-picker` do not scale according to Apple's Human Interface Guidelines. ### Android From a9c4033bb6c0fc6aabe38d25d8ab2eb66b221fbb Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Thu, 7 Sep 2023 16:24:54 -0400 Subject: [PATCH 03/37] typo --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 44d4d42d027..91006a26d76 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -61,7 +61,7 @@ Ionic follows [Apple's Human Interface Guidelines for Typography](https://develo 1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` or `ion-footer`. 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. -3. Components such as `ion-tab-bar` and `ion-picker` do not scale according to Apple's Human Interface Guidelines. +3. Text in components such as `ion-tab-bar` and `ion-picker` do not scale according to Apple's Human Interface Guidelines. ### Android From cf55ded2cbe0a9e532e572bed5319d991612314c Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 09:38:13 -0400 Subject: [PATCH 04/37] add more troubleshooting/guidance --- docs/layout/dynamic-font-scaling.md | 105 ++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 7 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 91006a26d76..58885167a76 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -2,6 +2,12 @@ Dynamic Font Scaling is a feature that allows users to choose the size of the text displayed on the screen. This helps users who need larger text for better readability, and it also accommodates users who can read smaller text. +Dynamic Font Scaling is supported on Android, iOS, and iPadOS starting in Ionic v7.5. + +## Try It Out + +Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo below grow or shrink according to your preferences. + ## Enabling Dynamic Font Scaling in Ionic :::note @@ -12,7 +18,7 @@ Dynamic Font Scaling is already enabled by default on Android. Developers can en ```css html { - --ion-dynamic-type: var(--ion-default-dynamic-font); + --ion-dynamic-font: var(--ion-default-dynamic-font); } ``` @@ -20,13 +26,15 @@ Under the hood, Ionic sets the following CSS on iOS devices to enable Dynamic Fo ```css html { - font: var(--ion-dynamic-type); + font: var(--ion-dynamic-font); } ``` Developers should ensure that the [typography.css](./global-stylesheets#typographycss) file is imported. -## Integrating Custom Components with Dynamic Font Scaling +## Using Dynamic Font Scaling + +### Integrating Custom Components Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any pixel font sizes to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically 16px. @@ -36,7 +44,7 @@ Developers should also audit their applications and make any other changes neces Also note that any Ionic components that have had their font sizes overridden should also be audited to use `rem` units. -## Using a Custom Font Family with Dynamic Font Scaling +### Custom Font Family We recommend using the default fonts in Ionic as they are designed to look good at any size and ensure consistency with other mobile apps. However, developers can use a custom font family with Dynamic Font Scaling via CSS: @@ -47,6 +55,62 @@ html { } ``` +### `em` units versus `rem` units + +Developers have two options for relative font sizes: `em` and `rem`. + +`em` units set the font size of an element relative to the font size of its parent. + +In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (2em * 20px = 40px). + +```css +.parent { + font-size: 20px; +} + +.child { + font-size: 2em; +} +``` + +However, this unit can have a compounding effect which can cause issues. In the following example, the second `.child` element has a computed font size of `80px` since the font sizes compound. + +```html +
+ Parent element with 20px +
+ Child element with 40px +
+ Child element with 80px +
+
+
+``` + +
+ Parent element with 20px +
+ Child element with 40px +
+ Child element with 80px +
+
+
+ +Due to this compounding effect, we strongly recommend using `rem` units instead of `em` units when working with Dynamic Font Scaling. `rem` units set the font size of an element relative to the font size of the root element, which is typically ``. The default font size of the root element is typically `16px`. + +In the following example, the computed font size of `.child` is `32px` because the font size is being computed relative to `html`, not `.parent`. + +```css +.parent { + font-size: 20px; +} + +.child { + font-size: 2rem; +} +``` + ## How Dynamic Font Scaling works in Ionic All Ionic components that define font sizes use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. @@ -69,7 +133,7 @@ The Android Web View's font scaling mechanism is always enabled in web content a For example, if Android has a font scale of 1.3 (i.e. The font size should be increased 30%) and the maximum font size for an element is `20px`, the computed font size for the element will actually be `26px` because Android will account for the system-level font scale since `20px * 1.3 = 26px`. -## How to change the font size on a device +## Changing the Font Size on a Device Font scaling preferences are configured on a per-device basis by the user. This allows the user to scale the font for all applications that support this behavior. This guide shows how to enable font scaling for each platform. @@ -85,9 +149,36 @@ Font scaling on Android can be configured in Settings > Accessibility > Display ## Troubleshooting +### Dynamic Font Scaling is not working + +There are a number of reasons why Dynamic Font Scaling may not have any effect on an app . The following list, while not exhaustive, provides some things to check to debug why Dynamic Font Scaling is not working. + +1. Verify that your version of Ionic supports Dynamic Font Scaling. Dynamic Font Scaling was added starting in Ionic v7.5. +2. Dynamic Font Scaling is opt-in on iOS on Ionic 7. Verify that the proper CSS has been set. See [Enabling Dynamic Font Scaling in Ionic](#enabling-dynamic-font-scaling-in-ionic) for more information. +3. Verify that your code does not override the root element's default font size. Manually setting a font size on the root element will prevent Dynamic Font Scaling from working as intended. +4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components with Dynamic Font Scaling](#integrating-custom-components-with-dynamic-font-scaling) for more information. + + + ### Maximum and minimum font sizes are not being respected on Android -The Android Web View scales the computed font sizes by the system-level font scale preference. This means that actual font sizes may be larger or smaller than the font sizes defined in [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min), [max()](https://developer.mozilla.org/en-US/docs/Web/CSS/max), or [clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp). +The Android Web View scales any font sizes defined using the `px` unit by the system-level font scale preference. This means that actual font sizes may be larger or smaller than the font sizes defined in [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min), [max()](https://developer.mozilla.org/en-US/docs/Web/CSS/max), or [clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp). + +Example: + +In the following example we are using the `min()` function to indicate that the font size of `.foo` should be no larger than `14px`. + +```css +.foo { + font-size: min(1rem, 14px); +} +``` + +If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. + +This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, then the `14px` used in our `min()` function will also be scaled by 1.5. + +As a result, this means that maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. ### Font sizes are larger/smaller even with Dynamic Font Scaling disabled @@ -95,7 +186,7 @@ Ionic components define font sizes using [rem units](https://developer.mozilla.o ### Scaled Ionic iOS component font sizes do not exactly match native iOS equivalents -Certain native iOS components such as the Action Sheet make use of private font scales that Ionic does not have access to. While we try to stay as close as possible to the native behavior, some components may render slightly larger or smaller than their native counterparts. +Certain native iOS components such as the Action Sheet make use of private font scales that Ionic does not have access to. While we try to stay as close as possible to the native behavior, text in some components may render slightly larger or smaller than their native counterparts. ### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling From 9e2fb3d70897bfe102197e0bab91f9fcebde8426 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 10:01:56 -0400 Subject: [PATCH 05/37] add demo --- docs/layout/dynamic-font-scaling.md | 12 ++- .../angular/example_component_html.md | 45 ++++++++++ .../angular/global_css.md | 5 ++ .../v7/layout/dynamic-font-scaling/demo.html | 65 +++++++++++++++ .../v7/layout/dynamic-font-scaling/index.md | 34 ++++++++ .../layout/dynamic-font-scaling/javascript.md | 51 ++++++++++++ .../dynamic-font-scaling/react/main_css.md | 5 ++ .../dynamic-font-scaling/react/main_tsx.md | 59 +++++++++++++ .../v7/layout/dynamic-font-scaling/vue.md | 82 +++++++++++++++++++ 9 files changed, 356 insertions(+), 2 deletions(-) create mode 100644 static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/demo.html create mode 100644 static/usage/v7/layout/dynamic-font-scaling/index.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/javascript.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/react/main_css.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/vue.md diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 58885167a76..2af5fb3f745 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -6,11 +6,19 @@ Dynamic Font Scaling is supported on Android, iOS, and iPadOS starting in Ionic ## Try It Out +:::tip +Be sure to try this on an Android, iOS, or iPadOS device. +::: + Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo below grow or shrink according to your preferences. +import DynamicFontScaling from '@site/static/usage/v7/layout/dynamic-font-scaling/index.md'; + + + ## Enabling Dynamic Font Scaling in Ionic -:::note +:::info This feature is currently opt-in on iOS. However, it will be enabled by default starting in Ionic 8 at which point the following CSS will no longer be necessary. ::: @@ -192,6 +200,6 @@ Certain native iOS components such as the Action Sheet make use of private font The root element's default font size is typically 16px. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style which has a default font size 17px](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications). Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. -:::note +:::info iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. ::: \ No newline at end of file diff --git a/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md b/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md new file mode 100644 index 00000000000..76687ae8b81 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md @@ -0,0 +1,45 @@ +```html + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md b/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md new file mode 100644 index 00000000000..2817f808062 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md @@ -0,0 +1,5 @@ +```css +html { + --ion-dynamic-font: var(--ion-default-dynamic-font); +} +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/demo.html b/static/usage/v7/layout/dynamic-font-scaling/demo.html new file mode 100644 index 00000000000..b46c569da7a --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/demo.html @@ -0,0 +1,65 @@ + + + + + + Label + + + + + + + + + + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + + + + diff --git a/static/usage/v7/layout/dynamic-font-scaling/index.md b/static/usage/v7/layout/dynamic-font-scaling/index.md new file mode 100644 index 00000000000..b5bd9d0cec2 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/index.md @@ -0,0 +1,34 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; + +import react_main_tsx from './react/main_tsx.md'; +import react_main_css from './react/main_css.md'; + +import vue from './vue.md'; + +import angular_example_component_html from './angular/example_component_html.md'; +import angular_global_css from './angular/global_css.md'; + + diff --git a/static/usage/v7/layout/dynamic-font-scaling/javascript.md b/static/usage/v7/layout/dynamic-font-scaling/javascript.md new file mode 100644 index 00000000000..3240686f9c5 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/javascript.md @@ -0,0 +1,51 @@ +```html + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + + + +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md new file mode 100644 index 00000000000..2817f808062 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md @@ -0,0 +1,5 @@ +```css +html { + --ion-dynamic-font: var(--ion-default-dynamic-font); +} +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md new file mode 100644 index 00000000000..73943a0f395 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md @@ -0,0 +1,59 @@ +```tsx +import React from 'react'; +import { IonBackButton, IonButton, IonButtons, IonCheckbox, IonContent, IonFooter, IonHeader, IonIcon, IonInput, IonItem, IonLabel, IonList, IonTitle, IonToggle, IonToolbar } from '@ionic/react'; +import { create } from 'ionicons/icons'; + +import './main.css'; + +function Example() { + return ( + <> + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + + + ); +} +export default Example; +``` + diff --git a/static/usage/v7/layout/dynamic-font-scaling/vue.md b/static/usage/v7/layout/dynamic-font-scaling/vue.md new file mode 100644 index 00000000000..124033bce77 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/vue.md @@ -0,0 +1,82 @@ +```html + + + + + +``` From 0512a8924e604dcf3328234ecd6da5643568a736 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 10:17:19 -0400 Subject: [PATCH 06/37] add clarification on how modes are implemented --- docs/layout/dynamic-font-scaling.md | 36 ++++++++++++++--------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 2af5fb3f745..d5a8467c64d 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -123,6 +123,8 @@ In the following example, the computed font size of `.child` is `32px` because t All Ionic components that define font sizes use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. +Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective devices. As a result, we strongly recommend using `'ios'` mode on iOS devices and `'md'` mode on Android devices when using Dynamic Font Scaling. + ### iOS Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically#overview). To do this, Ionic sets the [font](https://developer.mozilla.org/en-US/docs/Web/CSS/font) of the root element to an Apple-defined text style. For consistency, Ionic uses the [body](https://developer.apple.com/documentation/uikit/uifont/textstyle/1616682-body) text style. @@ -137,9 +139,21 @@ Ionic follows [Apple's Human Interface Guidelines for Typography](https://develo ### Android -The Android Web View's font scaling mechanism is always enabled in web content and will automatically scale the computed font sizes. This means that any maximum or minimum font sizes specified will still be scaled even if the final font size does not align with the maximum or minimum font sizes specified. +The Android Web View's font scaling mechanism is always enabled in web content and will automatically scale font sizes defined using the `px` unit. This means that any maximum or minimum font sizes specified using `px` will still be scaled even if the final font size does not align with the maximum or minimum font sizes specified. + +In the following example we are using the [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min) function to indicate that the font size of `.foo` should be no larger than `14px`. + +```css +.foo { + font-size: min(1rem, 14px); +} +``` + +If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. -For example, if Android has a font scale of 1.3 (i.e. The font size should be increased 30%) and the maximum font size for an element is `20px`, the computed font size for the element will actually be `26px` because Android will account for the system-level font scale since `20px * 1.3 = 26px`. +This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, then the `14px` used in our `min()` function will also be scaled by 1.5. + +As a result, this means that maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. ## Changing the Font Size on a Device @@ -166,27 +180,11 @@ There are a number of reasons why Dynamic Font Scaling may not have any effect o 3. Verify that your code does not override the root element's default font size. Manually setting a font size on the root element will prevent Dynamic Font Scaling from working as intended. 4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components with Dynamic Font Scaling](#integrating-custom-components-with-dynamic-font-scaling) for more information. - - ### Maximum and minimum font sizes are not being respected on Android The Android Web View scales any font sizes defined using the `px` unit by the system-level font scale preference. This means that actual font sizes may be larger or smaller than the font sizes defined in [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min), [max()](https://developer.mozilla.org/en-US/docs/Web/CSS/max), or [clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp). -Example: - -In the following example we are using the `min()` function to indicate that the font size of `.foo` should be no larger than `14px`. - -```css -.foo { - font-size: min(1rem, 14px); -} -``` - -If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. - -This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, then the `14px` used in our `min()` function will also be scaled by 1.5. - -As a result, this means that maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. +See [how font scaling works on Android](#android) for more information. ### Font sizes are larger/smaller even with Dynamic Font Scaling disabled From 35fa744a6302c0176f66045c816b9acf179862d5 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 10:22:03 -0400 Subject: [PATCH 07/37] add note on switching modes --- docs/layout/dynamic-font-scaling.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index d5a8467c64d..370246949bc 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -123,8 +123,6 @@ In the following example, the computed font size of `.child` is `32px` because t All Ionic components that define font sizes use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. -Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective devices. As a result, we strongly recommend using `'ios'` mode on iOS devices and `'md'` mode on Android devices when using Dynamic Font Scaling. - ### iOS Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically#overview). To do this, Ionic sets the [font](https://developer.mozilla.org/en-US/docs/Web/CSS/font) of the root element to an Apple-defined text style. For consistency, Ionic uses the [body](https://developer.apple.com/documentation/uikit/uifont/textstyle/1616682-body) text style. @@ -155,6 +153,14 @@ This is larger than our defined maximum of `14px`, so one might assume that the As a result, this means that maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. +### Using Modes on Different Platforms + +Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective devices. + +For example, `'ios'` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `'md'` mode does not implement this same behavior because Material Design does not have that same guidance. Using `'md'` mode on an iOS device may allow for very large font sizes in headers and footers. + +As a result, we strongly recommend using `'ios'` mode on iOS devices and `'md'` mode on Android devices when using Dynamic Font Scaling. + ## Changing the Font Size on a Device Font scaling preferences are configured on a per-device basis by the user. This allows the user to scale the font for all applications that support this behavior. This guide shows how to enable font scaling for each platform. From 1d497f6d63c5b156436eeedecd30f728b2ac89e1 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 10:37:09 -0400 Subject: [PATCH 08/37] typos --- docs/layout/dynamic-font-scaling.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 370246949bc..9cb1d0d33bd 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -50,7 +50,7 @@ For example, if a component has a font size of `14px`, then this could be conver Developers should also audit their applications and make any other changes necessary to support larger font sizes. One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. As a result, it may be necessary to change properties such as `width` and `height` to `min-width` and `min-height`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. -Also note that any Ionic components that have had their font sizes overridden should also be audited to use `rem` units. +Also note that any Ionic components that have had their font sizes overridden should also be updated to use `rem` units. ### Custom Font Family @@ -58,7 +58,7 @@ We recommend using the default fonts in Ionic as they are designed to look good ```css html { - --ion-dynamic-type: var(--ion-default-dynamic-font); + --ion-dynamic-font: var(--ion-default-dynamic-font); --ion-font-family: "Comic Sans"; } ``` @@ -81,7 +81,7 @@ In the following example, the computed font size of `.child` is `40px` because i } ``` -However, this unit can have a compounding effect which can cause issues. In the following example, the second `.child` element has a computed font size of `80px` since the font sizes compound. +However, the `em` unit has a compounding effect which can cause issues. In the following example, the second `.child` element has a computed font size of `80px` since the font sizes compound. ```html
@@ -131,9 +131,9 @@ Using the Apple-defined text style enables Dynamic Type, allowing all text in Io Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. This means a few things: -1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` or `ion-footer`. +1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` and `ion-footer`. 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. -3. Text in components such as `ion-tab-bar` and `ion-picker` do not scale according to Apple's Human Interface Guidelines. +3. Text in components such as `ion-tab-bar` and `ion-picker` do not participate in Dynamic Font Scaling according to Apple's Human Interface Guidelines. ### Android @@ -149,15 +149,15 @@ In the following example we are using the [min()](https://developer.mozilla.org/ If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. -This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, then the `14px` used in our `min()` function will also be scaled by 1.5. +This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, this means the `14px` used in our `min()` function will also be scaled by 1.5. -As a result, this means that maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. +As a result, this means that the maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. ### Using Modes on Different Platforms -Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective devices. +Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. -For example, `'ios'` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `'md'` mode does not implement this same behavior because Material Design does not have that same guidance. Using `'md'` mode on an iOS device may allow for very large font sizes in headers and footers. +For example, `'ios'` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `'md'` mode does not implement this same behavior because Material Design does not have that same guidance. This means that using `'md'` mode on an iOS device may allow for very large font sizes in headers and footers. As a result, we strongly recommend using `'ios'` mode on iOS devices and `'md'` mode on Android devices when using Dynamic Font Scaling. @@ -182,9 +182,9 @@ Font scaling on Android can be configured in Settings > Accessibility > Display There are a number of reasons why Dynamic Font Scaling may not have any effect on an app . The following list, while not exhaustive, provides some things to check to debug why Dynamic Font Scaling is not working. 1. Verify that your version of Ionic supports Dynamic Font Scaling. Dynamic Font Scaling was added starting in Ionic v7.5. -2. Dynamic Font Scaling is opt-in on iOS on Ionic 7. Verify that the proper CSS has been set. See [Enabling Dynamic Font Scaling in Ionic](#enabling-dynamic-font-scaling-in-ionic) for more information. +2. Dynamic Font Scaling is opt-in on iOS in Ionic 7. Verify that the proper CSS has been set. See [Enabling Dynamic Font Scaling in Ionic](#enabling-dynamic-font-scaling-in-ionic) for more information. 3. Verify that your code does not override the root element's default font size. Manually setting a font size on the root element will prevent Dynamic Font Scaling from working as intended. -4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components with Dynamic Font Scaling](#integrating-custom-components-with-dynamic-font-scaling) for more information. +4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components](#integrating-custom-components) for more information. ### Maximum and minimum font sizes are not being respected on Android @@ -202,7 +202,7 @@ Certain native iOS components such as the Action Sheet make use of private font ### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling -The root element's default font size is typically 16px. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style which has a default font size 17px](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications). Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. +The root element's default font size is typically 16px. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications) which has a default font size of 17px. Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. :::info iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. From 1ad12abbd92d47425d48dcbb93a488411cd94f0b Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 10:45:22 -0400 Subject: [PATCH 09/37] lint --- docs/layout/dynamic-font-scaling.md | 20 +++---- sidebars.js | 2 +- .../v7/layout/dynamic-font-scaling/demo.html | 10 +++- .../dynamic-font-scaling/react/main_tsx.md | 21 ++++++-- .../v7/layout/dynamic-font-scaling/vue.md | 54 ++++++++++++------- 5 files changed, 70 insertions(+), 37 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 9cb1d0d33bd..928c70d7b16 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -59,7 +59,7 @@ We recommend using the default fonts in Ionic as they are designed to look good ```css html { --ion-dynamic-font: var(--ion-default-dynamic-font); - --ion-font-family: "Comic Sans"; + --ion-font-family: 'Comic Sans'; } ``` @@ -69,8 +69,8 @@ Developers have two options for relative font sizes: `em` and `rem`. `em` units set the font size of an element relative to the font size of its parent. -In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (2em * 20px = 40px). - +In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (2em \* 20px = 40px). + ```css .parent { font-size: 20px; @@ -88,9 +88,7 @@ However, the `em` unit has a compounding effect which can cause issues. In the f Parent element with 20px
Child element with 40px -
- Child element with 80px -
+
Child element with 80px
``` @@ -99,9 +97,7 @@ However, the `em` unit has a compounding effect which can cause issues. In the f Parent element with 20px
Child element with 40px -
- Child element with 80px -
+
Child element with 80px
@@ -131,7 +127,7 @@ Using the Apple-defined text style enables Dynamic Type, allowing all text in Io Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. This means a few things: -1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` and `ion-footer`. +1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` and `ion-footer`. 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. 3. Text in components such as `ion-tab-bar` and `ion-picker` do not participate in Dynamic Font Scaling according to Apple's Human Interface Guidelines. @@ -147,7 +143,7 @@ In the following example we are using the [min()](https://developer.mozilla.org/ } ``` -If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. +If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, this means the `14px` used in our `min()` function will also be scaled by 1.5. @@ -206,4 +202,4 @@ The root element's default font size is typically 16px. However, Dynamic Font Sc :::info iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. -::: \ No newline at end of file +::: diff --git a/sidebars.js b/sidebars.js index 3b98d432c71..76e4d28bc4c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -41,7 +41,7 @@ module.exports = { }, 'layout/global-stylesheets', 'layout/css-utilities', - 'layout/dynamic-font-scaling' + 'layout/dynamic-font-scaling', ], }, { diff --git a/static/usage/v7/layout/dynamic-font-scaling/demo.html b/static/usage/v7/layout/dynamic-font-scaling/demo.html index b46c569da7a..bdec1645a91 100644 --- a/static/usage/v7/layout/dynamic-font-scaling/demo.html +++ b/static/usage/v7/layout/dynamic-font-scaling/demo.html @@ -6,8 +6,14 @@ Label - - + + -``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md deleted file mode 100644 index 2817f808062..00000000000 --- a/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md +++ /dev/null @@ -1,5 +0,0 @@ -```css -html { - --ion-dynamic-font: var(--ion-default-dynamic-font); -} -``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md deleted file mode 100644 index 863d4e269d3..00000000000 --- a/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md +++ /dev/null @@ -1,74 +0,0 @@ -```tsx -import React from 'react'; -import { - IonBackButton, - IonButton, - IonButtons, - IonCheckbox, - IonContent, - IonFooter, - IonHeader, - IonIcon, - IonInput, - IonItem, - IonLabel, - IonList, - IonTitle, - IonToggle, - IonToolbar, -} from '@ionic/react'; -import { create } from 'ionicons/icons'; - -import './main.css'; - -function Example() { - return ( - <> - - - - - - Title - - - - - - - - - - - - - - Check for a free puppy - - - Enable Notifications - - - - - - Item 1 - - - Item 2 - - - Item 3 - - - - - - Footer - - - - ); -} -export default Example; -``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/vue.md b/static/usage/v7/layout/dynamic-font-scaling/vue.md deleted file mode 100644 index 5e0f13156c6..00000000000 --- a/static/usage/v7/layout/dynamic-font-scaling/vue.md +++ /dev/null @@ -1,98 +0,0 @@ -```html - - - - - -``` From c105df8a27fceb2ec8b0d3c65754010761018f50 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 14:17:39 -0400 Subject: [PATCH 13/37] update ios instructions --- docs/layout/dynamic-font-scaling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 4ec5f54d345..57a9b381b51 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -161,9 +161,9 @@ Font scaling preferences are configured on a per-device basis by the user. This ### iOS -Font scaling on iOS can be configured in Settings > Accessibility > Display & Text Size > Larger Text. The slider on that page allows users to make the text larger or smaller across all apps that support font scaling. +Font scaling on iOS can be configured in the Settings app. -Users can also tap the "Large Accessibility Sizes" switch to access more font scale options. +See [Apple Support](https://support.apple.com/en-us/102453) for more information. ### Android From b37af9d598dbf1072e53aee75aa00662e4e34461 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 14:18:37 -0400 Subject: [PATCH 14/37] add troubleshooting --- docs/layout/dynamic-font-scaling.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 57a9b381b51..364e97980f2 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -179,6 +179,7 @@ There are a number of reasons why Dynamic Font Scaling may not have any effect o 2. Dynamic Font Scaling is opt-in on iOS in Ionic 7. Verify that the proper CSS has been set. See [Enabling Dynamic Font Scaling in Ionic](#enabling-dynamic-font-scaling-in-ionic) for more information. 3. Verify that your code does not override the root element's default font size. Manually setting a font size on the root element will prevent Dynamic Font Scaling from working as intended. 4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components](#integrating-custom-components) for more information. +5. Verify that Ionic is not being loaded inside of an `iframe`. Some variants of Android do not apply font scaling across `iframe` boundaries. ### Maximum and minimum font sizes are not being respected on Android From d0f06cd8fa4cd990901215af8d74d2f17d13d73b Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Fri, 8 Sep 2023 14:24:42 -0400 Subject: [PATCH 15/37] lint --- docs/layout/dynamic-font-scaling.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 364e97980f2..e77e7ba9819 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -12,7 +12,9 @@ Be sure to try this on an Android, iOS, or iPadOS device. Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo linked below grow or shrink according to your preferences. -Launch Dynamic Font Scaling Demo (opens in a new tab) + + Launch Dynamic Font Scaling Demo + (opens in a new tab) ## Enabling Dynamic Font Scaling in Ionic From d94841fd5e6c2cb03b8c7819451db5536a168dd8 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:36:27 -0400 Subject: [PATCH 16/37] link to ems vs rems --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index e77e7ba9819..61308a9af4b 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -65,7 +65,7 @@ html { ### `em` units versus `rem` units -Developers have two options for relative font sizes: `em` and `rem`. +Developers have two options for relative font sizes: [`em` and `rem`](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#ems_and_rems). `em` units set the font size of an element relative to the font size of its parent. From 0ed0b00e2b6d2c8e0153dbd7ba63c60888d6c938 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:36:57 -0400 Subject: [PATCH 17/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 61308a9af4b..9c262a3a220 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -143,7 +143,7 @@ In the following example we are using the [min()](https://developer.mozilla.org/ } ``` -If the root element's default font size is `16px`, and the system-level font scale is 1.5 (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. +If the root element's default font size is `16px`, and the system-level font scale is `1.5` (i.e text sizes should be increased by 50%), then `1rem` will evaluate to `24px` because `16 * 1.5 = 24`. This is larger than our defined maximum of `14px`, so one might assume that the evaluated font size of `.foo` is `14px`. However, since the Android Web View scales any font sizes defined using the `px` unit, this means the `14px` used in our `min()` function will also be scaled by 1.5. From ae4f3b7fe9e66688024edbfc23f0ecdbc28e831e Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:37:02 -0400 Subject: [PATCH 18/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 9c262a3a220..84af6d29b94 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -199,7 +199,7 @@ Certain native iOS components such as the Action Sheet make use of private font ### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling -The root element's default font size is typically 16px. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications) which has a default font size of 17px. Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. +The root element's default font size is typically `16px`. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications) which has a default font size of `17px`. Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. :::info iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. From 7263c8ae843411e4c55fd184abea18c45ca06735 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:37:08 -0400 Subject: [PATCH 19/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 84af6d29b94..c3476f11f30 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -44,7 +44,7 @@ Developers should ensure that the [typography.css](./global-stylesheets#typograp ### Integrating Custom Components -Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any pixel font sizes to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically 16px. +Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any pixel font sizes to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically `16px`. For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. From cbe79e4a05c44c55f9e4904813b643caa3bfaa67 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:37:14 -0400 Subject: [PATCH 20/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index c3476f11f30..b1dd02edb73 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -202,5 +202,5 @@ Certain native iOS components such as the Action Sheet make use of private font The root element's default font size is typically `16px`. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications) which has a default font size of `17px`. Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. :::info -iOS provides a "Callout" text style which has a default font size of 16px. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. +iOS provides a "Callout" text style which has a default font size of `16px`. However, this font style is currently not exposed to web content. See [the supported text styles in WebKit](https://webkit.org/blog/3709/using-the-system-font-in-web-content/) for more information. ::: From bf423b50aa84af723fc6a924b29b28f69e3d7295 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:37:23 -0400 Subject: [PATCH 21/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index b1dd02edb73..296a8e2d510 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -155,7 +155,7 @@ Each platform has slightly different font scaling behaviors, and the `'ios'` and For example, `'ios'` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `'md'` mode does not implement this same behavior because Material Design does not have that same guidance. This means that using `'md'` mode on an iOS device may allow for very large font sizes in headers and footers. -As a result, we strongly recommend using `'ios'` mode on iOS devices and `'md'` mode on Android devices when using Dynamic Font Scaling. +As a result, we strongly recommend using `ios` mode on iOS devices and `md` mode on Android devices when using Dynamic Font Scaling. ## Changing the Font Size on a Device From 175036ff8485d71f5aea7c3b621065c3224f93d0 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:37:28 -0400 Subject: [PATCH 22/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 296a8e2d510..7288d77a389 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -153,7 +153,7 @@ As a result, this means that the maximum computed font size is actually `21px` s Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. -For example, `'ios'` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `'md'` mode does not implement this same behavior because Material Design does not have that same guidance. This means that using `'md'` mode on an iOS device may allow for very large font sizes in headers and footers. +For example, `ios` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `md` mode does not implement this same behavior because Material Design does not have that same guidance. This means that using `md` mode on an iOS device may allow for very large font sizes in headers and footers. As a result, we strongly recommend using `ios` mode on iOS devices and `md` mode on Android devices when using Dynamic Font Scaling. From 338b4730b0c039518c63e0d303af9ff17c4444b2 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:39:44 -0400 Subject: [PATCH 23/37] clarify ionic behavior --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 7288d77a389..0bcd39ccd55 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -117,7 +117,7 @@ In the following example, the computed font size of `.child` is `32px` because t ## How Dynamic Font Scaling works in Ionic -All Ionic components that define font sizes use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. +Ionic components that define font sizes and participate in Dynamic Font Scaling typically use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. Some elements inside of these components, such as icons, use `em` units instead so the elements are sized relative to the text, though the text itself is sized using `rem` units. ### iOS From a4ad895bddb356dc330e4290790c3c947f0d0ccb Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:41:16 -0400 Subject: [PATCH 24/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 0bcd39ccd55..39f0f6bbe1f 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -123,7 +123,7 @@ Ionic components that define font sizes and participate in Dynamic Font Scaling Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically#overview). To do this, Ionic sets the [font](https://developer.mozilla.org/en-US/docs/Web/CSS/font) of the root element to an Apple-defined text style. For consistency, Ionic uses the [body](https://developer.apple.com/documentation/uikit/uifont/textstyle/1616682-body) text style. -Using the Apple-defined text style enables Dynamic Type, allowing all text in Ionic components to scale according to the system-level preference. Note that these Apple-defined fonts only work on Apple devices. As a result, these fonts will not work on Android devices even if your app is using `'ios'` mode. +Using the Apple-defined text style enables Dynamic Type, allowing all text in Ionic components to scale according to the system-level preference. Note that these Apple-defined fonts only work on Apple devices. As a result, these fonts will not work on Android devices even if your app is using `ios` mode. Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. This means a few things: From 075b66f677532a1fef244ad79e8287dbfcbc0601 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:41:27 -0400 Subject: [PATCH 25/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 39f0f6bbe1f..c9b6fedbca8 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -125,7 +125,7 @@ Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Ty Using the Apple-defined text style enables Dynamic Type, allowing all text in Ionic components to scale according to the system-level preference. Note that these Apple-defined fonts only work on Apple devices. As a result, these fonts will not work on Android devices even if your app is using `ios` mode. -Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `'ios'` mode. As a result, important content is prioritized when the text size changes. This means a few things: +Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `ios` mode. As a result, important content is prioritized when the text size changes. This means a few things: 1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` and `ion-footer`. 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. From 83aca7207f8b3e6e556783045f8977d790a3108d Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:41:40 -0400 Subject: [PATCH 26/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index c9b6fedbca8..7d13f04641d 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -127,7 +127,7 @@ Using the Apple-defined text style enables Dynamic Type, allowing all text in Io Ionic follows [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography) when an app is in `ios` mode. As a result, important content is prioritized when the text size changes. This means a few things: -1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize text in `ion-content` which is deemed more important than text in `ion-header` and `ion-footer`. +1. Content in an `ion-header` or an `ion-footer` will have maximum font sizes to prioritize content in `ion-content` which is deemed more important than content in the `ion-header` and `ion-footer`. 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. 3. Text in components such as `ion-tab-bar` and `ion-picker` do not participate in Dynamic Font Scaling according to Apple's Human Interface Guidelines. From e9a79a333c8a2f5bb8ac9933cfbda1f30702fe6c Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:41:51 -0400 Subject: [PATCH 27/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 7d13f04641d..ba009f4cd72 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -151,7 +151,7 @@ As a result, this means that the maximum computed font size is actually `21px` s ### Using Modes on Different Platforms -Each platform has slightly different font scaling behaviors, and the `'ios'` and `'md'` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. +Each platform has slightly different font scaling behaviors, and the `ios` and `md` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. For example, `ios` mode makes use of maximum and minimum font sizes to follow [Apple's Human Interface Guidelines for Typography](https://developer.apple.com/design/human-interface-guidelines/typography). `md` mode does not implement this same behavior because Material Design does not have that same guidance. This means that using `md` mode on an iOS device may allow for very large font sizes in headers and footers. From 5afefa5db75cf4da5277a04ac3217ac6866e9553 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:42:07 -0400 Subject: [PATCH 28/37] Update docs/layout/dynamic-font-scaling.md Co-authored-by: Brandy Carney --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index ba009f4cd72..e614ff7ecfc 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -69,7 +69,7 @@ Developers have two options for relative font sizes: [`em` and `rem`](https://de `em` units set the font size of an element relative to the font size of its parent. -In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (2em \* 20px = 40px). +In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (`2em \* 20px = 40px`). ```css .parent { From 7eac2a32692f22cea02a70209b19e40b9af00a23 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:43:28 -0400 Subject: [PATCH 29/37] use checklist --- docs/layout/dynamic-font-scaling.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index e614ff7ecfc..90e7052e75b 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -22,7 +22,10 @@ Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-dev This feature is currently opt-in on iOS. However, it will be enabled by default starting in Ionic 8 at which point the following CSS will no longer be necessary. ::: -Dynamic Font Scaling is already enabled by default on Android. Developers can enable it on iOS by setting the following CSS globally: +Dynamic Font Scaling is already enabled by default on Android. Developers can enable it on iOS using the following steps: + +1. Ensure that the [typography.css](./global-stylesheets#typographycss) file is imported. +2. Add the following CSS to a global stylesheet: ```css html { @@ -38,8 +41,6 @@ html { } ``` -Developers should ensure that the [typography.css](./global-stylesheets#typographycss) file is imported. - ## Using Dynamic Font Scaling ### Integrating Custom Components From ab09deb0038ad41f276936ce8b6eb7a5a0b19d4b Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 10:48:32 -0400 Subject: [PATCH 30/37] remove slash --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 90e7052e75b..75712580d7c 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -70,7 +70,7 @@ Developers have two options for relative font sizes: [`em` and `rem`](https://de `em` units set the font size of an element relative to the font size of its parent. -In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (`2em \* 20px = 40px`). +In the following example, the computed font size of `.child` is `40px` because it is a child of `.parent` (`2em * 20px = 40px`). ```css .parent { From 1997d2052c85bba127b793403d184221145fc53a Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 12:36:03 -0400 Subject: [PATCH 31/37] Revert "open demo in a new tab to avoid iframe issues" This reverts commit d16510a95eb09db4c2ad4e0feb2c5fa25bfaf7e3. --- docs/layout/dynamic-font-scaling.md | 8 +- .../angular/example_component_html.md | 45 +++++++++ .../angular/global_css.md | 5 + .../v7/layout/dynamic-font-scaling/index.md | 34 +++++++ .../layout/dynamic-font-scaling/javascript.md | 51 ++++++++++ .../dynamic-font-scaling/react/main_css.md | 5 + .../dynamic-font-scaling/react/main_tsx.md | 74 ++++++++++++++ .../v7/layout/dynamic-font-scaling/vue.md | 98 +++++++++++++++++++ 8 files changed, 316 insertions(+), 4 deletions(-) create mode 100644 static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/index.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/javascript.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/react/main_css.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md create mode 100644 static/usage/v7/layout/dynamic-font-scaling/vue.md diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 75712580d7c..893494f6539 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -10,11 +10,11 @@ Dynamic Font Scaling is supported on Android, iOS, and iPadOS starting in Ionic Be sure to try this on an Android, iOS, or iPadOS device. ::: -Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo linked below grow or shrink according to your preferences. +Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo below grow or shrink according to your preferences. - - Launch Dynamic Font Scaling Demo - (opens in a new tab) +import DynamicFontScaling from '@site/static/usage/v7/layout/dynamic-font-scaling/index.md'; + + ## Enabling Dynamic Font Scaling in Ionic diff --git a/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md b/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md new file mode 100644 index 00000000000..76687ae8b81 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/angular/example_component_html.md @@ -0,0 +1,45 @@ +```html + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md b/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md new file mode 100644 index 00000000000..2817f808062 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/angular/global_css.md @@ -0,0 +1,5 @@ +```css +html { + --ion-dynamic-font: var(--ion-default-dynamic-font); +} +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/index.md b/static/usage/v7/layout/dynamic-font-scaling/index.md new file mode 100644 index 00000000000..b5bd9d0cec2 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/index.md @@ -0,0 +1,34 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; + +import react_main_tsx from './react/main_tsx.md'; +import react_main_css from './react/main_css.md'; + +import vue from './vue.md'; + +import angular_example_component_html from './angular/example_component_html.md'; +import angular_global_css from './angular/global_css.md'; + + diff --git a/static/usage/v7/layout/dynamic-font-scaling/javascript.md b/static/usage/v7/layout/dynamic-font-scaling/javascript.md new file mode 100644 index 00000000000..3240686f9c5 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/javascript.md @@ -0,0 +1,51 @@ +```html + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + + + +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md new file mode 100644 index 00000000000..2817f808062 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/react/main_css.md @@ -0,0 +1,5 @@ +```css +html { + --ion-dynamic-font: var(--ion-default-dynamic-font); +} +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md b/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md new file mode 100644 index 00000000000..863d4e269d3 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/react/main_tsx.md @@ -0,0 +1,74 @@ +```tsx +import React from 'react'; +import { + IonBackButton, + IonButton, + IonButtons, + IonCheckbox, + IonContent, + IonFooter, + IonHeader, + IonIcon, + IonInput, + IonItem, + IonLabel, + IonList, + IonTitle, + IonToggle, + IonToolbar, +} from '@ionic/react'; +import { create } from 'ionicons/icons'; + +import './main.css'; + +function Example() { + return ( + <> + + + + + + Title + + + + + + + + + + + + + + Check for a free puppy + + + Enable Notifications + + + + + + Item 1 + + + Item 2 + + + Item 3 + + + + + + Footer + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/layout/dynamic-font-scaling/vue.md b/static/usage/v7/layout/dynamic-font-scaling/vue.md new file mode 100644 index 00000000000..5e0f13156c6 --- /dev/null +++ b/static/usage/v7/layout/dynamic-font-scaling/vue.md @@ -0,0 +1,98 @@ +```html + + + + + +``` From 85f54d04f17550bd917e6b63cdc6b823493f2f81 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 13:00:48 -0400 Subject: [PATCH 32/37] clarify browser behavior --- docs/layout/dynamic-font-scaling.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 893494f6539..b5c37b1d928 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -8,6 +8,8 @@ Dynamic Font Scaling is supported on Android, iOS, and iPadOS starting in Ionic :::tip Be sure to try this on an Android, iOS, or iPadOS device. + +If you are testing on Chrome for Android, make sure ["Accessibility Page Zoom"](#chrome-for-android) is enabled. ::: Follow the [Changing the Font Size on a Device](#changing-the-font-size-on-a-device) guide to set your preferred font size, and watch the text in the demo below grow or shrink according to your preferences. @@ -132,7 +134,7 @@ Ionic follows [Apple's Human Interface Guidelines for Typography](https://develo 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. 3. Text in components such as `ion-tab-bar` and `ion-picker` do not participate in Dynamic Font Scaling according to Apple's Human Interface Guidelines. -### Android +### Android Web View The Android Web View's font scaling mechanism is always enabled in web content and will automatically scale font sizes defined using the `px` unit. This means that any maximum or minimum font sizes specified using `px` will still be scaled even if the final font size does not align with the maximum or minimum font sizes specified. @@ -150,6 +152,14 @@ This is larger than our defined maximum of `14px`, so one might assume that the As a result, this means that the maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. +### Chrome for Android + +The Chrome Web Browser on Android behaves differently than the Android Web View. By default, Chrome for Android does not respect the system-level font scale setting. However, the Chromium team is working on a new feature to allow for this. When enabled, this feature will change the `zoom` level of the `html` element which will cause the layout to increase in size in addition to the text. + +Developers can test this behavior by enabling the experimental "Accessibility Page Zoom" feature in `chrome://flags`. + +See https://bugs.chromium.org/p/chromium/issues/detail?id=645717 for more information. + ### Using Modes on Different Platforms Each platform has slightly different font scaling behaviors, and the `ios` and `md` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. @@ -172,6 +182,10 @@ See [Apple Support](https://support.apple.com/en-us/102453) for more information Where users access the font scaling configuration varies across devices, but it is typically found in the "Accessibility" page in the Settings app. +:::info +The Chrome Web Browser on Android has some limitations with respecting system-level font scales. See [Chrome for Android](#chrome-for-android) for more information. +::: + ## Troubleshooting ### Dynamic Font Scaling is not working From 03febb1e212a48c915e603fb12ab721cd6df289f Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 13:03:00 -0400 Subject: [PATCH 33/37] make under the hood info a note --- docs/layout/dynamic-font-scaling.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index b5c37b1d928..5515e8d5073 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -35,6 +35,7 @@ html { } ``` +:::note Under the hood, Ionic sets the following CSS on iOS devices to enable Dynamic Font Scaling: ```css @@ -42,6 +43,7 @@ html { font: var(--ion-dynamic-font); } ``` +::: ## Using Dynamic Font Scaling From a9e12380a2df5fc6ec70a70f5d3ee0cefc99cae8 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 13:04:37 -0400 Subject: [PATCH 34/37] clarify length units --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 5515e8d5073..bfb5953b58a 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -53,7 +53,7 @@ Developers can configure their custom components to take advantage of Dynamic Fo For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. -Developers should also audit their applications and make any other changes necessary to support larger font sizes. One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. As a result, it may be necessary to change properties such as `width` and `height` to `min-width` and `min-height`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. +One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. Developers should audit their applications for any CSS properties that use [length values](https://developer.mozilla.org/en-US/docs/Web/CSS/length) and make any applicable conversions from `px` to `rem`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. Also note that any Ionic components that have had their font sizes overridden should also be updated to use `rem` units. From a5c09e6f467bec64fac73f7cebb5ccdf2b95ab78 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 13:08:34 -0400 Subject: [PATCH 35/37] lint --- docs/layout/dynamic-font-scaling.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index bfb5953b58a..2e4c6907cb2 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -43,6 +43,7 @@ html { font: var(--ion-dynamic-font); } ``` + ::: ## Using Dynamic Font Scaling From 46083a6a87f0452e8d5988c4482627e363d50680 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 13:17:00 -0400 Subject: [PATCH 36/37] update troubleshooting point to be reflect browser behavior --- docs/layout/dynamic-font-scaling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 2e4c6907cb2..98217ef6161 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -199,7 +199,7 @@ There are a number of reasons why Dynamic Font Scaling may not have any effect o 2. Dynamic Font Scaling is opt-in on iOS in Ionic 7. Verify that the proper CSS has been set. See [Enabling Dynamic Font Scaling in Ionic](#enabling-dynamic-font-scaling-in-ionic) for more information. 3. Verify that your code does not override the root element's default font size. Manually setting a font size on the root element will prevent Dynamic Font Scaling from working as intended. 4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. See [Integrating Custom Components](#integrating-custom-components) for more information. -5. Verify that Ionic is not being loaded inside of an `iframe`. Some variants of Android do not apply font scaling across `iframe` boundaries. +5. Verify "Accessibility Page Zoom" is enabled if using Chrome for Android. See [Chrome for Android](#chrome-for-android) for more information. ### Maximum and minimum font sizes are not being respected on Android From b0360dfb76ecd8bf971023f6b1d81d045fd61867 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Mon, 11 Sep 2023 14:13:11 -0400 Subject: [PATCH 37/37] clarify integration custom components section --- docs/layout/dynamic-font-scaling.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/layout/dynamic-font-scaling.md b/docs/layout/dynamic-font-scaling.md index 98217ef6161..384a71fd635 100644 --- a/docs/layout/dynamic-font-scaling.md +++ b/docs/layout/dynamic-font-scaling.md @@ -50,13 +50,9 @@ html { ### Integrating Custom Components -Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any pixel font sizes to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically `16px`. +Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any `font-size` declarations that use `px` units to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) instead. An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically `16px`. For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. Also note that any Ionic components that have had their font sizes overridden should also be updated to use `rem` units. -For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. - -One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. Developers should audit their applications for any CSS properties that use [length values](https://developer.mozilla.org/en-US/docs/Web/CSS/length) and make any applicable conversions from `px` to `rem`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. - -Also note that any Ionic components that have had their font sizes overridden should also be updated to use `rem` units. +One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. For example, `width` and `height` properties may need to change to `min-width` and `min-height`, respectively. Developers should audit their applications for any CSS properties that use [length values](https://developer.mozilla.org/en-US/docs/Web/CSS/length) and make any applicable conversions from `px` to `rem`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. ### Custom Font Family