rdlabo-dev · rdlabo · Aug 21, 2026 · Aug 21, 2026
diff --git a/BREAKING.md b/BREAKING.md
diff --git a/README.md b/README.md
@@ -24,7 +24,6 @@ If you need a more comprehensive Material Design 3 implementation, you may also
 
 > **Note:** This theme is purpose-built for compatibility with Ionic's design approach and `@rdlabo/ionic-theme-ios26`; it is not intended as a strict, full MD3 recreation.
 
-
 ## Quick start
 
 After [Installation](#installation), import the theme CSS and set `navAnimation` as shown below.
@@ -72,12 +71,21 @@ createApp(App)
 })
 ```
 
-
 ## Documentation
 
 Start with [Installation](#installation). Pair this theme with [@rdlabo/ionic-theme-ios26](https://docs.rdlabo.dev/projects/ionic-theme-ios26) when you need both platforms from one markup tree.
 
+- [Special markup](./docs/special-markup.md) — opt-in component combinations used by the demo.
+- [Using ion-item-group](./docs/using-ion-item-group.md) — shared inset-list markup for iOS 26 and MD3.
+
+<!-- rdlabo-docs-omit -->
+
+- [Breaking changes](./docs/breaking.md) — changes required when upgrading major versions.
+
+<!-- /rdlabo-docs-omit -->
+
 <!-- rdlabo-docs-omit -->
+
 **Full documentation:** [https://docs.rdlabo.dev/projects/ionic-theme-md3](https://docs.rdlabo.dev/projects/ionic-theme-md3)
 
 ## Development & Testing
@@ -118,4 +126,5 @@ npm run test:e2e:debug
 # Update baseline screenshots (when intentionally changing UI)
 npm run test:e2e:update
 ```
+
 <!-- /rdlabo-docs-omit -->
diff --git a/demo/E2E_TESTING.md b/demo/E2E_TESTING.md
diff --git a/docs/breaking.md b/docs/breaking.md
@@ -0,0 +1,3 @@
+# Breaking changes
+
+This document lists the breaking changes introduced in major releases of `@rdlabo/ionic-theme-md3` and the steps required to migrate. There are no documented breaking changes yet.
diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md
@@ -0,0 +1,51 @@
+# E2E screenshot testing
+
+This maintainer guide explains how to run the Playwright visual-regression suite for the Material Design 3 demo. The suite covers every entry declared in `demo/e2e/screenshot.spec.ts` in both light and dark modes. Overlay variants are generated from the shared arrays in `demo/src/app/overlay-types.ts`.
+
+## Run the suite
+
+Install the demo dependencies first:
+
+```bash
+cd demo
+npm install
+```
+
+Then choose the command that matches the task:
+
+```bash
+npm run test:e2e          # Run the suite
+npm run test:e2e:ui       # Open Playwright UI mode
+npm run test:e2e:debug    # Run with the Playwright debugger
+npm run test:e2e:update   # Regenerate intentional baseline changes
+```
+
+To reproduce the Linux environment used by CI, run the Docker variants from `demo/`:
+
+```bash
+npm run test:e2e:docker
+npm run test:e2e:docker:update
+```
+
+The Docker commands use the Playwright image pinned in `demo/package.json`.
+
+## Review a failure
+
+A screenshot mismatch can be a regression or an intentional visual change. Before updating a baseline:
+
+1. Inspect the actual, expected, and diff images in `demo/test-results/`.
+2. Check the affected route in both light and dark modes.
+3. Confirm that the component change is intentional.
+4. Regenerate the baseline with `npm run test:e2e:update`, or use the Docker variant when matching CI rendering.
+
+The HTML report is written to `demo/playwright-report/` and can be opened with:
+
+```bash
+npx playwright show-report
+```
+
+## Add coverage
+
+When adding a demo route or overlay variant, update `demo/e2e/screenshot.spec.ts` and regenerate the relevant baselines. Commit baseline changes only after reviewing the visual diff.
+
+Pull requests run the E2E workflow in `.github/workflows/e2e-pull_request.yml`; pushes to `main` run `.github/workflows/e2e-main.yml`.
diff --git a/docs/special-markup.md b/docs/special-markup.md
@@ -0,0 +1,36 @@
+---
+title: Special markup
+---
+
+# Special markup
+
+Most Ionic markup works without changes. The combination below is an explicit opt-in demonstrated in `demo/src/app/docs` and is useful when the same template also uses `@rdlabo/ionic-theme-ios26`.
+
+## Two-line inset list items
+
+Place an unslotted `ion-label` immediately alongside an unslotted `ion-note` to render a two-line item. Use `slot="end"` on `ion-note` when you want the standard trailing-note layout instead.
+
+```html
+<ion-list inset="true">
+  <ion-item>
+    <ion-label>Network &amp; internet</ion-label>
+    <ion-note>Mobile, Wi-Fi, hotspot</ion-note>
+  </ion-item>
+</ion-list>
+```
+
+If the application imports `@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css`, wrap list items in `ion-item-group` and keep `ion-list-header` outside the group:
+
+```html
+<ion-list inset="true">
+  <ion-list-header><ion-label>Connections</ion-label></ion-list-header>
+  <ion-item-group>
+    <ion-item>
+      <ion-label>Network &amp; internet</ion-label>
+      <ion-note>Mobile, Wi-Fi, hotspot</ion-note>
+    </ion-item>
+  </ion-item-group>
+</ion-list>
+```
+
+See [Using `ion-item-group`](./using-ion-item-group.md) for the required import and background model.
diff --git a/USING_ION_ITEM_GROUP.md → docs/using-ion-item-group.md b/USING_ION_ITEM_GROUP.md → docs/using-ion-item-group.md
@@ -1,14 +1,19 @@
-# Using `ion-item-group` with iOS26 Theme
+---
+title: Using ion-item-group
+---
 
-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`.
+# Using `ion-item-group` with the MD3 theme
+
+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.
 
 ## When is `ion-item-group` required?
 
-It is only required when **both** of the following conditions are met:
+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
 
-Only when these conditions apply, you need to wrap your list items with `ion-item-group`.
+When these conditions apply, wrap the list items—but not the list header—with `ion-item-group`.
 
 ## Implementation Example
 
@@ -28,7 +33,7 @@ Only when these conditions apply, you need to wrap your list items with `ion-ite
 
 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**.
 
-![](screenshots/why-ion-list-inset.png)
+![Inset list background comparison](https://raw.githubusercontent.com/rdlabo-dev/ionic-theme-ios26/v2.3.2/screenshots/why-ion-list-inset.png)
 
 ### Solution: Background Color Separation
 
@@ -52,5 +57,5 @@ This will apply the same `ion-item-group` pattern to the Material Design theme a
 ## 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`
+- **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
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Breaking changes

		This document lists the breaking changes introduced in major releases of `@rdlabo/ionic-theme-md3` and the steps required to migrate. There are no documented breaking changes yet.