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 = - '
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.
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.
<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>Explicit Ionic colors, disabled state, and fill="clear" / fill="outline" keep their\nnormal meaning. The class does not force a different fill.
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.
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>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>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.
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.
\nFor 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.
buttons: [\n { text: \'Cancel\', role: \'cancel\' },\n { text: \'Continue\', role: \'preferred\' },\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.
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.
<ion-list inset="true">\n <ion-item-group>\n <ion-item>\n <ion-label>Network & internet</ion-label>\n <ion-note>Mobile, Wi-Fi, hotspot</ion-note>\n </ion-item>\n </ion-item-group>\n</ion-list>Add .button-square when a button should use more squared corners. It works with text buttons and icon-only buttons.
<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>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.
This is an introductory group. Place regular list items in a separate ion-item-group that follows it.
<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>The standard toggle is icon-free. Ionic's enableOnOffLabels remains available\nwhen the application explicitly requests labels:
<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>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.
\nThe 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.
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.
Add .md3-disabled to an individual Ionic component when it must retain Ionic's standard Material styling.
<ion-button fill="solid">MD3 theme</ion-button> <ion-button class="md3-disabled" fill="solid">Standard Ionic</ion-button>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.
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.
<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>Explicit Ionic colors, disabled state, and fill="clear" / fill="outline" keep their\nnormal meaning. The class does not force a different fill.
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.
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>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>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.
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.
\nFor 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.
buttons: [\n { text: \'Cancel\', role: \'cancel\' },\n { text: \'Continue\', role: \'preferred\' },\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.
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.
<ion-list inset="true">\n <ion-item-group>\n <ion-item>\n <ion-label>Network & internet</ion-label>\n <ion-note>Mobile, Wi-Fi, hotspot</ion-note>\n </ion-item>\n </ion-item-group>\n</ion-list>Add .button-square when a button should use more squared corners. It works with text buttons and icon-only buttons.
<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>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.
This is an introductory group. Place regular list items in a separate ion-item-group that follows it.
<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>The standard toggle is icon-free. Ionic's enableOnOffLabels remains available\nwhen the application explicitly requests labels:
<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>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.
\nThe 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.
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.
Add .md3-disabled to an individual Ionic component when it must retain Ionic's standard Material styling.
<ion-button fill="solid">MD3 theme</ion-button> <ion-button class="md3-disabled" fill="solid">Standard Ionic</ion-button>