@rdlabo/ionic-theme-ios27 1.2.1 → 2.0.0-1

package/docs/eslint.md

@@ -2,6 +2,8 @@
 title: Keep lists consistent with ESLint
 ---
 
+# Keep lists consistent with ESLint
+
 Catch missing list groups before they reach the screen. In Ionic Angular apps, `@rdlabo/eslint-plugin-rules` checks the markup used by iOS 27.
 
 ## Enable the list check
@@ -60,7 +62,7 @@ Group the items and import `IonItemGroup` in the standalone component:
 
 The rule checks all `ion-list` elements, including non-inset lists. Radio, reorder, and accordion groups are also supported. It checks Angular templates; it does not inspect React or Vue templates.
 
-See [Using ion-item-group](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/using-ion-item-group) for layout examples and the [rule reference](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/rules/require-ion-item-group) for supported structures and automatic fixes.
+See [Using ion-item-group](using-ion-item-group.md) for layout examples and the [rule reference](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/rules/require-ion-item-group) for supported structures and automatic fixes.
 
 ## Keep it checked
 

package/docs/features.md

@@ -4,16 +4,20 @@ title: Features
 
 # Features
 
-Customize the theme with CSS variables and Sass mixins, or adopt it one component at a time. Markup-specific opt-ins are documented in [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup).
+Customize the theme with CSS variables and Sass mixins, or adopt it one component at a time. Markup-specific opt-ins are documented in [Special markup and classes](special-markup.md).
 
 ## CSS variables
 
 To customize the library's default styles to match your design, several CSS variables are provided. See this file for details:
 [Default variables](../src/styles/default-variables.scss)
 
-For menus, `--ios-theme-menu-background-rgb` sets the surface RGB channels (light: `225, 230, 240`; dark: `26, 31, 34`). `--ios-theme-menu-background-opacity` controls opacity and defaults to `0.96`. Both are public customization variables and can be set on `ion-menu`.
+| Variable                              | Default                                    | Purpose                                                           |
+| ------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
+| `--ios-theme-menu-background-rgb`     | Light: `225, 230, 240`; dark: `26, 31, 34` | Menu surface RGB channels; set on `ion-menu`.                     |
+| `--ios-theme-menu-background-opacity` | `0.96`                                     | Menu surface opacity; set on `ion-menu`.                          |
+| `--ios-theme-button-press-duration`   | `380ms`                                    | Duration of the button's `:active` scaling with slight overshoot. |
 
-Button press scaling follows `:active` with a slight overshoot. Set `--ios-theme-button-press-duration` (default: `380ms`) to customize its duration instead of the shared activated-transition duration variables.
+Use `--ios-theme-button-press-duration` instead of the shared activated-transition duration variables to customize button press scaling.
 
 ## Liquid Glass mixin
 
