/port

Platform UX Adaptation

Translate web UX into Apple HIG (iOS) and Material Design 3 (Android). The two are different in philosophy — accept divergence as a feature, not a bug.

Component naming translation (Web ↔ HIG ↔ Material 3 / Compose terms) → ui-terminology-matrix.md. This file covers behavior adaptation.

Core Principle

Web designers think in pages and breakpoints. iOS thinks in flows and gestures. Android thinks in screens and shared transitions. Never ship the same UI on both with only color adjustments.

2026 Update — What changed since 2024

iOS — Liquid Glass (iOS 26, WWDC25)

The biggest visual redesign since iOS 7, applied across iOS 26 / iPadOS 26 / macOS Tahoe / watchOS / tvOS 26.

• Liquid Glass material: translucent, refractive, real-time-rendered surfaces for controls, navigation, widgets, icons.
• Dynamic shrinking tab bar: tab bar shrinks during scroll and expands when scrolling stops. Plan for this in tab-heavy designs.
• Icons require 4 variants: light / dark / tinted / clear. Use Apple's Icon Composer.
• Lock-screen content can dynamically tuck behind subjects (depth illusion).
• New SwiftUI / UIKit / AppKit APIs for materials and corner radii (hardware-aware).

Port action:

• From 2026-04-28, all App Store Connect uploads must be built with Xcode 26 + iOS 26 SDK — Liquid Glass is applied by default to native UI components when built with the iOS 26 SDK regardless of the deployment target. Verify navigation bars / tab bars / toolbars / sheets visually on iOS 26 and legacy deployment targets.
• If targeting iOS 26 → Liquid Glass adoption is the default. Document any deviation explicitly.
• If targeting iOS 17/18 → still build with the iOS 26 SDK; design must work visually on iOS 26 devices (legible at scale; no broken assumptions about translucency).
• WWDC 2026 runs 2026-06-08 to 2026-06-12; iOS 27 announcement may shift the recommended target during P2/P3 — revisit the UX adaptation plan after the conference.

iOS — iOS 18 / iOS 26 surfaces to plan around

• Control Center API (ControlWidgetToggle, AppIntentControlValueProvider) — apps can add toggles to Control Center, Lock Screen, and Action Button. New native capability beyond the "Push / Biometrics / Camera" set.
• Live Activities + Dynamic Island — ActivityKit allows up to 8h active + 4h stale. Payload ~4KB. APNs apns-priority 5 for normal updates. Advertising / marketing copy is forbidden by Apple.
• App Intents + Apple Intelligence (iOS 18+, expanding through 26) — surface domain operations to Spotlight / Siri / Action Button. 12 domains (Books, Camera, Spreadsheets, etc.). Use opensAppWhenRun = false for "answer without opening the app" UX.
• Foundation Models framework (on-device LLM) — built-in ~3B quantized model + Private Cloud Compute fallback. Web→Native uplift opportunity for AI features.

Android — Material 3 Expressive (Google I/O 2025)

Announced at Google I/O 2025 as the new design language. Rolled out to Pixel devices via Android 16 QPR1 (2025-09) with refreshes to notifications, Quick Settings, lock screen, and launcher. androidx.compose.material3:material3:1.4.0 shipped stable on 2025-09-24 (promoting a set of previously experimental APIs); the fully Expressive component set is currently in 1.5.0-alpha as of 2026-05. Backed by 46 user studies / 18,000 participants.

Five core pillars: Color · Shape · Size · Motion · Containment.

New / updated components:

• LoadingIndicator / ContainedLoadingIndicator — replaces indeterminate CircularProgressIndicator for sub-5s waits; loops through 7 morphing shapes.
• PullToRefreshBox — official Material 3 component (replaces ad-hoc implementations).
• DockedToolbar / FloatingToolbar — BottomAppBar is deprecated. FloatingToolbar supports horizontal/vertical with FAB combinations.
• Carousel — official component for image/video collections.
• Shape Library — 35 new shapes; shape morphing; variable fonts.
• Spring-based motion engine — physics-based for natural feedback.

Android — Material You / Dynamic Color

