diff --git a/README.md b/README.md
index a5c9bd2..6a2db07 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
A CSS/JS theme library that applies Material Design 3 design system to Ionic applications.
-
+
DEMO is here: https://ionic-theme-md3.rdlabo.dev/
diff --git a/docs/special-markup.md b/docs/special-markup.md
index 715bd91..1318461 100644
--- a/docs/special-markup.md
+++ b/docs/special-markup.md
@@ -36,6 +36,8 @@ Add `.button-square` when a button should use more squared corners. It works wit
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
+
```
diff --git a/docs/using-ion-item-group.md b/docs/using-ion-item-group.md
index c03e917..12c6552 100644
--- a/docs/using-ion-item-group.md
+++ b/docs/using-ion-item-group.md
@@ -2,60 +2,32 @@
title: Using ion-item-group
---
-# Using `ion-item-group` with the MD3 theme
+# Using `ion-item-group` in inset lists
-The MD3 theme supports the same inset-list markup as `@rdlabo/ionic-theme-ios26`, so an application can share one template across Ionic modes. Add `ion-item-group` when you opt in to that shared pattern.
+The MD3 theme uses the same inset-list structure as `@rdlabo/ionic-theme-ios26`, allowing one template to work across Ionic modes. 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 both of the following conditions are met:
-
-- You have enabled the `inset` property on `ion-list`
-- You import the iOS 26 package's optional `md-ion-list-inset.css` stylesheet
-
-When these conditions apply, wrap the list items—but not the list header—with `ion-item-group`.
-
-## Implementation Example
-
-```diff
-
- Label
-+
- ...
- ...
-+
-
+```html
+
+ Connections
+
+ ...
+ ...
+
+
```
-## Why is this change necessary?
-
-### Background: Challenges in iOS Design Reproduction
-
-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**.
-
-
+No wrapper is required for lists that do not use `inset="true"`.
-### Solution: Background Color Separation
+## Why the wrapper is required
-To faithfully reproduce iOS design, this theme makes the following changes:
-
-- Set `ion-list` background color to transparent
-- Delegate background color to `ion-item-group`
-
-This change allows `ion-list-header` to be treated as an independent element, achieving the native iOS appearance.
-
-## Using the Same Design with Material Design
-
-If you want to use the same design pattern with Material Design theme, import the following CSS:
-
-```css
-@import '@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css';
-```
+The shared structure keeps `ion-list-header` separate from the item surface. This matches the iOS 26 layout while allowing MD3 to style the same markup without platform-specific templates.
-This will apply the same `ion-item-group` pattern to the Material Design theme as well.
+The theme therefore:
-## Summary
+- makes the inset `ion-list` background transparent;
+- applies the item surface to `ion-item-group`; and
+- leaves `ion-list-header` outside that surface.
-- **Most cases**: You can use your existing Ionic code as-is
-- **Specific conditions only**: `ion-item-group` is required when using the optional shared inset-list stylesheet
-- **Purpose**: To accurately reproduce iOS 26's native design patterns
+For two-line items and section-header groups, see [Special markup](./special-markup.md).