diff --git a/README.md b/README.md
index 952cb03..750e244 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
A CSS/JS theme library that applies iOS26 design system to Ionic applications.
-
+
DEMO is here: https://ionic-theme-ios26.rdlabo.dev/
@@ -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';
*/
@@ -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.
diff --git a/docs/experimental-animation.md b/docs/experimental-animation.md
index 0c0a913..5d6505b 100644
--- a/docs/experimental-animation.md
+++ b/docs/experimental-animation.md
@@ -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.
[](https://gyazo.com/fafd726b520827f042c76b6c73abd81c)
@@ -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.
[](https://gyazo.com/06bc63f4a474f9f19f5b1d865f5c2a85)
diff --git a/docs/features.md b/docs/features.md
index f31948a..45d98db 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -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 Design
-
-
-Standard Ionic Design
-```
-
-### Liquid Glass Mixin
+## Liquid Glass mixin
Import the SCSS files from the main package to use the liquid glass mixin.
@@ -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.
@@ -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).
diff --git a/docs/special-markup.md b/docs/special-markup.md
index 5af6bde..3d146c0 100644
--- a/docs/special-markup.md
+++ b/docs/special-markup.md
@@ -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
+
+ First item
+
```
@@ -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
-iOS 26 theme
-Standard Ionic button
+iOS 26 theme Standard Ionic 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).
diff --git a/docs/using-ion-item-group.md b/docs/using-ion-item-group.md
index 1f8e1c2..7699fa8 100644
--- a/docs/using-ion-item-group.md
+++ b/docs/using-ion-item-group.md
@@ -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
-
- Label
-+
- ...
- ...
-+
-
+```html
+
+ Connections
+
+ ...
+ ...
+
+
```
-## 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.
-
+
-### 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).