@@ -27,9 +31,9 @@ ion-textarea label.textarea-wrapper {
 }
 ```
 
-## Native UI Shell (Preview)
+## Native UI (Preview)
 
-Capacitor iOS apps can use the optional [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) to render supported fixed Ionic controls with UIKit and system Liquid Glass. It is available as a preview in `1.2.0`. Content and application logic stay in the WebView, with Ionic owning routing and page transitions. The guide explains the hybrid approach's origins in Basecamp and Capacitor, setup, supported controls and Web fallback behavior.
+Once your theme is working, [add Native UI](add-native-ui.md) to render supported fixed controls with UIKit and SwiftUI on iOS. Keep theme styles for Web content and fallback controls. Native UI is an optional preview; adding styles alone does not enable it.
 
 ## Selective component imports
 

package/docs/iphone-duo.md

@@ -1,32 +1,40 @@
 ---
-title: iPhone Duo support (preview)
+title: iPhone Duo support
 ---
 
-# iPhone Duo support (preview)
+# iPhone Duo support
 
 Adapt your Ionic app to iPhone Duo: place navigation and actions in its vertical system rail, and adjust your split pane as the device opens and closes. Existing Ionic markup remains the source of labels, icons, routing, and click handlers.
 
-**New here?** Start with [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme) to preview the side layout in Chrome. This page explains device events, placement and split panes. [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) documents control projection and the runtime API.
+**New here?** Start with [iPhone Duo with your existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md) to preview the side layout in Chrome. This page explains device events, placement and split panes. [Vertical Bars](../../capacitor-native-ui/docs/vertical-bars.md) documents control projection and the runtime API.
 
-Available in `1.2.0` as a **preview** feature alongside [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell). APIs and supported behavior may change before stable status. Stable status is planned after the official release of Xcode 27.1. The real system rail and hinge reporting require iOS 27.1 or later and an app built with Xcode 27.1 or newer.
+iPhone Duo support is stable starting with version 2.0.0. The real system rail and hinge reporting require iOS 27.1 or later and an app built with Xcode 27.1 or newer.
 
-This package provides two independent pieces for that hardware. Each works **without the iOS 27 theme stylesheets** and **without the full Native UI Shell**:
+Use the theme layout and native plugin independently for that hardware. Neither requires the full iOS 27 appearance:
 
-- `dist/css/vertical-bars.css` — opt-in classes that reserve the rail's safe area, plus a registered custom property for a posture-driven split-pane width.
-- `enableVerticalControlArea()` — moves eligible tabs and toolbar controls into the reserved area. On Capacitor iOS they are rendered by a native SwiftUI `TabView` and toolbar; everywhere else the same controls appear as Web clones.
+- Theme: `dist/css/vertical-bars.css` — opt-in classes that reserve the rail's safe area, plus a registered custom property for a posture-driven split-pane width.
+- Native UI: `enableNativeUI({ controls: 'verticalOnly' })` — selects eligible tabs and toolbar controls placed in the reserved area. On Capacitor iOS they are rendered by a native SwiftUI `TabView` and toolbar; everywhere else the same controls appear as Web clones.
 
-Device state belongs to [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable). The **application** subscribes to its events and chooses its layout. This package's **stylesheet and runtime** apply that decision by reserving space, projecting controls and adapting the split pane. The theme does not monitor hinge state or bar placement.
+Device state belongs to [`@erkamyaman/capacitor-foldable`](https://github.com/erkamyaman/capacitor-foldable). The **application** subscribes to its events and chooses its layout. The theme reserves space and adapts the split pane; Native UI projects eligible controls. The theme does not monitor hinge state or bar placement.
+
+| Owner               | Responsibility                                                                                              |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Foldable            | Report bar placement and hinge posture, initially and when they change.                                     |
+| Application / theme | Subscribe to device events and apply Web layout through `setVerticalBarsLayout` or `applyFoldStateClasses`. |
+| Native UI           | Project eligible controls and determine native rail availability independently.                             |
+
+For the native package's integration, including application-owned CSS and plain HTML, see [Use with Capacitor Foldable](../../capacitor-native-ui/docs/vertical-bars.md#use-with-capacitor-foldable).
 
 ## Choose what to adopt
 
-To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme). This page covers the shared device-layout rules.
+To keep your existing theme and add only the standalone support, follow [iPhone Duo with your existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md). This page covers the shared device-layout rules.
 
-| Goal                                             | Stylesheet          | Runtime                                                            |
-| ------------------------------------------------ | ------------------- | ------------------------------------------------------------------ |
-| Hinge posture only (layout switches) | none | none — subscribe to `Foldable` directly |
-| Posture-driven split-pane width | `vertical-bars.css` | none — subscribe to `Foldable` directly |
-| Vertical rail for tabs and toolbar actions       | `vertical-bars.css` | `enableVerticalControlArea()`                                      |
-| Native shell plus the rail                       | `vertical-bars.css` | `enableNativeUIShell()` — includes rail projection |
+| Goal                                       | Stylesheet          | Runtime                                        |
+| ------------------------------------------ | ------------------- | ---------------------------------------------- |
+| Hinge posture only (layout switches)       | none                | none — subscribe to `Foldable` directly        |
+| Posture-driven split-pane width            | `vertical-bars.css` | none — subscribe to `Foldable` directly        |
+| Vertical rail for tabs and toolbar actions | `vertical-bars.css` | `enableNativeUI({ controls: 'verticalOnly' })` |
+| Native shell plus the rail                 | `vertical-bars.css` | `enableNativeUI()` — includes rail projection  |
 
 ```scss
 @use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
@@ -51,7 +59,7 @@ After `ion-app` is mounted, pass device state to `applyFoldStateClasses`. The ap
 
 ```ts
 import { Foldable } from '@erkamyaman/capacitor-foldable';
-import { applyFoldStateClasses } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+import { applyFoldStateClasses } from '@rdlabo/ionic-theme-ios27';
 
 const root = document.querySelector('ion-app')!;
 const listener = await Foldable.addListener('foldStateChange', (fold) => applyFoldStateClasses(root, fold));
@@ -66,9 +74,31 @@ await listener.remove();
 
 Subscribe to changes, then read the current state. The same helper handles initial values and events.
 
-`applyFoldStateClasses` keeps one of `ios-theme-fold-flat`, `ios-theme-fold-half-opened`, and `ios-theme-fold-closed` on the supplied root, preserving unrelated classes. It also sets `ios-theme-fold-expanded` for a half-opened state or a flat state with hinge geometry. A flat state without geometry (including the Web fallback) and a closed state clear that class. The helper does not subscribe to the plugin or change Ionic's split-pane `when` property.
+### Posture classes
+
+`applyFoldStateClasses` updates the supplied root while preserving unrelated classes:
+
+| Class                        | Applied when                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ios-theme-fold-flat`        | Flat posture.                                                                                                            |
+| `ios-theme-fold-half-opened` | Half-opened posture.                                                                                                     |
+| `ios-theme-fold-closed`      | Closed posture.                                                                                                          |
+| `ios-theme-fold-expanded`    | Half-opened, or flat with hinge geometry. Cleared for flat without geometry (including Web fallback) and closed posture. |
+
+Only one of the first three classes is retained. The helper does not subscribe to the plugin or change Ionic's split-pane `when` property.
+
+### Placement values
+
+For rail placement, import `setVerticalBarsLayout` from the theme and pass the reported logical `edge` with the measured `inset`:
+
+| Value              | Web layout effect                                    |
+| ------------------ | ---------------------------------------------------- |
+| `edge: 'leading'`  | Physical left in LTR; physical right in RTL.         |
+| `edge: 'trailing'` | Physical right in LTR; physical left in RTL.         |
+| `edge: null`       | Restores ordinary layout.                            |
+| Measured `inset`   | Reserves that width; zero clears the explicit width. |
 
