From 5ea098ae0a9cc7bfb9313fcbdc87ce9650ed49b8 Mon Sep 17 00:00:00 2001 From: rdlabo Date: Sat, 22 Aug 2026 03:02:23 +0900 Subject: [PATCH] docs: organize public theme guides --- README.md | 11 +- USING_ION_ITEM_GROUP.md | 1 - demo/E2E_TESTING.md | 214 --------------------- demo/src/app/docs/docs-page.component.html | 2 +- BREAKING.md => docs/breaking.md | 34 ++-- docs/e2e-testing.md | 51 +++++ docs/experimental-animation.md | 6 + docs/features.md | 8 +- FEEDBACK.md => docs/feedback.md | 11 +- docs/ios-18.md | 11 +- docs/migration.md | 6 + docs/special-markup.md | 72 +++++++ docs/using-ion-item-group.md | 6 +- 13 files changed, 190 insertions(+), 243 deletions(-) delete mode 100644 USING_ION_ITEM_GROUP.md delete mode 100644 demo/E2E_TESTING.md rename BREAKING.md => docs/breaking.md (75%) create mode 100644 docs/e2e-testing.md rename FEEDBACK.md => docs/feedback.md (98%) create mode 100644 docs/special-markup.md diff --git a/README.md b/README.md index d851fee8..dd5cfd7f 100644 --- a/README.md +++ b/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. + +- [Breaking changes](./docs/breaking.md) β€” changes required when upgrading major versions. + + + + + **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 ``` + diff --git a/USING_ION_ITEM_GROUP.md b/USING_ION_ITEM_GROUP.md deleted file mode 100644 index 06272e14..00000000 --- a/USING_ION_ITEM_GROUP.md +++ /dev/null @@ -1 +0,0 @@ -This guide now lives in [docs/using-ion-item-group.md](./docs/using-ion-item-group.md). diff --git a/demo/E2E_TESTING.md b/demo/E2E_TESTING.md deleted file mode 100644 index 6de239ac..00000000 --- a/demo/E2E_TESTING.md +++ /dev/null @@ -1,214 +0,0 @@ -# E2E Screenshot Testing Guide - -This document explains how to use the Playwright-based screenshot testing system for the Ionic iOS26 Theme Demo application. - -## Overview - -The E2E test suite uses Playwright to capture full-page screenshots of all routes in the demo application. This ensures visual consistency and helps catch unintended UI changes. - -## Test Coverage - -### Routes Tested -All routes defined in `src/app/index/index.routes.ts` are automatically tested: - -- Index (main page) -- Action Sheet -- Alert -- Button -- Checkbox -- Range -- Toast -- Toggle -- Segment -- Modal -- Card -- Chip -- Breadcrumbs -- Searchbar -- Popover -- Progress Indicators -- Floating Action Button -- Select -- Radio -- Date and Time Pickers -- Accordion -- Inputs -- Item List -- Reorder -- Tabs -- Toolbar - -### Test Modes -Each route is tested in two modes: -- **Light Mode**: Default Ionic styling -- **Dark Mode**: With `ion-palette-dark` class applied - -**Total Tests**: 26 routes Γ— 2 modes = **52 screenshot tests** - -## Running Tests - -### Prerequisites - -Make sure you have installed all dependencies: - -```bash -npm install -``` - -Playwright browsers will be automatically installed when needed, or you can install them manually: - -```bash -npx playwright install chromium -``` - -### Test Commands - -#### Run all tests -```bash -npm run test:e2e -``` - -#### Interactive UI mode -Run tests with Playwright's interactive UI: -```bash -npm run test:e2e:ui -``` - -#### Debug mode -Step through tests with debugging tools: -```bash -npm run test:e2e:debug -``` - -#### Update screenshots -When you intentionally change the UI and need to update baseline screenshots: -```bash -npm run test:e2e:update -``` - -#### Run in Docker (same as CI) -To run tests in the same Linux environment as GitHub Actions (using the same Docker image): - -**Run tests in Docker**: -```bash -npm run test:e2e:docker -``` - -**Update screenshots in Docker**: -```bash -npm run test:e2e:docker:update -``` - -These commands will: -1. Mount the project root into the Docker container -2. Install dependencies -3. Start the development server inside Docker -4. Run Playwright tests -5. Clean up automatically - -This ensures your local test results match the CI environment exactly, including font rendering and browser behavior differences between macOS and Linux. - -## Understanding Test Results - -### Passing Tests -When a test passes, it means the current screenshot matches the baseline screenshot stored in `e2e/screenshot.spec.ts-snapshots/`. - -### Failing Tests -When a test fails, it indicates a visual difference between the current and baseline screenshots. This could be: -- An intentional UI change (update baselines with `npm run test:e2e:update`) -- An unintended regression (fix the issue and re-run tests) - -### Test Reports -After running tests, you can view detailed HTML reports: -```bash -npx playwright show-report -``` - -## CI/CD Integration - -The E2E tests run automatically on: -- Push to `main` or `develop` branches -- Pull requests targeting `main` or `develop` branches - -See `.github/workflows/e2e-tests.yml` for the CI configuration. - -### Viewing CI Results -When tests fail in CI: -1. Check the GitHub Actions workflow results -2. Download the `playwright-report` artifact to view the full report -3. Download the `test-results` artifact to see actual vs expected screenshots - -## File Structure - -``` -demo/ -β”œβ”€β”€ e2e/ -β”‚ β”œβ”€β”€ screenshot.spec.ts # Test specifications -β”‚ └── screenshot.spec.ts-snapshots/ # Baseline screenshots (committed to git) -β”œβ”€β”€ playwright-report/ # Test reports (gitignored) -β”œβ”€β”€ test-results/ # Failed test artifacts (gitignored) -└── playwright.config.ts # Playwright configuration -``` - -## Best Practices - -1. **Review visual changes carefully** before updating baselines -2. **Run tests locally** before pushing to avoid CI failures -3. **Update baselines only when UI changes are intentional** -4. **Use UI mode** (`npm run test:e2e:ui`) for easier debugging -5. **Check both light and dark mode** when making UI changes - -## Troubleshooting - -### Tests failing on CI but passing locally -This can happen due to: -- Font rendering differences between macOS and Linux -- Browser behavior differences between operating systems - -**Solution**: Update screenshots using Docker to match the CI environment: -```bash -npm run test:e2e:docker:update -``` - -This uses the same `mcr.microsoft.com/playwright:v1.56.0-noble` Docker image as GitHub Actions and regenerates screenshots in the Linux environment. - -### Slow test execution -- The development server takes time to start (configured timeout: 120s) -- Each screenshot capture includes a 500ms wait for animations to complete -- Parallel execution is configured to speed up the process - -### Screenshots appear incorrect -1. Ensure the development server is running correctly -2. Check that the route paths match those in `index.routes.ts` -3. Verify the page has fully loaded before screenshot capture - -## Updating the Test Suite - -### Adding new routes -When adding a new route to `index.routes.ts`, update `e2e/screenshot.spec.ts`: - -```typescript -const routes = [ - // ... existing routes - { path: '/index/new-page', name: 'new-page' }, -]; -``` - -Then run: -```bash -npm run test:e2e:update -``` - -### Modifying test behavior -Edit `playwright.config.ts` to adjust: -- Browser configurations -- Viewport sizes -- Timeout settings -- Screenshot options - -## Additional Resources - -- [Playwright Documentation](https://playwright.dev/) -- [Playwright Screenshots Guide](https://playwright.dev/docs/screenshots) -- [Visual Comparisons](https://playwright.dev/docs/test-snapshots) - diff --git a/demo/src/app/docs/docs-page.component.html b/demo/src/app/docs/docs-page.component.html index e996248c..2a52b90b 100644 --- a/demo/src/app/docs/docs-page.component.html +++ b/demo/src/app/docs/docs-page.component.html @@ -86,7 +86,7 @@

