How Kuikly Simplifies Foldable Screen Adaptation Across Android, iOS, and HarmonyOS

Kuikly is Tencent's open-source, high-performance cross-platform framework built on Kotlin Multiplatform. It covers six platforms — Android, iOS, HarmonyOS, H5, WeChat Mini Program, and macOS — and powers business apps with over 500 million daily active users. With the arrival of Apple's foldable device (referred to as "iPhone Duo" in the article), foldable-screen adaptation has become a cross-platform requirement rather than an Android/HarmonyOS-only concern.

Why Foldable Adaptation Is Hard

The article frames adaptation complexity as:

Adaptation Complexity = Platform Count × Window Forms × Interaction Modes

Each new platform, window state (folded, unfolded, split-screen, free-form window), and interaction mode (touch, back gesture, keyboard) multiplies the implementation and verification effort. Traditional per-platform adaptation leads to duplicated layout breakpoints, state restoration logic, navigation handling, and animation code that are difficult to keep consistent.

Kuikly's Layered Reuse Strategy

From Per-Platform to Multi-Platform Reuse

Kuikly forwards native container size changes to a shared Kotlin layer. Developers define a single set of responsive adaptation rules (breakpoints, column strategies, state preservation) in shared code. Platform-specific code only handles necessary container integration and system capabilities, reducing duplicate development and long-term maintenance.

Unified Experience Rules

Kuikly abstracts five consistent models across platforms:

Unified Size Model: Same container dimensions and breakpoint semantics on every platform.

Unified State Model: Selected items, input content, and page hierarchy are platform-agnostic.

Unified Layout Strategy: Single-column, dual-column, and multi-column layouts follow identical switching rules.

Unified Navigation Semantics: Business logic expresses "navigate forward," "go back," "select"; the framework maps these to full-page transitions on small screens or in-pane content swaps on large screens.

Unified Interaction Principles: Animation pacing, back-gesture priority, and gesture scope are co-designed in the shared layer.

From Page Reuse to Multi-Form Capability Reuse

The adaptation pipeline — sense window change → shared state decides page form → layout, routing, and interaction respond together — is reusable for tablets, split-screen, free-form windows, and future large-screen form factors. New device shapes only require adjusting breakpoints and strategies, not rebuilding the adaptation system.

Implementation Details

3.1 Routing: Unifying Full-Page Navigation and In-Pane Switching

On small screens, navigation relies on system containers (Android Activity, iOS ViewController). On large screens, list and detail coexist, so "open detail" becomes an in-pane content swap. Kuikly establishes a unified navigation state inside adaptive pages/components. Business code still calls "go to detail" or "go back"; the component maps these to page pushes or pane replacements based on current window form. Routing state is driven by reactive data, managing content hierarchy, lifecycle, and state restoration uniformly.

3.2 Animations: From System Transitions to Local Transitions

Small-screen page switches can reuse system transition animations. Large-screen content swaps occur inside a pane, where system transitions don't apply. Kuikly binds animations to the adaptive navigation state: small screens keep platform-standard enter/exit transitions; large screens run targeted content transitions inside the destination pane. When switching from single-column to dual-column, list width, detail position, and navigation elements are choreographed simultaneously to preserve visual continuity.

3.3 Gestures: Unified Back Strategy and Event Handling

Small-screen second-level pages respond to system back gesture; custom back policies are supported.

Large screens prioritize popping the current pane's internal stack; only when the pane stack is empty does the outer page handle the gesture.

Content panes at each level actively consume their corresponding gestures, preventing tap/drag/scroll events from leaking to underlying pages.

Linking the back stack to gesture scope lets small and large screens share navigation semantics while respecting each form's interaction structure.

3.4 Platform Adaptation: Unified DX Without Sacrificing Native Feel

Kuikly's native rendering architecture converges platform differences inside the framework. The same foldable-screen page shares layout, routing, and interaction logic while naturally adopting platform-specific traits like iOS Liquid Glass. Physical constraints — status bars, navigation bars, notches, punch-holes, rounded corners — are abstracted into a unified safe-area inset set that updates with size changes. Developers lay out once; the framework handles avoidance on every platform.

Sample Code and Resources

The adaptive screen-settings page and multi-form adaptation samples shown in the article are available at:

https://github.com/Tencent-TDS/KuiklyUI/tree/feat/kuikly_fold

Sample components will be packaged for direct reuse. The main Kuikly repository is at https://github.com/Tencent-TDS/KuiklyUI and documentation at https://kuikly.tds.qq.com/Introduction/arch.html.

Conclusion

Device form-factor evolution shifts cross-platform frameworks from "run the same page on multiple OSes" to "continuously adapt the same app to changing space and input modes." Kuikly's foldable adaptation demonstrates that a single business state can render as a single page on small screens and expand to multi-column layouts on large screens; the same page logic reorganizes in response to window changes; and core code remains reusable across platforms. As hardware and interaction paradigms advance, cross-platform infrastructure becomes essential for apps to quickly leverage hardware innovation. Kuikly will continue enhancing foldable, large-screen, and multi-window capabilities to help developers build more efficient, natural experiences in a shifting device ecosystem.