From 15e0cd43d7d116b2dee4a3bb58f42cd88f1a4e6f Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 20:42:03 +0900 Subject: [PATCH 1/6] docs: Make the MD3 theme setup and demo easier to find --- README.md | 8 +++----- docs/setup.md | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 227a5cd..eb46834 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # 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](docs/setup.md) · [Try the browser demo](https://ionic-theme-md3.rdlabo.dev/) @@ -8,10 +10,6 @@ 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 diff --git a/docs/setup.md b/docs/setup.md index d0009e6..87c65de 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 From 2d900aaba335e5ed012ded05e476002cff257596 Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 20:43:02 +0900 Subject: [PATCH 2/6] docs: use consistent names for shared features --- README.md | 2 +- docs/android-settings.md | 2 +- docs/color-system.md | 2 +- docs/configuration.md | 2 +- docs/dynamic-colors.md | 6 ++++-- docs/migration.md | 2 +- docs/setup.md | 2 +- docs/special-markup.md | 4 +++- 8 files changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index eb46834..6a8eb06 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ for stylesheet ordering and platform-based animation selection. - [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. +- [Android Dynamic Color](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. diff --git a/docs/android-settings.md b/docs/android-settings.md index 9824909..b43d850 100644 --- a/docs/android-settings.md +++ b/docs/android-settings.md @@ -17,7 +17,7 @@ on Android 17; other Android manufacturers can use different designs. | 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 | +| Palette | Existing Ionic color intent | Device colors are a separate [Android Dynamic Color](dynamic-colors.md) feature | ## Default font, CSS only diff --git a/docs/color-system.md b/docs/color-system.md index dea1131..05af81c 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. 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..e43d45a 100644 --- a/docs/dynamic-colors.md +++ b/docs/dynamic-colors.md @@ -1,6 +1,8 @@ -# Android dynamic colors + -Dynamic colors are supported and opt-in. Android 12+ supplies light and dark Material color +# Android Dynamic 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 87c65de..6f97fda 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -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. From 0f95b04c789d258c3ed823f61a849435ce65525e Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 20:51:50 +0900 Subject: [PATCH 3/6] docs: link README guides to the documentation website --- README.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 6a8eb06..2e03158 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Apply Material Design 3 styling to Ionic components using the same markup as the iOS themes. -[Set up the theme](docs/setup.md) · [Try the browser demo](https://ionic-theme-md3.rdlabo.dev/) +[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/) @@ -12,13 +12,13 @@ Apply Material Design 3 styling to Ionic components using the same markup as the ## 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). +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). ### Android Settings appearance @@ -27,27 +27,27 @@ toggles are icon-free. The MD font default uses the device's local Google Sans F 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, +See [Android Settings appearance](https://webview-native-ui.com/projects/ionic-theme-md3/docs/android-settings) 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) +review the [9.2.0 migration notes](https://webview-native-ui.com/projects/ionic-theme-md3/docs/migration#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) +Follow [combined theme configuration](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration#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 Color](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. +- [Setup](https://webview-native-ui.com/projects/ionic-theme-md3/docs/setup) — install and configure the theme with the theme stylesheet and configuration object. +- [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 @@ -59,7 +59,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 From 308643410dbc073466f403950ca0c6110458498c Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 20:56:37 +0900 Subject: [PATCH 4/6] docs: apply package guide review feedback --- README.md | 3 +++ demo/src/app/docs/docs-content.generated.ts | 2 +- docs/dynamic-colors.md | 4 ++-- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2e03158..d7abc2d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Apply Material Design 3 styling to Ionic components using the same markup as the [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`. + ![Ionic MD3 theme with the default Ionic palette on Android 17](screenshots/md3.png) @@ -137,4 +139,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/dynamic-colors.md b/docs/dynamic-colors.md index e43d45a..611129b 100644 --- a/docs/dynamic-colors.md +++ b/docs/dynamic-colors.md @@ -1,7 +1,7 @@ - - # Android Dynamic 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. From f97aff8d8aa26e2b1229f839377d1b3b5a3b022c Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 21:04:17 +0900 Subject: [PATCH 5/6] docs: separate getting started from detailed guidance --- README.md | 20 +++----------------- docs/android-settings.md | 36 ++++++++++++++++++++++++++++-------- docs/color-system.md | 20 ++------------------ 3 files changed, 33 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index d7abc2d..a8ac2a4 100644 --- a/README.md +++ b/README.md @@ -22,26 +22,12 @@ versions can use `@rdlabo/ionic-theme-md3@1.0.2`. 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). -### Android Settings appearance - -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](https://webview-native-ui.com/projects/ionic-theme-md3/docs/android-settings) for installation, -font fallbacks and component overrides. Existing users should -review the [9.2.0 migration notes](https://webview-native-ui.com/projects/ionic-theme-md3/docs/migration#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](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration#use-md3-and-ios-27-together) -for stylesheet ordering and platform-based animation selection. + + ## Documentation -- [Setup](https://webview-native-ui.com/projects/ionic-theme-md3/docs/setup) — install and configure the theme with the theme stylesheet and configuration object. +- [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. diff --git a/docs/android-settings.md b/docs/android-settings.md index b43d850..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 [Android Dynamic Color](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 05af81c..97bfc90 100644 --- a/docs/color-system.md +++ b/docs/color-system.md @@ -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). From bba775cd2e2245c8034c7e978259e0ac1d85824f Mon Sep 17 00:00:00 2001 From: rdlabo Date: Wed, 18 Nov 2026 21:09:38 +0900 Subject: [PATCH 6/6] docs: address final package guide review --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a8ac2a4..bc4d8d9 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ For existing apps, follow the [optional setup simplification](https://webview-na For individual CSS files and animation settings, use [configuration](https://webview-native-ui.com/projects/ionic-theme-md3/docs/configuration). + ## Documentation