Skip to content

docs: organize public theme guides #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rdlabo merged 1 commit into from
Aug 22, 2026
Merged

docs: organize public theme guides #119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A CSS/JS theme library that applies iOS26 design system to Ionic applications.

![iOS 26 themed Ionic screens with Liquid Glass tab bar, lists, and controls](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/ios26.png)
![iOS 26 themed Ionic screens with Liquid Glass tab bar, lists, and controls](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v3.0.0-1/screenshots/ios26.png)

DEMO is here: https://ionic-theme-ios26.rdlabo.dev/

Expand Down Expand Up @@ -38,14 +38,14 @@ And import the theme in your project's main CSS file (e.g., `src/styles.scss`).
* This file is to eliminate the impact of class name changes for iOS26.
* For example, `ion-buttons ion-button[fill=default]` is not normally implemented, but may be required for iOS26.
* This file is to eliminate such effects.
* Note: This is not include `@rdlabo/ionic-theme-md3`
* Note: This stylesheet is not included in `@rdlabo/ionic-theme-md3`.
*/
@import '@rdlabo/ionic-theme-ios26/dist/css/md-remove-ios-class-effect.css';

/**
* If you will use the design of ion-item-group with ion-list on Android as well, import it.
* More info: ./docs/using-ion-item-group.md
* Note: This is include `@rdlabo/ionic-theme-md3`
* Note: This stylesheet is included in `@rdlabo/ionic-theme-md3`.
* @import '@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css';
*/

