diff --git a/README.md b/README.md index 227a5cd..bc4d8d9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Ionic Theme Material Design 3 -A CSS/JS theme for Ionic applications, using Android Settings as its visual reference while preserving Ionic component APIs and color semantics. +Apply Material Design 3 styling to Ionic components using the same markup as the iOS themes. + +[Set up the theme](https://webview-native-ui.com/projects/ionic-theme-md3/docs/setup) · [Try the browser demo](https://ionic-theme-md3.rdlabo.dev/) + +The setup guide shows Ionic 9. On Ionic 8 (8.8.0 or later), Angular apps import `provideIonicAngular` from `@ionic/angular/standalone`. @@ -8,48 +12,31 @@ A CSS/JS theme for Ionic applications, using Android Settings as its visual refe -DEMO is here: https://ionic-theme-md3.rdlabo.dev/ - -Designed for compatibility with `@rdlabo/ionic-theme-ios27`, so one markup tree can style both Ionic modes. - ## Installation -Use the [setup guide](docs/setup.md) to install the package, import +Use the [setup guide](https://webview-native-ui.com/projects/ionic-theme-md3/docs/setup) to install the package, import `@rdlabo/ionic-theme-md3/styles/theme.css`, and spread `md3ThemeConfig` into your existing Ionic initializer's options. Ionic `>=8.8.0 <10` is supported. Apps on older Ionic versions can use `@rdlabo/ionic-theme-md3@1.0.2`. -For existing apps, follow the [optional setup simplification](docs/migration.md#optional-simplify-the-setup). -For individual CSS files and animation settings, use [configuration](docs/configuration.md). - -### Android Settings appearance +For existing apps, follow the [optional setup simplification](https://webview-native-ui.com/projects/ionic-theme-md3/docs/migration#optional-simplify-the-setup). +For individual CSS files and animation settings, use [configuration](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration). -The theme keeps Ionic's color semantics and application font overrides. Standard -toggles are icon-free. The MD font default uses the device's local Google Sans Flex -when available, with standard fallbacks; it is included in the theme CSS. No font -initialization code or Capacitor plugin is required. Back icons remain Ionic's responsibility. - -See [Android Settings appearance](docs/android-settings.md) for installation, -font fallbacks and component overrides. Existing users should -review the [9.2.0 migration notes](docs/migration.md#migrating-to-920-android-settings-alignment) -for changes to toolbar, list and toggle dimensions. - -### Optional: use the MD3 and iOS 27 themes together - -Follow [combined theme configuration](docs/configuration.md#use-md3-and-ios-27-together) -for stylesheet ordering and platform-based animation selection. + + + ## Documentation -- [Setup](docs/setup.md) — install and configure the theme with the theme stylesheet and configuration object. -- [Configuration](docs/configuration.md) — individual stylesheets, animations and existing mode selection. -- [Android dynamic colors](docs/dynamic-colors.md) — opt-in Material You setup, light/dark appearance, lifecycle and role mapping. -- [Color system](docs/color-system.md) — Ionic palette defaults, optional Material roles and component color assignments. -- [Android Settings appearance](docs/android-settings.md) — default geometry, CSS font defaults and Ionic customization. -- [Using ion-item-group](https://docs.rdlabo.dev/projects/ionic-theme-md3/docs/using-ion-item-group) — shared inset-list markup for iOS 27 and MD3. -- [Special markup](https://docs.rdlabo.dev/projects/ionic-theme-md3/docs/special-markup) — opt-in component combinations used by the demo. -- [ESLint](https://docs.rdlabo.dev/projects/ionic-theme-md3/docs/eslint) — check list structure with ESLint rules. -- [Migration](docs/migration.md) — optional setup simplification and version-specific upgrade steps. +- [Combine MD3 and iOS 27](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration#use-md3-and-ios-27-together) — share markup across Ionic modes. +- [Configuration](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration) — individual stylesheets, animations and existing mode selection. +- [Android Dynamic Color](https://webview-native-ui.com/projects/ionic-theme-md3/docs/dynamic-colors) — opt-in Material You setup, light/dark appearance, lifecycle and role mapping. +- [Color system](https://webview-native-ui.com/projects/ionic-theme-md3/docs/color-system) — Ionic palette defaults, optional Material roles and component color assignments. +- [Android Settings appearance](https://webview-native-ui.com/projects/ionic-theme-md3/docs/android-settings) — default geometry, CSS font defaults and Ionic customization. +- [Using ion-item-group](https://webview-native-ui.com/projects/ionic-theme-md3/docs/using-ion-item-group) — shared inset-list markup for iOS 27 and MD3. +- [Special markup](https://webview-native-ui.com/projects/ionic-theme-md3/docs/special-markup) — opt-in component combinations used by the demo. +- [ESLint](https://webview-native-ui.com/projects/ionic-theme-md3/docs/eslint) — check list structure with ESLint rules. +- [Migration](https://webview-native-ui.com/projects/ionic-theme-md3/docs/migration) — optional setup simplification and version-specific upgrade steps. ## Related Projects @@ -61,7 +48,7 @@ If you need a more comprehensive Material Design 3 implementation, you may also -**Full documentation:** [https://docs.rdlabo.dev/projects/ionic-theme-md3](https://docs.rdlabo.dev/projects/ionic-theme-md3) +**Full documentation:** [https://webview-native-ui.com/projects/ionic-theme-md3](https://webview-native-ui.com/projects/ionic-theme-md3) ## Development & Testing @@ -139,4 +126,5 @@ Only `npm run release` can create a release tag. Stable `vX.Y.Z` tags (major, mi ## Maintainers - [rdlabo](https://rdlabo.dev/) + diff --git a/demo/src/app/docs/docs-content.generated.ts b/demo/src/app/docs/docs-content.generated.ts index fa53064..7fce51a 100644 --- a/demo/src/app/docs/docs-content.generated.ts +++ b/demo/src/app/docs/docs-content.generated.ts @@ -1,3 +1,3 @@ // Generated from docs/special-markup.md. Do not edit directly. export const docsContentHtml = - '

Special markup

\n

Most Ionic markup works without changes. Shared markup carries the same meaning in\n@rdlabo/ionic-theme-ios27 and this theme; its appearance follows the active platform.\nAndroid Settings is the MD3 visual reference. Shared markup does not request an iOS\nGlass appearance on Android.

\n

Submit buttons

\n

Use type="submit" for a real form submission. If submitting through a form is not\npossible, type="button" class="button-submit" identifies the equivalent action;\nthe class only describes appearance and does not submit, validate, or install a handler.\nFor a filled primary action, use Ionic's public fill="solid". MD3 already renders\nsolid buttons using the palette's base/contrast pair, so these two forms share the\nsame Android appearance without an additional effect or JavaScript helper.

\n
<ion-button type="submit" fill="solid" color="primary">Submit</ion-button>\n<ion-button type="button" class="button-submit" fill="solid" color="primary">Continue</ion-button>
\n\n
\n
Preview
\nSubmit\nContinue\n
\n\n

Explicit Ionic colors, disabled state, and fill="clear" / fill="outline" keep their\nnormal meaning. The class does not force a different fill.

\n

Toolbar button badges

\n

Place ion-badge directly inside an ion-button in an ion-toolbar. Both\nstandalone buttons and buttons inside ion-buttons support this markup.\nAn empty badge shows an unread indicator; text such as 3 or 99+ shows a count.\nFor an indicator, keep the contents completely empty (<ion-badge></ion-badge>),\nwithout spaces or line breaks between the tags.

\n

Standalone toolbar button:

\n
<ion-toolbar>\n  <ion-button slot="end" aria-label="Notifications">\n    <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n    <ion-badge>3</ion-badge>\n  </ion-button>\n</ion-toolbar>
\n\n
\n
Preview
\n\n \n \n 3\n \n\n
\n\n

Grouped toolbar buttons, with empty, numeric and wide badges:

\n
<ion-toolbar>\n  <ion-buttons slot="end">\n    <ion-button aria-label="Unread notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge></ion-badge>\n    </ion-button>\n    <ion-button aria-label="3 notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge>3</ion-badge>\n    </ion-button>\n    <ion-button aria-label="99 or more notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge>99+</ion-badge>\n    </ion-button>\n  </ion-buttons>\n</ion-toolbar>
\n\n
\n
Preview
\n\n \n \n \n \n \n \n \n 3\n \n \n \n 99+\n \n \n\n
\n\n

Use the badge's color property to choose an Ionic color. Setting hidden or\ndisplay: none, or removing the badge, hides it without changing the action's\nlayout. Include the notification state in the action's accessible label.

\n

The treatment is limited to direct-child badges in toolbar buttons. Badges in\ntabs, outside toolbars, or nested in another child keep their existing styling.\nTheme opt-outs on the toolbar, group, button or badge remain supported.

\n

Preferred overlay actions

\n

For alerts and action sheets, use role: 'preferred' for the recommended action,\nmatching the iOS 27 theme's convention. Appearance follows the overlay's purpose:\nan Alert uses a filled primary/on-primary action, while an Action Sheet keeps the\nsame full-width row geometry as its other choices and emphasizes its text/icon\nwith primary color and medium weight. The Action Sheet's Cancel group is separated\nfrom the choices by spacing and a divider. Colors derive from the Ionic palette\nunless optional Material roles are supplied. Ordinary/default actions remain text\nactions; confirm alone does not request emphasis. Cancellation, selection, and\ndestructive roles remain separate from recommendation.

\n
buttons: [\n  { text: \'Cancel\', role: \'cancel\' },\n  { text: \'Continue\', role: \'preferred\' },\n];
\n\n

This custom Ionic role does not select or invoke an action automatically. The\nbutton's handler runs normally and dismissal reports preferred; handle that\nrole explicitly if the application inspects dismissal results. cancel retains\nIonic cancellation behavior. Do not replace cancel, selected, or destructive\nwith preferred just to change their color.

\n

Two-line inset list items

\n

Place an unslotted ion-label immediately alongside an unslotted ion-note to render a two-line item. Wrap inset items in ion-item-group and keep ion-list-header outside the group. Use slot="end" on ion-note when you want the standard trailing-note layout instead.

\n
<ion-list inset="true">\n  <ion-item-group>\n    <ion-item>\n      <ion-label>Network &amp; internet</ion-label>\n      <ion-note>Mobile, Wi-Fi, hotspot</ion-note>\n    </ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n \n Network & internet\n Mobile, Wi-Fi, hotspot\n \n \n\n
\n\n

Square buttons

\n

Add .button-square when a button should use more squared corners. It works with text buttons and icon-only buttons.

\n
<ion-button class="button-square" fill="solid">Continue</ion-button>\n<ion-button class="button-square" fill="solid">\n  <ion-icon name="add" slot="icon-only"></ion-icon>\n</ion-button>
\n\n
\n
Preview
\nContinue\n\n \n\n
\n\n

Inset-list section headers

\n

Add .item-group-header to an ion-item-group to create the centered icon, title, and description used at the top of the component demo pages.

\n

This is an introductory group. Place regular list items in a separate ion-item-group that follows it.

\n
<ion-list inset="true">\n  <ion-item-group class="item-group-header">\n    <ion-item>\n      <ion-label>\n        <ion-icon name="list" style="background: var(--ion-color-primary)"></ion-icon>\n        <h2>Lists</h2>\n        <ion-text>Inset-list examples</ion-text>\n      </ion-label>\n    </ion-item>\n  </ion-item-group>\n  <ion-item-group>\n    <ion-item><ion-label>First item</ion-label></ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n \n \n \n

Lists

\n Inset-list examples\n
\n
\n
\n \n First item\n \n
\n
\n\n

Android Settings controls

\n

The standard toggle is icon-free. Ionic's enableOnOffLabels remains available\nwhen the application explicitly requests labels:

\n
<ion-list inset="true">\n  <ion-item-group>\n    <ion-item><ion-toggle justify="space-between">Notifications</ion-toggle></ion-item>\n    <ion-item>\n      <ion-toggle justify="space-between" enable-on-off-labels="true">Notifications with on/off labels</ion-toggle>\n    </ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n Notifications\n \n Notifications with on/off labels\n \n \n\n
\n\n

The theme uses a 52×28px track and 20px thumb. Grouped rows have a 56px minimum\nheight, or 72px for radio rows; long content can grow. Use Ionic's public CSS\nvariables for application sizing, and keep the shared list structure.

\n

The main theme supplies a CSS-only MD font default using local Google Sans Flex\nwhen available and standard fallbacks otherwise. An application's\n--ion-font-family takes priority. Back icons are managed by Ionic; the theme does\nnot bundle a replacement. See Android Settings appearance\nfor font defaults, fallbacks and application overrides.\nReview the migration guide\nwhen updating applications with custom dimensions. These options preserve Ionic's\npalette intent and explicit component properties.

\n

Platform-specific extensions

\n

The shared structure above works without platform-specific templates. iOS-only\nsegment-style-glass, searchbar-classic, floating iPad sheets, and iOS tab-bar\npositioning are not Android appearance requirements. MD3 retains Ionic's segment,\nsearchbar, modal, and tab-bar behavior. .button-square is an optional MD3 shape\nextension, not a required shared markup convention.

\n

Opting out

\n

Add .md3-disabled to an individual Ionic component when it must retain Ionic's standard Material styling.

\n
<ion-button fill="solid">MD3 theme</ion-button> <ion-button class="md3-disabled" fill="solid">Standard Ionic</ion-button>
\n\n
\n
Preview
\nMD3 theme Standard Ionic\n
\n'; + '

Special markup

\n

Most Ionic markup works without changes. Shared markup carries the same meaning in\n@rdlabo/ionic-theme-ios27 and this theme; its appearance follows the active platform.\nAndroid Settings is the MD3 visual reference. Shared markup does not request an iOS\nGlass appearance on Android.

\n

Submit buttons

\n

Use type="submit" for a real form submission. If submitting through a form is not\npossible, type="button" class="button-submit" identifies the equivalent action;\nthe class only describes appearance and does not submit, validate, or install a handler.\nFor a filled primary action, use Ionic's public fill="solid". MD3 already renders\nsolid buttons using the palette's base/contrast pair, so these two forms share the\nsame Android appearance without an additional effect or JavaScript helper.

\n
<ion-button type="submit" fill="solid" color="primary">Submit</ion-button>\n<ion-button type="button" class="button-submit" fill="solid" color="primary">Continue</ion-button>
\n\n
\n
Preview
\nSubmit\nContinue\n
\n\n

Explicit Ionic colors, disabled state, and fill="clear" / fill="outline" keep their\nnormal meaning. The class does not force a different fill.

\n

Toolbar button badges

\n

Place ion-badge directly inside an ion-button in an ion-toolbar. Both\nstandalone buttons and buttons inside ion-buttons support this markup.\nAn empty badge shows an unread indicator; text such as 3 or 99+ shows a count.\nFor an indicator, keep the contents completely empty (<ion-badge></ion-badge>),\nwithout spaces or line breaks between the tags.

\n

Standalone toolbar button:

\n
<ion-toolbar>\n  <ion-button slot="end" aria-label="Notifications">\n    <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n    <ion-badge>3</ion-badge>\n  </ion-button>\n</ion-toolbar>
\n\n
\n
Preview
\n\n \n \n 3\n \n\n
\n\n

Grouped toolbar buttons, with empty, numeric and wide badges:

\n
<ion-toolbar>\n  <ion-buttons slot="end">\n    <ion-button aria-label="Unread notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge></ion-badge>\n    </ion-button>\n    <ion-button aria-label="3 notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge>3</ion-badge>\n    </ion-button>\n    <ion-button aria-label="99 or more notifications">\n      <ion-icon name="ellipsis-horizontal" slot="icon-only"></ion-icon>\n      <ion-badge>99+</ion-badge>\n    </ion-button>\n  </ion-buttons>\n</ion-toolbar>
\n\n
\n
Preview
\n\n \n \n \n \n \n \n \n 3\n \n \n \n 99+\n \n \n\n
\n\n

Use the badge's color property to choose an Ionic color. Setting hidden or\ndisplay: none, or removing the badge, hides it without changing the action's\nlayout. Include the notification state in the action's accessible label.

\n

The treatment is limited to direct-child badges in toolbar buttons. Badges in\ntabs, outside toolbars, or nested in another child keep their existing styling.\nTheme opt-outs on the toolbar, group, button or badge remain supported.

\n

Preferred overlay actions

\n

For alerts and action sheets, use role: 'preferred' for the recommended action,\nmatching the iOS 27 theme's convention. Appearance follows the overlay's purpose:\nan Alert uses a filled primary/on-primary action, while an Action Sheet keeps the\nsame full-width row geometry as its other choices and emphasizes its text/icon\nwith primary color and medium weight. The Action Sheet's Cancel group is separated\nfrom the choices by spacing and a divider. Colors derive from the Ionic palette\nunless optional Material roles are supplied. Ordinary/default actions remain text\nactions; confirm alone does not request emphasis. Cancellation, selection, and\ndestructive roles remain separate from recommendation.

\n
buttons: [\n  { text: \'Cancel\', role: \'cancel\' },\n  { text: \'Continue\', role: \'preferred\' },\n];
\n\n

This custom Ionic role does not select or invoke an action automatically. The\nbutton's handler runs normally and dismissal reports preferred; handle that\nrole explicitly if the application inspects dismissal results. cancel retains\nIonic cancellation behavior. Do not replace cancel, selected, or destructive\nwith preferred just to change their color.

\n

Two-line inset list items

\n

Place an unslotted ion-label immediately alongside an unslotted ion-note to render a two-line item. Wrap inset items in ion-item-group and keep ion-list-header outside the group. Use slot="end" on ion-note when you want the standard trailing-note layout instead.

\n
<ion-list inset="true">\n  <ion-item-group>\n    <ion-item>\n      <ion-label>Network &amp; internet</ion-label>\n      <ion-note>Mobile, Wi-Fi, hotspot</ion-note>\n    </ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n \n Network & internet\n Mobile, Wi-Fi, hotspot\n \n \n\n
\n\n

Square buttons

\n

Add .button-square when a button should use more squared corners. It works with text buttons and icon-only buttons.

\n
<ion-button class="button-square" fill="solid">Continue</ion-button>\n<ion-button class="button-square" fill="solid">\n  <ion-icon name="add" slot="icon-only"></ion-icon>\n</ion-button>
\n\n
\n
Preview
\nContinue\n\n \n\n
\n\n

Inset-list section headers

\n

Add .item-group-header to an ion-item-group to create the centered icon, title, and description used at the top of the component demo pages.

\n

This is an introductory group. Place regular list items in a separate ion-item-group that follows it.

\n
<ion-list inset="true">\n  <ion-item-group class="item-group-header">\n    <ion-item>\n      <ion-label>\n        <ion-icon name="list" style="background: var(--ion-color-primary)"></ion-icon>\n        <h2>Lists</h2>\n        <ion-text>Inset-list examples</ion-text>\n      </ion-label>\n    </ion-item>\n  </ion-item-group>\n  <ion-item-group>\n    <ion-item><ion-label>First item</ion-label></ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n \n \n \n

Lists

\n Inset-list examples\n
\n
\n
\n \n First item\n \n
\n
\n\n

Android Settings controls

\n

The standard toggle is icon-free. Ionic's enableOnOffLabels remains available\nwhen the application explicitly requests labels:

\n
<ion-list inset="true">\n  <ion-item-group>\n    <ion-item><ion-toggle justify="space-between">Notifications</ion-toggle></ion-item>\n    <ion-item>\n      <ion-toggle justify="space-between" enable-on-off-labels="true">Notifications with on/off labels</ion-toggle>\n    </ion-item>\n  </ion-item-group>\n</ion-list>
\n\n
\n
Preview
\n\n \n Notifications\n \n Notifications with on/off labels\n \n \n\n
\n\n

The theme uses a 52×28px track and 20px thumb. Grouped rows have a 56px minimum\nheight, or 72px for radio rows; long content can grow. Use Ionic's public CSS\nvariables for application sizing, and keep the shared list structure.

\n

The main theme supplies a CSS-only MD font default using local Google Sans Flex\nwhen available and standard fallbacks otherwise. An application's\n--ion-font-family takes priority. Back icons are managed by Ionic; the theme does\nnot bundle a replacement. See Android Settings appearance\nfor font defaults, fallbacks and application overrides.\nReview the migration guide\nwhen updating applications with custom dimensions. These options preserve Ionic's\npalette intent and explicit component properties.

\n

Platform-specific extensions

\n

The shared structure above works without platform-specific templates. iOS-only\nsegment-style-glass, searchbar-classic, floating iPad sheets, and iOS tab-bar\npositioning are not Android appearance requirements. MD3 retains Ionic's segment,\nsearchbar, modal, and tab-bar behavior. .button-square is an optional MD3 shape\nextension, not a required shared markup convention.

\n

\n

Disable the theme for a component

\n

Add .md3-disabled to an individual Ionic component when it must retain Ionic's standard Material styling.

\n
<ion-button fill="solid">MD3 theme</ion-button> <ion-button class="md3-disabled" fill="solid">Standard Ionic</ion-button>
\n\n
\n
Preview
\nMD3 theme Standard Ionic\n
\n'; diff --git a/docs/android-settings.md b/docs/android-settings.md index 9824909..82e272d 100644 --- a/docs/android-settings.md +++ b/docs/android-settings.md @@ -11,13 +11,13 @@ on Android 17; other Android manufacturers can use different designs. ## Default theme and application overrides -| Feature | Theme default | Application customization | -| --- | --- | --- | -| Toolbar, grouped lists and controls | Android-aligned dimensions | Ionic CSS variables and application CSS | -| Toggle thumb | No state icon | Ionic `enableOnOffLabels`, or the state-icon helper below | -| Font | Device-local Google Sans Flex, then Roboto / Helvetica Neue / sans-serif | Ionic `--ion-font-family` | -| Back arrow | Ionic's configured icon | Ionic's own icon configuration; no theme icon is bundled | -| Palette | Existing Ionic color intent | Device colors are a separate [dynamic colors](dynamic-colors.md) feature | +| Feature | Theme default | Application customization | +| ----------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| Toolbar, grouped lists and controls | Android-aligned dimensions | Ionic CSS variables and application CSS | +| Toggle thumb | No state icon | Ionic `enableOnOffLabels`, or the state-icon helper below | +| Font | Device-local Google Sans Flex, then Roboto / Helvetica Neue / sans-serif | Ionic `--ion-font-family` | +| Back arrow | Ionic's configured icon | Ionic's own icon configuration; no theme icon is bundled | +| Palette | Existing Ionic color intent | Device colors are a separate [Android Dynamic Color](dynamic-colors.md) feature | ## Default font, CSS only @@ -110,9 +110,29 @@ win when `enableOnOffLabels` is enabled, including subsequent property changes. `md3-disabled` and iOS mode suppress this icon enhancement. The demo does not attach this helper automatically. +## Tablet Alert sizing + +Wide tablet Alerts follow the measured Android 17 Settings proportions: 85% in +portrait and 65% in landscape. Android tablet typing keeps that width when the +IME resizes the viewport. Phone-sized windows retain Ionic's content-sized layout. + +Use the public sizing properties to customize a dialog. For a controller-created +Alert, set `cssClass: 'app-alert'` and place a component-qualified rule in the +application's global stylesheet after the theme: + +```css +ion-alert.app-alert { + --width: 400px; + --max-width: min(400px, calc(100vw - 32px)); +} +``` + +Inline style bindings work as well. The ordinary CSS minimum/maximum constraints +still apply, and `md3-disabled` restores Ionic's own sizing defaults. + ## Upgrading and verification -Review the [migration notes](migration.md#unreleased-android-settings-alignment) +Review the [migration notes](migration.md#migrating-to-920-android-settings-alignment) for dimension changes and [grouped-list markup](using-ion-item-group.md) for sizing. Explicit Ionic `color`, disabled state, interaction and local overrides retain their meaning. The [measurement report](validation/android17-pixel-pass1-2026-11-09.md) diff --git a/docs/color-system.md b/docs/color-system.md index dea1131..97bfc90 100644 --- a/docs/color-system.md +++ b/docs/color-system.md @@ -49,7 +49,7 @@ Provide foreground/background role pairs together when changing a pair. Omitted roles still follow Ionic. No separate registration or complete scheme is needed. Material You is one optional provider of these values. See -[dynamic colors](dynamic-colors.md) for native acquisition and appearance control. +[Android Dynamic Color](dynamic-colors.md) for native acquisition and appearance control. The provider preserves Material's `on*` roles for MD3 components; Ionic named colors use supplied `onPrimary`, `onSecondary`, `onTertiary` and `onError` for their contrast values, with Ionic's contrast calculation as the per-role fallback. @@ -148,22 +148,6 @@ native reference captures, see [Android 17 tablet review](validation/android17-t For the subsequent Ionic-default color correction and its browser verification, see [Ionic color inheritance review](validation/ionic-color-inheritance-2026-11-07.md). -## Tablet Alert sizing + -Wide tablet Alerts follow the measured Android 17 Settings proportions: 85% in -portrait and 65% in landscape. Android tablet typing keeps that width when the -IME resizes the viewport. Phone-sized windows retain Ionic's content-sized layout. - -Use the public sizing properties to customize a dialog. For a controller-created -Alert, set `cssClass: 'app-alert'` and place a component-qualified rule in the -application's global stylesheet after the theme: - -```css -ion-alert.app-alert { - --width: 400px; - --max-width: min(400px, calc(100vw - 32px)); -} -``` - -Inline style bindings work as well. The ordinary CSS minimum/maximum constraints -still apply, and `md3-disabled` restores Ionic's own sizing defaults. +For dialog dimensions, see [Tablet Alert sizing](android-settings.md#tablet-alert-sizing). diff --git a/docs/configuration.md b/docs/configuration.md index 98d7e71..ce83f05 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -21,7 +21,7 @@ imports. Put application CSS overrides after the theme. Ionic owns dark-palette selection. Choose `dark.system.css`, `dark.class.css` or `dark.always.css` from `@ionic/core/css/palettes/` according to your app's appearance -policy. [Dynamic Colors](dynamic-colors.md) manages `ion-palette-dark` and uses +policy. [Android Dynamic Color](dynamic-colors.md) manages `ion-palette-dark` and uses `dark.class.css`. ## Configure animations directly diff --git a/docs/dynamic-colors.md b/docs/dynamic-colors.md index 84fe5a5..611129b 100644 --- a/docs/dynamic-colors.md +++ b/docs/dynamic-colors.md @@ -1,6 +1,8 @@ -# Android dynamic colors +# Android Dynamic Color -Dynamic colors are supported and opt-in. Android 12+ supplies light and dark Material color + + +Android Dynamic Color is opt-in. Android 12+ supplies light and dark Material color schemes; this package converts their roles using the Ionic Docs color generator algorithms. Older Android, iOS, and Web use the existing Ionic palette and component color defaults. See [color system](color-system.md): Ionic palettes alone are sufficient; native diff --git a/docs/migration.md b/docs/migration.md index 4a09846..ed2b2f5 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -65,7 +65,7 @@ the matching theme configuration. Put application settings after the spread so custom animations take precedence, including an explicit `navAnimation: undefined` for Ionic's default transition. See [setup](setup.md) for framework imports and [configuration](configuration.md) for individual APIs -and combined-theme selection. Dynamic Colors continues to use Ionic's +and combined-theme selection. Android Dynamic Color continues to use Ionic's [class-based palette](dynamic-colors.md). ## Migrating to 9.2.0: Android Settings alignment diff --git a/docs/setup.md b/docs/setup.md index d0009e6..6f97fda 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -4,7 +4,7 @@ title: Set up the MD3 theme # Set up the MD3 theme -Use an existing Ionic Angular, React or Vue app with Ionic `>=8.8.0 <10`. +Apply the Material Design 3 theme to an Ionic Angular, React or Vue app. This setup supports Ionic `>=8.8.0 <10`. ## Install the theme @@ -26,7 +26,7 @@ it in an existing app, replace the individual MD3 stylesheet imports. Keep your chosen Ionic dark-palette import, such as `@ionic/core/css/palettes/dark.system.css`, and put application overrides after the theme stylesheet. MD3 has one theme stylesheet for all appearance modes. For -[Dynamic Colors](dynamic-colors.md), select Ionic's `dark.class.css` palette. +[Android Dynamic Color](dynamic-colors.md), select Ionic's `dark.class.css` palette. ## Configure Ionic diff --git a/docs/special-markup.md b/docs/special-markup.md index aed8deb..c53ee42 100644 --- a/docs/special-markup.md +++ b/docs/special-markup.md @@ -185,7 +185,9 @@ positioning are not Android appearance requirements. MD3 retains Ionic's segment searchbar, modal, and tab-bar behavior. `.button-square` is an optional MD3 shape extension, not a required shared markup convention. -## Opting out + + +## Disable the theme for a component Add `.md3-disabled` to an individual Ionic component when it must retain Ionic's standard Material styling.