• Compose BOM 2026.05.00 is the current stable BOM (maps to Compose 1.11.1); 2025.12.00 and earlier are still supported. Use the BOM rather than pinning individual Compose libraries.
• Dynamic Color: API 31+. Use dynamicLightColorScheme() / dynamicDarkColorScheme() with feature detection. Hard-coded colors are forbidden — use MaterialTheme.colorScheme.surface and friends.
• Pausable Composition (Compose December '25 / BOM 2025.12.00) brings scroll performance on par with classic Views — adopt when porting long lists from web.

Android — Edge-to-Edge enforcement (API 36)

• R.attr#windowOptOutEdgeToEdgeEnforcement is deprecated and disabled at targetSdk 36.
• Design every screen with Modifier.windowInsetsPadding() / WindowInsets.systemBars from day 1.
• This is a hard policy gate: targetSdk 36 apps that don't handle insets correctly will look broken.

Android — Predictive Back (default ON, API 36)

• targetSdk 36: predictive back gesture animations are default ON for back-to-home, cross-task, cross-activity.
• onBackPressed() is no longer dispatched. Use OnBackPressedDispatcher (Activity) or BackHandler (Compose).
• Plan back-stack semantics carefully when porting from web's history-stack model.

Android — Adaptive forced resizability (sw ≥ 600dp, API 36)

• For displays with smallest width ≥ 600dp at targetSdk 36, the following Manifest / runtime constraints are ignored:
  • screenOrientation, resizableActivity, minAspectRatio, maxAspectRatio
  • setRequestedOrientation() / getRequestedOrientation()
• Exceptions: games (appCategory="game"), screens < sw 600dp, user override.
• Temporary opt-out: PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY (expires API 37).
• Window Size Class: compact / medium / expanded / large / extra-large (new). Use Compose Adaptive Layouts 1.2+ for foldable / trifold support.

Android — Glance for App Widgets

• Jetpack Glance (Compose-runtime-based) is the recommended path for new widgets. RemoteViews directly is legacy.
• Battery-friendly, integrates with PreferencesDataStore.

Cross-platform UX shifts

• Photo Picker / Photo Picker Everywhere — On Android, use Photo Picker by default. Holding READ_MEDIA_IMAGES for non-essential reasons is out of policy since 2025-05-28.
• Credential Manager (Android) / Passkey (iOS) — System-managed credential UI, not custom auth screens. See data-and-auth-porting.md.
• AI feature disclosure UI — App Store 5.1.2(i) requires explicit consent UI naming the third-party AI provider before any user data leaves the device. Plan this UI flow at MVP, not post-MVP.

OS Baselines (2026 recommendation)

targetSdk (Android): 35 mandatory since 2025-08-31, expect 36 during 2026.

Navigation

Divergence to expect:

• iOS rarely uses FAB; primary action goes to toolbar.
• Android predictive back (API 34+) and gesture nav change choreography.
• iPad supports multi-column NavigationSplitView; Android tablets use adaptive layouts.

Gestures

Don't translate web hover states 1:1. Mobile has no hover. Use long-press for "more info" patterns and tap for primary action.

Typography & Type Scale

Rule: Use the platform's semantic type scale. Don't port web's "16px / 14px / 12px" stack literally — use Dynamic Type / fontScale so accessibility settings work.

Color, Theming, Dark Mode

Mandatory: Both platforms ship with full dark-mode support if the web product has it. Dark mode is a baseline expectation, not a feature.

Motion & Animation

Never ship motion that ignores Reduce Motion / Animator scale. Both stores penalize accessibility failures.

Iconography

Use SF Symbols on iOS by default. Custom icons require justification.

Lists, Cards, Empty States

Forms & Input

Critical: Both platforms have password-manager integration (iOS Keychain, Android Credential Manager). Web <input type="password"> patterns must use the right textContentType / Autofill hints to populate password managers.

A11y

A11y must be designed at blueprint, not retrofitted. Document accessibilityLabel / contentDescription per component in the design handoff.

OS Integration

Permissions UX

Never request permissions on app launch. Always trigger contextually with a custom rationale screen.

Errors, Loading, Empty States

Web → Native UX Patterns

OS Version Baselines (Recommended)

Document choice and excluded-user percentage from web analytics.

Output Skeleton

# Platform UX Adaptation Plan: <App Name>

## Navigation
- iOS top-level: TabView with N tabs ([list])
- Android top-level: NavigationBar with N destinations ([list])
- Modal patterns: …
- Deep-link routing: …

## Gestures
- Pull-to-refresh: ✓ on N screens
- Swipe-to-action: ✓ on M lists
- Long-press menus: …

## Type & Color
- Type scale: HIG default / Material 3 default
- Dark mode: ✓
- Dynamic Color (Android): ✓ / ✗
- Custom font: …

## Motion
- Default curves: …
- Reduce Motion respect: ✓

## A11y
- VoiceOver labels: documented per component
- TalkBack labels: documented per component
- Min contrast: WCAG AA

## Permissions
- Pre-prompt rationale screens: [list]
- Permissions requested: [list with timing]

## OS baselines
- iOS NN (excludes ~X% of users)
- API NN (excludes ~Y% of users)

## Web→Native UX deltas
- [list of deliberate divergences with rationale]

This plan is consumed by Native (implementation) and Vision/Muse (design system tuning).