Expand Down Expand Up @@ -95,8 +95,8 @@ createApp(App)
Start with [Installation](#installation), then [Using ion-item-group](./docs/using-ion-item-group.md) when you use inset lists.

- [Using ion-item-group](./docs/using-ion-item-group.md) — required markup for inset lists.
- [Special markup and classes](./docs/special-markup.md) — opt-in markup, CSS variables, and utility classes used by the demo.
- [Features](./docs/features.md) — CSS variables, `.ios26-disabled`, Liquid Glass, selective imports, and dark mode.
- [Special markup and classes](./docs/special-markup.md) — opt-in markup and utility classes used by the theme.
- [Features](./docs/features.md) — CSS variables, Liquid Glass, selective imports, and dark mode.
- [Experimental Animation](./docs/experimental-animation.md) — tab bar and searchable effects.
- [iOS 18](./docs/ios-18.md) — load the theme only on iOS 26.
- [Migration](./docs/migration.md) — required changes when upgrading major versions.
Expand Down
12 changes: 5 additions & 7 deletions docs/experimental-animation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@ title: Experimental animation

# Experimental animation

Optional gesture and animation helpers. The theme works without this feature.
These gesture and animation helpers are experimental and optional. The theme works without them.

**This feature is experimental. The library can be used without this feature.**
## Sheet of Glass with `ion-tab-button` / `ion-segment-button`

### Sheet of Glass with `ion-tab-button` / `ion-segment-button`

By registering `ion-tab-bar` / `ion-segment`, you can display animation effects on `ion-tab-button` / `ion-segment-button`
Register an `ion-tab-bar` or `ion-segment` element to add a moving selection effect to its buttons.

[![Sheet of Glass animation on ion-tab-button and ion-segment-button](https://i.gyazo.com/fafd726b520827f042c76b6c73abd81c.gif)](https://gyazo.com/fafd726b520827f042c76b6c73abd81c)

Expand All @@ -36,9 +34,9 @@ const destroy = () => {
};
```

### TabBarSearchable: Searchable with `ion-tab-bar` and `ion-fab-button`
## TabBarSearchable: Searchable with `ion-tab-bar` and `ion-fab-button`

Enable Searchable for the DOM structure with the specified markup inner `ion-tabs`.
Use the following structure inside `ion-tabs` to animate a search button into a search toolbar.

[![TabBarSearchable animation expanding search from ion-fab-button into the tab bar](https://i.gyazo.com/06bc63f4a474f9f19f5b1d865f5c2a85.gif)](https://gyazo.com/06bc63f4a474f9f19f5b1d865f5c2a85)

Expand Down
30 changes: 8 additions & 22 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,14 @@ title: Features

# Features

CSS variables, opt-out class, and the Liquid Glass mixin. See [Using ion-item-group](./using-ion-item-group.md) for list markup.
Customize the theme with CSS variables and Sass mixins, or adopt it one component at a time. Markup-specific opt-ins are documented in [Special markup and classes](./special-markup.md).

### CSS Variables
## CSS variables

To customize the library's default styles to match your design, several CSS variables are provided. See this file for details:
https://github.com/rdlabo-dev/ionic-theme-ios26/blob/v3.0.0/src/styles/default-variables.scss
https://github.com/rdlabo-dev/ionic-theme-ios26/blob/v3.0.0-1/src/styles/default-variables.scss

### `.ios26-disabled` Class

Add the `.ios26-disabled` class to disable the iOS26 theme on specific components.

```html
<!-- iOS26 theme applied -->
<ion-button>iOS26 Design</ion-button>

<!-- Standard Ionic iOS styling -->
<ion-button class="ios26-disabled">Standard Ionic Design</ion-button>
```

### Liquid Glass Mixin
## Liquid Glass mixin

Import the SCSS files from the main package to use the liquid glass mixin.

Expand All @@ -35,12 +23,6 @@ ion-textarea label.textarea-wrapper {
}
```

### Additional Design

To achieve higher fidelity to iOS26 design, you can implement additional design provided by this library. For more details, please visit:

https://ionic-theme-ios26.rdlabo.dev/main/docs

## Selective component imports

For gradual adoption, you can import individual components instead of the full theme file.
Expand Down Expand Up @@ -100,3 +82,7 @@ Class:
@include theme-dark.ion-segment;
}
```

## Interactive examples

[Browse rendered examples in the demo](https://ionic-theme-ios26.rdlabo.dev/main/docs).
10 changes: 7 additions & 3 deletions docs/special-markup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ Use `slot="end"` on `ion-note` when you want the standard trailing-note layout i

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.

```html preview
<ion-list inset="true">
<ion-item-group class="item-group-header">
Expand All @@ -58,6 +60,9 @@ Add `.item-group-header` to an `ion-item-group` to create the centered icon, tit
</ion-label>
</ion-item>
</ion-item-group>
<ion-item-group>
<ion-item><ion-label>First item</ion-label></ion-item>
</ion-item-group>
</ion-list>
```

Expand Down Expand Up @@ -134,8 +139,7 @@ Add `.toolbar-searchbar` when an `ion-toolbar` combines a search bar with start
Add `.ios26-disabled` to an individual Ionic component when it must retain Ionic's standard iOS styling.

```html preview
<ion-button>iOS 26 theme</ion-button>
<ion-button class="ios26-disabled">Standard Ionic button</ion-button>
<ion-button>iOS 26 theme</ion-button> <ion-button class="ios26-disabled">Standard Ionic button</ion-button>
```

For the background model behind inset lists, see [Using `ion-item-group`](https://github.com/rdlabo-dev/ionic-theme-ios26/blob/main/docs/using-ion-item-group.md).
For the background model behind inset lists, see [Using `ion-item-group`](./using-ion-item-group.md).
61 changes: 23 additions & 38 deletions docs/using-ion-item-group.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,59 +2,44 @@
title: Using ion-item-group
---

# Using `ion-item-group` with the iOS26 theme
# Using `ion-item-group` in inset lists

This theme aims to bring Ionic Framework applications as close as possible to iOS 26 design. In most cases, you can use your existing Ionic code as-is, but **only under specific conditions**, you need to add `ion-item-group`.
Most Ionic markup works without changes. When an `ion-list` uses `inset="true"`, wrap its items in `ion-item-group` and keep `ion-list-header` outside the group.

## When is `ion-item-group` required?
The examples use framework-neutral Web Component markup. In React or Vue, use the equivalent component and property syntax.

It is only required when the following condition is met:

- You have enabled the `inset` property on `ion-list`

Only when this condition applies, you need to wrap your list items with `ion-item-group`.

## Implementation Example

```diff
<ion-list inset=true>
<ion-list-header><ion-label>Label</ion-label></ion-list-header>
+ <ion-item-group>
<ion-item>...</ion-item>
<ion-item>...</ion-item>
+ </ion-item-group>
</ion-list>
```html
<ion-list inset="true">
<ion-list-header><ion-label>Connections</ion-label></ion-list-header>
<ion-item-group>
<ion-item>...</ion-item>
<ion-item>...</ion-item>
</ion-item-group>
</ion-list>
```

## Why is this change necessary?
No wrapper is required for lists that do not use `inset="true"`.

### Background: Challenges in iOS Design Reproduction
## Why the wrapper is required

By default in Ionic Framework, `ion-list` has a background color, and `ion-list-header` is treated as part of the list. However, with this structure, it's impossible to accurately reproduce **iOS's native design patterns**.
Ionic normally gives `ion-list` its background, which makes `ion-list-header` appear inside the same surface as the items. The iOS 26 layout treats the header and item surface separately.

![ion-list inset background comparison showing why ion-item-group is required](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/why-ion-list-inset.png)
![Inset list background comparison showing why ion-item-group is required](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v3.0.0-1/screenshots/why-ion-list-inset.png)

### Solution: Background Color Separation
The theme therefore:

To faithfully reproduce iOS design, this theme makes the following changes:
- makes the inset `ion-list` background transparent;
- applies the item surface to `ion-item-group`; and
- leaves `ion-list-header` outside that surface.

- Set `ion-list` background color to transparent
- Delegate background color to `ion-item-group`
## Sharing the markup with Material Design

This change allows `ion-list-header` to be treated as an independent element, achieving the native iOS appearance.
`@rdlabo/ionic-theme-md3` supports the same grouped markup, so one template can be used for both Ionic modes.

## Using the Same Design with Material Design

If you want to use the same design pattern with Material Design theme, import the following CSS:
When an application uses this package without `@rdlabo/ionic-theme-md3`, import the optional stylesheet to apply the same grouped layout in Material mode:

```css
@import '@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css';
```

This will apply the same `ion-item-group` pattern to the Material Design theme as well.

## Summary

- **Most cases**: You can use your existing Ionic code as-is
- **Specific conditions only**: `ion-item-group` is only required when setting using `inset` on `ion-list`
- **Purpose**: To accurately reproduce iOS 26's native design patterns
For two-line items and section-header groups, see [Special markup and classes](./special-markup.md).
Loading