ion-searchbar.searchbar-classic

iOS26's searchbar classic style.

<ion-searchbar class="searchbar-classic"></ion-searchbar> - + diff --git a/BREAKING.md b/docs/breaking.md similarity index 75% rename from BREAKING.md rename to docs/breaking.md index 6fc3783e..5e38a8b5 100644 --- a/BREAKING.md +++ b/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 ``can now be used again without causing transition issues. +With this update, the previously discouraged pattern `` 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 `` with `` 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; diff --git a/docs/e2e-testing.md b/docs/e2e-testing.md new file mode 100644 index 00000000..257e5296 --- /dev/null +++ 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 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`. diff --git a/docs/experimental-animation.md b/docs/experimental-animation.md index fa3ea2a1..0c0a9131 100644 --- a/docs/experimental-animation.md +++ b/docs/experimental-animation.md @@ -1,3 +1,9 @@ +--- +title: Experimental animation +--- + +# Experimental animation + Optional gesture and animation helpers. The theme works without this feature. **This feature is experimental. The library can be used without this feature.** diff --git a/docs/features.md b/docs/features.md index 90c959da..cd5eaf50 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,4 +1,10 @@ -CSS variables, opt-out class, and the liquid glass mixin. See [Using ion-item-group](./using-ion-item-group.md) for list markup. +--- +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. ### CSS Variables diff --git a/FEEDBACK.md b/docs/feedback.md similarity index 98% rename from FEEDBACK.md rename to docs/feedback.md index 9a4b11ef..501a26c4 100644 --- a/FEEDBACK.md +++ b/docs/feedback.md @@ -1,16 +1,16 @@ -# Feature Requests for Ionic Framework +# Feature requests for Ionic Framework ## feat(): change `--knob-handle-size` to `--knob-handle-width` / `--knob-handle-height` Currently, only square sizes are taken into consideration. Overwriting the `knob` itself is possible, but `--knob-handle-size` cannot be ignored as it plays a crucial role in determining the `top` and `margin-inline-start` of `div.range-knob-handle`. - ## feat(): ion-config new property for `collapse` Currently, `collapse` behavior is automatically enabled in iOS mode, but this should be configurable through `ion-config` for better control. ex: + ```typescript export interface IonicConfig { ..., @@ -27,10 +27,10 @@ export interface IonicConfig { } ``` - ## feat(): add native shadow-part for design ### native-inner(or item-inner) part to ion-item + The styling for `ion-item[lines=inset]` is applied to `.item-inner`, which cannot be styled directly. This limitation means that for iOS 26 styling, I can only modify the border-bottom style through `::part(native)` with padding-right, preventing me from utilizing the full right side of `ion-item`. Adding `::part(native-inner)` would increase styling flexibility. ```diff @@ -49,14 +49,17 @@ The styling for `ion-item[lines=inset]` is applied to `.item-inner`, which canno Resolved: https://github.com/ionic-team/ionic-framework/pull/30992#event-23306774962 ## docs(): Naming conventions for Ionic theme classes + Resolved. ### should disable ion-back-button Animation + Resolved: by created https://github.com/rdlabo-dev/ionic-theme-ios26/tree/main/src/transition ## feat(): ion-content[fullscreen=true] will have .content-fullscreen class -Resolved: https://github.com/ionic-team/ionic-framework/pull/30926 +Resolved: https://github.com/ionic-team/ionic-framework/pull/30926 ## feat(): add .range-knob-min and .range-knob-max directly to ion-range + Resolved: https://github.com/ionic-team/ionic-framework/pull/30932 diff --git a/docs/ios-18.md b/docs/ios-18.md index 8b4a7fce..09bc6da1 100644 --- a/docs/ios-18.md +++ b/docs/ios-18.md @@ -1,11 +1,16 @@ -### How to prevent loading a theme file on iOS 18 +--- +title: Supporting iOS 18 +--- + +# Supporting iOS 18 + +## How to prevent loading the theme on iOS 18 If you want to load a theme file only when the user's device is running iOS 26 (and let users on iOS 18 use the default Ionic iOS theme), you can achieve this by adding a supports-condition to your `import`. ```css @import '@rdlabo/ionic-theme-ios26/dist/css/default-variables.css' supports(text-wrap: pretty); @import '@rdlabo/ionic-theme-ios26/dist/css/ionic-theme-ios26.css' supports(text-wrap: pretty); -@import '@rdlabo/ionic-theme-ios26/dist/css/md-remove-ios-class-effect.css' - supports(text-wrap: pretty); +@import '@rdlabo/ionic-theme-ios26/dist/css/md-remove-ios-class-effect.css' supports(text-wrap: pretty); @import '@rdlabo/ionic-theme-ios26/dist/css/md-ion-list-inset.css' supports(text-wrap: pretty); ``` diff --git a/docs/migration.md b/docs/migration.md index 18ac6c4f..7a2e3bd6 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,3 +1,9 @@ +--- +title: Migration +--- + +# Migration + For gradual migration, you can selectively apply the iOS26 theme by importing individual components instead of the full theme file. ```css diff --git a/docs/special-markup.md b/docs/special-markup.md new file mode 100644 index 00000000..50061313 --- /dev/null +++ b/docs/special-markup.md @@ -0,0 +1,72 @@ +--- +title: Special markup and classes +--- + +# Special markup and classes + +Most Ionic markup works without changes. The combinations below are explicit opt-ins used by the theme and demonstrated in `demo/src/app/docs`. + +## Primary submit buttons + +Solid primary submit buttons use `--ion-color-primary-brightness` for their foreground and border treatment. Define a value with sufficient contrast for your primary color. + +```css +:root { + --ion-color-primary-brightness: #96feff; +} +``` + +```html +Submit +``` + +## Two-line inset list items + +Place an unslotted `ion-label` immediately alongside an unslotted `ion-note` to render a two-line item. When using the iOS-style inset-list background, wrap the items in `ion-item-group`; keep `ion-list-header` outside the group. + +```html + + + Connections + + + + Network & internet + Mobile, Wi-Fi, hotspot + + + +``` + +Use `slot="end"` on `ion-note` when you want the standard trailing-note layout instead. + +## Full-width segments + +Add `.segment-expand` when segment buttons should divide the available width evenly. The class also changes the Liquid Glass effect sizing when `registerSegmentEffect` is used. + +```html + + New + Replied + +``` + +## Classic search bar + +The default theme uses the iOS 26 search field. Add `.searchbar-classic` to retain the classic Ionic iOS search-bar appearance. Place it inside `ion-toolbar` so the toolbar-specific layout rules apply. + +```html + + + +``` + +## Opting out + +Add `.ios26-disabled` to an individual Ionic component when it must retain Ionic's standard iOS styling. + +```html +Standard Ionic button +``` + +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 f340eea2..1f8e1c2e 100644 --- a/docs/using-ion-item-group.md +++ b/docs/using-ion-item-group.md @@ -1,4 +1,8 @@ -# Using `ion-item-group` with iOS26 Theme +--- +title: Using ion-item-group +--- + +# Using `ion-item-group` with the iOS26 theme 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`.