Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 22 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,42 @@
# 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`.

<!-- rdlabo-docs-pick -->

![Ionic MD3 theme with the default Ionic palette on Android 17](screenshots/md3.png)

<!-- /rdlabo-docs-pick -->

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.
<a id="android-settings-appearance"></a>
<a id="optional%3A-use-the-md3-and-ios-27-themes-together"></a>
<a id="optional-use-the-md3-and-ios-27-themes-together"></a>

## 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

Expand All @@ -61,7 +48,7 @@ If you need a more comprehensive Material Design 3 implementation, you may also

<!-- rdlabo-docs-omit -->

**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

Expand Down Expand Up @@ -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/)

<!-- /rdlabo-docs-omit -->
2 changes: 1 addition & 1 deletion demo/src/app/docs/docs-content.generated.ts

Large diffs are not rendered by default.

36 changes: 28 additions & 8 deletions docs/android-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
22 changes: 3 additions & 19 deletions docs/color-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
<a id="tablet-alert-sizing"></a>

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).
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions docs/dynamic-colors.md
Original file line number Diff line number Diff line change
@@ -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
<a id="android-dynamic-colors"></a>

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
Expand Down
2 changes: 1 addition & 1 deletion docs/migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
4 changes: 3 additions & 1 deletion docs/special-markup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<a id="opting-out"></a>

## Disable the theme for a component

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

Expand Down
Loading