-For rail placement, use `setVerticalControlAreaPlacement` as shown below. Pass the reported logical edge as both `edge` and `nativeEdge`, together with the measured `inset`. Leading is the physical left in LTR and the physical right in RTL. A null edge restores the ordinary layout; an inset of zero clears the explicit width. No start/stop monitoring calls are needed.
+The helper does not report native availability or activate projection. No start/stop monitoring calls are needed. See [Project controls into the rail](#project-controls-into-the-rail) for the subscription.
 
 WebView corner radius remains a rendering concern: `configureNativeTransition()` uses the shell's `getWebViewMetrics()` API, independently of `Foldable`.
 
@@ -76,22 +106,23 @@ WebView corner radius remains a rendering concern: `configureNativeTransition()`
 
 ## Reserve the vertical rail
 
-Load `vertical-bars.css` as shown above. For class-based browser simulation, safe-area handling, RTL and overlay layout, see [Reserve the vertical rail](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#reserve-the-vertical-rail). On device, the placement helper below applies the layout classes and measured inset.
+Load `vertical-bars.css` as shown above. For class-based browser simulation, safe-area handling, RTL and overlay layout, see [Reserve the vertical rail](vertical-bars-layout.md#reserve-the-vertical-rail). On device, the placement helper below applies the layout classes and measured inset.
 
 ## Project controls into the rail
 
-Start the standalone runtime once after `ion-app` is mounted, and apply the plugin's placement with `setVerticalControlAreaPlacement`:
+Enable rail projection once after `ion-app` is mounted, and apply Foldable's placement to the Web layout with `setVerticalBarsLayout`:
 
 ```ts
 import { Foldable } from '@erkamyaman/capacitor-foldable';
-import { setVerticalControlAreaPlacement, enableVerticalControlArea } from '@rdlabo/ionic-theme-ios27/vertical-bars';
+import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
+import { enableNativeUI } from '@rdlabo/capacitor-native-ui';
 
-const rail = await enableVerticalControlArea();
+const rail = await enableNativeUI({ controls: 'verticalOnly' });
 const listener = await Foldable.addListener('barPlacementChange', ({ verticalBarEdge, inset }) =>
-  setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset }),
+  setVerticalBarsLayout({ edge: verticalBarEdge, inset }),
 );
 const { verticalBarEdge, inset } = await Foldable.getBarPlacement();
-setVerticalControlAreaPlacement({ edge: verticalBarEdge, nativeEdge: verticalBarEdge, inset });
+setVerticalBarsLayout({ edge: verticalBarEdge, inset });
 ```
 
 When the application owner is disposed:
@@ -101,30 +132,26 @@ await listener.remove();
 await rail.destroy();
 ```
 
-Supply `nativeEdge` on both the initial read and each event so the renderer knows which rail the system actually provides. The measured `inset` is passed through instead of assuming a fixed width. Devices without a reported rail, including Web and Android, return a null edge and retain the ordinary layout. For browser simulation, use the [class-based preview](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#reserve-the-vertical-rail) without connecting device placement.
+Native UI detects native availability independently through its own device metrics. The theme helper controls Web layout only. The measured `inset` is passed through instead of assuming a fixed width. Devices without a reported rail, including Web and Android, return a null edge and retain the ordinary layout. For browser simulation, use the [class-based preview](vertical-bars-layout.md#reserve-the-vertical-rail) without connecting device placement.
 
-Start either `enableVerticalControlArea()` or the full `enableNativeUIShell()` — not both. If the app already uses Native UI Shell, keep that runtime and use the same `setVerticalControlAreaPlacement` callback. The application owner removes its listeners and destroys its runtime on teardown.
+Start either `enableNativeUI({ controls: 'verticalOnly' })` or the full `enableNativeUI()` — not both. If the app already uses Native UI, keep that runtime and use the same `setVerticalBarsLayout` callback. The application owner removes its listeners and destroys its runtime on teardown.
 
-On supported iOS versions the runtime hands eligible tabs, back navigation, menu buttons, and fixed-toolbar actions to a native SwiftUI `TabView` and toolbar; on Web, Android, or when native projection is unavailable, Web clones remain the fallback. See [Toolbar actions](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for control eligibility.
+On supported iOS versions the runtime hands eligible tabs, back navigation, menu buttons, and fixed-toolbar actions to a native SwiftUI `TabView` and toolbar; on Web, Android, or when native projection is unavailable, Web clones remain the fallback. See [Toolbar actions](../../capacitor-native-ui/docs/vertical-bars.md#toolbar-actions) for control eligibility.
 
 ### Toolbar actions
 
-See [Vertical Bars: Toolbar actions](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#toolbar-actions) for eligible markup, placement, button appearance and local overrides.
+See [Vertical Bars: Toolbar actions](../../capacitor-native-ui/docs/vertical-bars.md#toolbar-actions) for eligible markup, placement, button appearance and local overrides.
 
 ### Tab bar
 
-See [Vertical Bars: Tab bar](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#tab-bar) for navigation, labels and Web fallback behavior.
+See [Vertical Bars: Tab bar](../../capacitor-native-ui/docs/vertical-bars.md#tab-bar) for navigation, labels and Web fallback behavior.
 
 ## Adapt the split pane
 
 For a side-by-side menu on iPhone Duo, opt the `ion-split-pane` into the separately measured Settings layout. The sidebar is 320pt when fully unfolded and reaches the display midpoint when half-opened (50vw). The application supplies the posture; both states have the same viewport width, so a width media query cannot distinguish them:
 
 ```html
-<ion-split-pane
-  class="split-pane-fold-layout"
-  contentId="main-content"
-  when="(min-width: 900px)"
->
+<ion-split-pane class="split-pane-fold-layout" contentId="main-content" when="(min-width: 900px)">
   <ion-menu contentId="main-content">...</ion-menu>
   <div id="main-content">...</div>
 </ion-split-pane>
@@ -147,4 +174,4 @@ Ionic's `when` still controls whether the menu is persistent. The example choose
 
 ## Vertical Control Area API
 
-The runtime handle reference is maintained in [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars#vertical-control-area-api).
+The runtime handle reference is maintained in [Vertical Bars](../../capacitor-native-ui/docs/vertical-bars.md#vertical-control-area-api).

package/docs/migration.md

@@ -1,35 +1,23 @@
 ---
-title: Migration
+title: Theme migration
 ---
 
-# Migration
+# Theme migration
 
-## Native UI Shell transition adapter
+## Native UI package separation
 
-Use `withNativeUIShellTransition()` to keep your existing Ionic navigation animation while coordinating Native UI Shell controls.
+Theme styles and ordinary theme API imports remain supported. If you previously used native controls through this package, the `/native` and `/vertical-bars` entries have been removed:
 
-- If you already import `iosTransitionAnimation` from `@rdlabo/ionic-theme-ios27`, keep the [package animation setup](./iphone-duo-with-original-theme.md#use-this-package%27s-ios-animation); no configuration change is needed. It now uses the shared adapter internally; do not add another wrapper.
-- If you use Ionic's default animation without a `navAnimation` option, follow [Keep Ionic's default animation](./iphone-duo-with-original-theme.md#keep-ionic%27s-default-animation). The example selects Ionic's standard iOS or MD builder from the transition mode.
-- If you use a custom navigation animation with Native UI Shell or the standalone Vertical Control Area, wrap your existing builder when configuring Ionic:
+| Previous import                           | Replacement                                 |
+| ----------------------------------------- | ------------------------------------------- |
+| `@rdlabo/ionic-theme-ios27/native`        | `@rdlabo/capacitor-native-ui`               |
+| `@rdlabo/ionic-theme-ios27/vertical-bars` | `@rdlabo/capacitor-native-ui/vertical-bars` |
 
-```diff
-+ import { withNativeUIShellTransition } from '@rdlabo/ionic-theme-ios27/vertical-bars';
-
-  const ionicConfig = {
--   navAnimation: existingTransition,
-+   navAnimation: withNativeUIShellTransition(existingTransition),
-  };
-```
-
-Merge this option into your existing Ionic configuration before initialization. The adapter preserves the animation's effects, duration, and easing while coordinating native retirement, swipe progress, and cancellation. Keep your existing theme stylesheet imports and Native UI Shell or Vertical Control Area startup.
-
-Use the adapter only for navigation; leave modal and popover animations unchanged. Your builder must create a fresh `Animation` for each navigation because Ionic destroys it afterward. Keep lifecycle events for control registration and transitions without animation. If the custom builder animates a horizontal back button separately, exclude that effect while `.ios-theme-vertical-bars` is active.
-
-See [Connect your navigation animation](./iphone-duo-with-original-theme.md#3.-connect-your-navigation-animation) for the setup and supported scope.
+Add the native package as a direct application dependency, update imports, rebuild Web assets, and run `npx cap sync ios`. Follow the [Native UI migration guide](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/migration.md) for 1.2.1 startup settings and native project changes. Theme-only apps do not need native startup or plugin setup.
 
 ## From the iOS 26 theme
 
-For an app using `@rdlabo/ionic-theme-ios26`, the recommended migration keeps that package and adds `@rdlabo/ionic-theme-ios27`. The [README setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/readme#get-started) selects iOS 27 or iOS 26 styles by browser capability and leaves Ionic's default iOS appearance on older browsers.
+For an app using `@rdlabo/ionic-theme-ios26`, the recommended migration keeps that package and adds `@rdlabo/ionic-theme-ios27`. The [adaptive theme setup](adaptive-themes.md) selects iOS 27 or iOS 26 styles by browser capability and leaves Ionic's default iOS appearance on older browsers.
 
 ### 1. Add the new package
 
@@ -127,17 +115,20 @@ To switch entirely to iOS 27, remove the iOS 26 package and replace its styleshe
 + @use '@rdlabo/ionic-theme-ios27/src/styles/md-remove-ios-class-effect.scss';
 ```
 
-Change the animation import from `@rdlabo/ionic-theme-ios26` to `@rdlabo/ionic-theme-ios27`; the existing `isPlatform('ios')` configuration can stay. See the README's [iOS 27-only setup](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/readme#use-only-the-ios-27-theme). Unconditional imports apply the new styles on every browser using Ionic iOS mode.
+Change the animation import from `@rdlabo/ionic-theme-ios26` to `@rdlabo/ionic-theme-ios27`; the existing `isPlatform('ios')` configuration can stay. See the [iOS 27 setup](setup.md). Unconditional imports apply the new styles on every browser using Ionic iOS mode.
 
 ## iOS 27 naming
 
 For the iOS 27 branch or an iOS 27-only app, use `@rdlabo/ionic-theme-ios27`. Its stylesheets are `ionic-theme-ios27.scss` or `ionic-theme-ios27.css`, including the `-dark-always`, `-dark-system`, and `-dark-class` variants. Keep the iOS 26 stylesheet names in the iOS 26 branch of an adaptive setup.
 
-Use the version-independent `--ios-theme-*` CSS variables. The corresponding `--ios26-*` variables remain supported as deprecated fallbacks. When both are set, the new name takes precedence. For example, use `--ios-theme-content-box-shadow-rgb` instead of `--ios26-content-box-shadow-rgb`.
+| Customization       | Current name                                                      | Legacy behavior                                                                                   |
+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| CSS variables       | `--ios-theme-*`, for example `--ios-theme-content-box-shadow-rgb` | Corresponding `--ios26-*` names remain deprecated fallbacks. Current names win when both are set. |
+| Theme opt-out class | `ios-theme-disabled`                                              | `ios26-disabled` remains a deprecated alias; migrate existing markup when convenient.             |
 
-For opting out of the theme, use the version-independent `ios-theme-disabled` class. The `ios26-disabled` class remains supported as a deprecated alias; migrate existing markup when convenient.
+Use the version-independent names for new customizations.
 
-See [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup) and [Default variables](../src/styles/default-variables.scss) for the current names.
+See [Special markup and classes](special-markup.md) and [Default variables](../src/styles/default-variables.scss) for the current names.
 
 Earlier migration notes are preserved in the [iOS 26 migration guide](https://docs.rdlabo.dev/projects/ionic-theme-ios26/docs/migration).
 

package/docs/setup.md

@@ -0,0 +1,92 @@
+# Set up the iOS 27 theme
+
+Give an existing Ionic app the iOS 27 appearance in four steps. This guide uses the iOS 27 theme on its own and system dark mode. For browser-dependent iOS 26/27 styling or MD3, use [adaptive themes](adaptive-themes.md) instead.
+
+## Before you start
+
+Use an existing Ionic Angular, React, or Vue application with Ionic `>=8.8.1 <10`. Keep Ionic's base CSS imports. Capacitor is not required, including for browser-only apps.
+
+## 1. Install the theme
+
+```sh
+npm install @rdlabo/ionic-theme-ios27
+```
+
+## 2. Load the styles
+
+Add these imports to your global stylesheet after Ionic's base styles. Replace an existing Ionic dark palette import rather than loading multiple palettes:
+
+```css
+@import '@ionic/core/css/palettes/dark.system.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/default-variables.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/md-remove-ios-class-effect.css';
+@import '@rdlabo/ionic-theme-ios27/dist/css/ionic-theme-ios27-dark-system.css';
+```
+
+### Choose one dark-mode pair
+
+Use one matching Ionic palette and theme variant. Paths below are relative to `@ionic/core/css/palettes/` and `@rdlabo/ionic-theme-ios27/dist/css/` respectively.
+
+| Mode                   | Ionic palette     | Theme stylesheet                    | Activation                                      |
+| ---------------------- | ----------------- | ----------------------------------- | ----------------------------------------------- |
+| System (example above) | `dark.system.css` | `ionic-theme-ios27-dark-system.css` | System appearance.                              |
+| Manual                 | `dark.class.css`  | `ionic-theme-ios27-dark-class.css`  | Toggle `ion-palette-dark` on the document root. |
+| Always dark            | `dark.always.css` | `ionic-theme-ios27-dark-always.css` | Always active.                                  |
+
+If you also enable Native UI, these styles provide its light/dark appearance marker. Keep the Ionic palette and theme variant paired so Web and native controls agree. See [native appearance inheritance](../../capacitor-native-ui/docs/appearance.md) for the resolution order and shared rail behavior.
+
+## 3. Configure Ionic animations
+
+Set these options in your existing Ionic initialization, before rendering the app:
+
+```ts
+import { iosTransitionAnimation, popoverEnterAnimation, popoverLeaveAnimation } from '@rdlabo/ionic-theme-ios27';
+
+const ionicConfig = {
+  mode: 'ios' as const,
+  navAnimation: iosTransitionAnimation,
+  popoverEnter: popoverEnterAnimation,
+  popoverLeave: popoverLeaveAnimation,
+};
+```
+
+This example deliberately uses `ios` mode so desktop browsers show the theme too. Pass `ionicConfig` to the initializer your app already uses:
+
+| Framework         | Apply the options                                                            |
+| ----------------- | ---------------------------------------------------------------------------- |
+| Angular / Ionic 8 | `provideIonicAngular(ionicConfig)` imported from `@ionic/angular/standalone` |
+| Angular / Ionic 9 | `provideIonicAngular(ionicConfig)` imported from `@ionic/angular`            |
+| React             | `setupIonicReact(ionicConfig)` imported from `@ionic/react`                  |
+| Vue               | `app.use(IonicVue, ionicConfig)` with `IonicVue` from `@ionic/vue`           |
+
+Merge with existing options; do not initialize Ionic twice. To retain Material Design mode on Android, keep your platform-based mode selection and apply these animation options only to the iOS configuration. See [adaptive themes](adaptive-themes.md) for a complete platform-aware example.
+
+## 4. Preview your first screen
+
+Start your application's usual development server and open an existing page. Add this markup inside its `ion-content` (use your framework's component syntax):
+
+```html
+<ion-list inset="true">
+  <ion-item-group>
+    <ion-item><ion-label>Notifications</ion-label></ion-item>
+    <ion-item><ion-label>Appearance</ion-label></ion-item>
+  </ion-item-group>
+</ion-list>
+```
+
+You should see an inset group with rounded edges. Switch the system between light and dark appearance, then navigate between pages to see the theme transition. Read [Using ion-item-group](using-ion-item-group.md) for list structure.
+
+| If you see…                         | Check…                                                        |
+| ----------------------------------- | ------------------------------------------------------------- |
+| Material Design controls on desktop | Set `mode: 'ios'` in the existing Ionic initializer.          |
+| Unstyled controls                   | Load the theme stylesheet globally after Ionic's base styles. |
+| Mixed light and dark surfaces       | Use one matching Ionic palette and theme dark-mode variant.   |
+| Default page transitions            | Pass the animation options before Ionic initializes.          |
+
+## Next steps
+
+- [Customize styles and components](features.md).
+- [Add Native UI](add-native-ui.md) for supported controls in a Capacitor iOS app. Theme installation alone does not enable native controls.
+- [Add Vertical Bars with an existing theme](../../capacitor-native-ui/docs/ionic-vertical-bars.md).
+- [Migrate an existing app](migration.md).

package/docs/special-markup.md

@@ -28,15 +28,38 @@ buttons: [
 ];
 ```
 
-Buttons with no role or `default` keep the normal text color. `cancel` retains Ionic's cancellation behavior, `selected` remains a selection state, and `destructive` uses `--ios-theme-destructive-color`. An existing `confirm` role is not treated as preferred. Use `preferred` for the recommended action, not simply any action that confirms a choice.
+Choose the role by action semantics:
+
+| Role                 | Appearance and behavior                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------- |
+| `preferred`          | Filled primary action; dismissal reports `preferred`. Does not automatically select or invoke it. |
+| No role or `default` | Normal text color.                                                                                |
+| `cancel`             | Retains Ionic's cancellation behavior.                                                            |
+| `selected`           | Retains selection state.                                                                          |
+| `destructive`        | Uses `--ios-theme-destructive-color`.                                                             |
+| `confirm`            | Not treated as preferred. Use `preferred` for a recommended action, not simply any confirmation.  |
 
 ## Floating iPad sheets
 
-Set `expandToScroll: false` on a sheet modal to use floating lower corners and a 20px bottom gap on iPad. Ionic then sizes the visible page at each breakpoint, so the theme can style it with CSS alone. Content scrolls within the current breakpoint; dragging the handle still resizes the sheet. With the default `expandToScroll: true`, the sheet keeps Ionic's bottom-attached layout and scroll-to-expand behavior.
+Choose the sheet's scrolling behavior with `expandToScroll`:
+
+| Setting          | iPad appearance                               | Scrolling and resizing                                                                                                                                     |
+| ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false`          | Floating lower corners and a 20px bottom gap. | Content scrolls within the current breakpoint; dragging the handle resizes the sheet. Ionic sizes the visible page at each breakpoint so CSS can style it. |
+| `true` (default) | Ionic's bottom-attached layout.               | Scroll-to-expand behavior.                                                                                                                                 |
 
 ## Tab bar position
 
-Add one of `tab-bar-position-start`, `tab-bar-position-center`, or `tab-bar-position-end` to an iOS `ion-tab-bar` to position the whole bar within its safe area. These classes work with both `slot="top"` and `slot="bottom"` and preserve the bar's width and press animation. Start and end follow the text direction (reversed in RTL). Without a class, the existing placement is unchanged.
+Choose a class on an iOS `ion-tab-bar` to position the whole bar within its safe area:
+
+| Class                     | Placement                       |
+| ------------------------- | ------------------------------- |
+| `tab-bar-position-start`  | Start of the reading direction. |
+| `tab-bar-position-center` | Center.                         |
+| `tab-bar-position-end`    | End of the reading direction.   |
+| None                      | Existing placement unchanged.   |
+
+All three classes support `slot="top"` and `slot="bottom"`, preserve width and press animation, and resolve start/end in RTL.
 
 ```html
 <ion-tab-bar slot="bottom" class="tab-bar-position-center">
@@ -47,15 +70,15 @@ Add one of `tab-bar-position-start`, `tab-bar-position-center`, or `tab-bar-posi
 
 These classes do not reposition a separate `ion-fab`; leave room for it when choosing the bar's position.
 
-## Support iPhone Duo (preview)
+## Support iPhone Duo
 
-iPhone Duo support, including standalone vertical bars, is available as a **preview** in `1.2.0` alongside Native UI Shell. Its APIs and supported behavior may change.
+iPhone Duo support, including standalone Vertical Bars, is stable starting with version 2.0.0.
 
-iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI Shell. See [iPhone Duo support](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo) for the complete setup, including device-layout monitoring without a projection runtime.
+iPhone Duo support — the vertical system rail, hinge posture, and the posture-driven split-pane layout — is independent of the iOS 27 theme and the full Native UI. See [iPhone Duo support](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/theme-ios27/docs/iphone-duo.md) for the complete setup, including device-layout monitoring without a projection runtime.
 
-See [Vertical Bars](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/vertical-bars) for rail layout classes, control eligibility and native button appearance.
+See [Vertical Bars](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/vertical-bars.md) for rail layout classes, control eligibility and native button appearance.
 
-For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/iphone-duo-with-original-theme).
+For standalone setup while keeping your existing theme, see [iPhone Duo with your existing theme](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/ionic-vertical-bars.md).
 
 ## Two-line inset list items
 
@@ -115,7 +138,15 @@ For colored segments, use Ionic's `color` property (for example, `color="primary
 
 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.
 
-Segments use a 32px minimum height in content and a 48px minimum height inside `ion-toolbar`. `.segment-expand` keeps the compact 32px layout in a toolbar. Compact segments retain Ionic's flat background and indicator colors; only the regular toolbar variant has a glass container and scales its outer container while pressed. Content and expanded segments keep their outer bounds. The optional moving glass lens is independent of the container's background.
+### Segment size and press behavior
+
+| Placement                                 | Minimum height | Container behavior                                               |
+| ----------------------------------------- | -------------- | ---------------------------------------------------------------- |
+| In content                                | 32px           | Compact, flat background and indicator; outer bounds stay fixed. |
+| Inside `ion-toolbar`                      | 48px           | Glass container; outer container scales while pressed.           |
+| `.segment-expand`, including in a toolbar | 32px           | Compact, flat background and indicator; outer bounds stay fixed. |
+
+The optional moving glass lens is independent of the container's background.
 
 ```html preview
 <ion-segment class="segment-expand" value="new">
@@ -178,4 +209,4 @@ Add `.ios-theme-disabled` to an individual Ionic component when it must retain I
 <ion-button>iOS 27 theme</ion-button> <ion-button class="ios-theme-disabled">Standard Ionic button</ion-button>
 ```
 
-For the background model behind inset lists, see [Using `ion-item-group`](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/using-ion-item-group).
+For the background model behind inset lists, see [Using `ion-item-group`](using-ion-item-group.md).

package/docs/using-ion-item-group.md

@@ -20,7 +20,7 @@ The examples use framework-neutral Web Component markup. In React or Vue, use th
 
 No wrapper is required for lists that do not use `inset="true"`.
 
-[Check list structure with ESLint](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/eslint).
+[Check list structure with ESLint](eslint.md).
 
 ## Why the wrapper is required
 
@@ -44,4 +44,4 @@ When an application uses this package without `@rdlabo/ionic-theme-md3`, import
 @import '@rdlabo/ionic-theme-ios27/dist/css/md-ion-list-inset.css';
 ```
 
-For two-line items and section-header groups, see [Special markup and classes](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/special-markup).
+For two-line items and section-header groups, see [Special markup and classes](special-markup.md).

package/docs/vertical-bars-layout.md

@@ -0,0 +1,67 @@
+# Vertical Bars layout
+
+This optional theme stylesheet owns Web spacing and positioning around a vertical rail. It can be used with your existing theme without loading the full iOS 27 appearance. Native rendering and state synchronization are provided separately by [Capacitor Native UI](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/vertical-bars.md).
+
+```sh
+npm install @rdlabo/ionic-theme-ios27
+```
+
+```scss
+@use '@rdlabo/ionic-theme-ios27/dist/css/vertical-bars.css';
+```
+
+The layout behavior below assumes this stylesheet is loaded. For native runtime setup and device placement, follow the [integration guide](https://github.com/rdlabo-dev/ionic-theme-ios27/blob/main/packages/capacitor-native-ui/docs/ionic-vertical-bars.md).
+
+## Reserve the vertical rail
+
+Add `.ios-theme-vertical-bars` to `ion-app` to reserve the rail region on the physical right, or add `.ios-theme-vertical-bars-left` as well to use the physical left:
+
+```html
+<ion-app class="ios-theme-vertical-bars">...</ion-app>
+```
+
+The classes are physical — `-left` always means the physical left edge — because CSS and the native renderer work in physical coordinates. `setVerticalBarsLayout` applies the logical `verticalBarEdge` reported by the device plugin and resolves it through the document's direction, so an RTL app does not need its own conversion.
+
+### Rail width
+
+| Source                                   | Reserved width                                                                                      |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Classes alone, including Chrome previews | `80px`; no native plugin required.                                                                  |
+| `setVerticalBarsLayout({ edge, inset })` | The supplied inset, even below `80px`.                                                              |
+| Custom CSS preview                       | Override `--ios-theme-vertical-bars-safe-area-left` or `--ios-theme-vertical-bars-safe-area-right`. |
+
+### Content and overlay layout
+
+| Surface                                  | Layout with the rail stylesheet                                                                                                                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Routers and component backgrounds        | Remain full-viewport.                                                                                                                                                                        |
+| `ion-content`                            | Insets its scroll foreground.                                                                                                                                                                |
+| `ion-toolbar`                            | Insets its container foreground.                                                                                                                                                             |
+| `ion-fab`                                | Adjusts only when placed beside the system UI.                                                                                                                                               |
+| Full-width `ion-modal`, including sheets | Applies the foreground inset. With the runtime enabled, the topmost modal projects eligible toolbar controls into its own rail; sheet rails follow visible bounds as the breakpoint changes. |
+| Centered modal                           | Keeps toolbar buttons and receives no page-rail inset.                                                                                                                                       |
+| `ion-menu` / `ion-popover`               | Internal foreground components retain Ionic's standard safe-area handling, without the main-page conversion.                                                                                 |
+| Menu beside the system UI                | Keeps its full-viewport animation host; offsets only the visible container by the inset.                                                                                                     |
+| Menu on the opposite side                | Unchanged.                                                                                                                                                                                   |
+
+The corresponding Ionic safe-area variable is reset inside inset foreground components so descendants do not add the inset again.
+
+Modal eligibility follows the visible dialog width, not hinge posture or modal type. Left and right remain physical coordinates in RTL; Ionic's `side="start"` and `side="end"` remain logical.
+
+The mode is component-mode independent: an app can keep Ionic `mode: 'md'` on iOS and still enable Vertical Bars. No component needs `mode="ios"`.
+
+## Layout API
+
+```ts
+import { setVerticalBarsLayout } from '@rdlabo/ionic-theme-ios27';
+
+setVerticalBarsLayout({ edge: 'trailing', inset: 80 });
+// Optionally supply a root element and explicit RTL boolean as the next arguments.
+setVerticalBarsLayout({ edge: null }); // restore ordinary Web layout
+```
+
+The helper operates on Web CSS only and works without Capacitor or Native UI startup. The application supplies device state and owns subscriptions. Starting, disabling or destroying Native UI does not change these layout classes or the reserved inset. Unsupported native rails retain the chosen Web rail; choose `edge: null` explicitly if the application wants a horizontal layout instead.
+
+## Migration
+
+Move `setVerticalControlAreaPlacement` calls from the plugin to `setVerticalBarsLayout({ edge, inset })` from the theme. Move `applyFoldStateClasses` imports to the theme too. Remove `nativeEdge`: it no longer reports availability. The old plugin helpers are deprecated; update existing imports using the [migration guide](../../capacitor-native-ui/docs/migration.md#web-layout-ownership).