docs: organize public theme guides

README.md

@@ -2,7 +2,7 @@
 
 A CSS/JS theme library that applies Material Design 3 design system to Ionic applications.
 
-![Material Design 3 themed Ionic screens with updated components and navigation](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-md3/v1.1.0/screenshots/md3.png)
+![Material Design 3 themed Ionic screens with updated components and navigation](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-md3/v2.0.0-1/screenshots/md3.png)
 
 DEMO is here: https://ionic-theme-md3.rdlabo.dev/
 

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
 <ion-list inset="true">
   <ion-item-group class="item-group-header">
@@ -47,6 +49,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>
 ```
 

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
-  <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?
-
-### 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**.
-
-![Inset list background comparison](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/why-ion-list-inset.png)
+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).