docs: organize iOS26 theme guides

README.md

@@ -14,7 +14,6 @@ I'm also working on the Android Design (Material Design 3) theme. Be sure to cat
 
 👉️[rdlabo-dev/ionic-theme-md3](https://github.com/rdlabo-dev/ionic-theme-md3)
 
-
 ## Quick start
 
 After [Installation](#installation), import the theme CSS. Details are in Installation below.
@@ -91,18 +90,25 @@ createApp(App)
 })
 ```
 
-
 ## Documentation
 
 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.
 - [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) — selective component imports and dark mode.
 
 <!-- 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-ios26](https://docs.rdlabo.dev/projects/ionic-theme-ios26)
 
 ## Development & Testing
@@ -143,4 +149,5 @@ npm run test:e2e:debug
 # Update baseline screenshots (when intentionally changing UI)
 npm run test:e2e:update
 ```
+
 <!-- /rdlabo-docs-omit -->

demo/src/app/docs/docs-page.component.html

@@ -86,7 +86,7 @@ <h3><code>ion-searchbar.searchbar-classic</code></h3>
           <p>iOS26's searchbar classic style.</p>
           <code class="code-block ion-margin-bottom">&lt;ion-searchbar class="searchbar-classic"&gt;&lt;/ion-searchbar&gt;</code>
           <ion-toolbar>
-            <ion-searchbar class="sarchbar-classic"></ion-searchbar>
+            <ion-searchbar class="searchbar-classic"></ion-searchbar>
           </ion-toolbar>
         </div>
       </ion-item>

BREAKING.md → docs/breaking.md

@@ -1,5 +1,6 @@
-# Breaking Changes
-This is a comprehensive list of the breaking changes introduced in the major version releases of `@rdlabo/ionic-theme-ios26`
+# Breaking changes
+
+This document lists the breaking changes introduced in major releases of `@rdlabo/ionic-theme-ios26` and the steps required to migrate.
 
 ## Version 2.0.0
 
@@ -16,25 +17,24 @@ import { iosTransitionAnimation } from '@rdlabo/ionic-theme-ios26';
 
 // Angular
 provideIonicAngular({
-    ...
-    navAnimation: isPlatform('ios') ? iosTransitionAnimation: undefined,
+  // ...
+  navAnimation: isPlatform('ios') ? iosTransitionAnimation : undefined,
 });
 
 // React
 setupIonicReact({
-    ...
-    navAnimation: isPlatform('ios') ? iosTransitionAnimation: undefined,
+  // ...
+  navAnimation: isPlatform('ios') ? iosTransitionAnimation : undefined,
 });
 
 // Vue
-createApp(App)
-    .use(IonicVue, {
-        ...
-        navAnimation: isPlatform('ios') ? iosTransitionAnimation: undefined,
-})
+createApp(App).use(IonicVue, {
+  // ...
+  navAnimation: isPlatform('ios') ? iosTransitionAnimation : undefined,
+});
 ```
 
-With this update, the previously discouraged pattern `<ion-buttons><ion-back-button></ion-back-button></ion-buttons>`can now be used again without causing transition issues.
+With this update, the previously discouraged pattern `<ion-buttons><ion-back-button></ion-back-button></ion-buttons>` can be used again without causing transition issues.
 
 ### Why does `iosTransitionAnimation` need to be replaced?
 
@@ -47,10 +47,9 @@ Because the behavior no longer exists on modern iOS, Ionic’s built-in transiti
 To align with the new iOS 26 design, our `iosTransitionAnimation` removes the now-obsolete `animateBackButton()` step.  
 As a result, transitions are smoother and header structures such as custom `<ion-buttons>` with `<ion-back-button>` work reliably again.
 
-
 ## Version 1.0.0
 
-### change the import path of the SCSS files
+### Change the SCSS import path
 
 Reorganized the folder structure after adding JavaScript files.
 
@@ -61,7 +60,8 @@ Reorganized the folder structure after adding JavaScript files.
 
 Note: The output path for the generated dist files remains unchanged.
 
-### `--ios26-color-background-rgb` is renamed.
+### Rename `--ios26-color-background-rgb`
+
 Changed the variable names for clarity.
 
 ```diff
@@ -71,8 +71,10 @@ Changed the variable names for clarity.
   }
 ```
 
-### `--ion-color-**-brightness-rgb` is changed to `--ion-color-**-brightness`
+### Rename `--ion-color-**-brightness-rgb` to `--ion-color-**-brightness`
+
 Refactoring the styling removed the need to manipulate transparency.
+
 ```diff
   :root {
 -   --ion-color-**-brightness-rgb: 130, 255, 255;

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 iOS26 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`.