Kuikly: One Codebase for Foldable Screen Adaptation Across Android, iOS, HarmonyOS

Introduction

At Apple's 2024 fall event, a new foldable device form factor was announced. Unlike routine hardware upgrades, foldable screens change the available space on mobile devices: devices switch between a compact small screen and an expanded large screen, requiring app interfaces to move from fixed layouts to multi-form designs that continuously respond to window changes.

Before Apple's entry, vendors like Huawei, Samsung, Honor, OPPO, vivo, and Xiaomi had already released foldable products with accelerating iteration and richer form factors. Apple's participation further expands industry coverage, making large/small screen adaptation for content browsing, mobile office, and multi-task collaboration a concern for more apps.

AI is also reshaping mobile terminal information structures: from single Q&A entry points to composite task interfaces that simultaneously carry context materials, tool calls, generated results, and human confirmation. Remote work, cloud desktops, and cross-device collaboration also need to display more information in limited space. As these scenarios evolve, mobile terminals' demand for display space will increase, and foldable/large screens may become key directions for AI super-terminals and mobile productivity devices.

Behind the trend lies a practical problem for developers: when a phone can switch between small and large screens, how should the app "unfold" along with it? Can existing pages adapt naturally? Must layout, routing, animation, and gestures be redeveloped? Do Android, iOS, and HarmonyOS each need separate adaptation?

Kuikly considered window changes and multi-form adaptation from its design inception and already possesses mature foldable screen support capabilities. Based on Kotlin Multiplatform and a shared UI system, developers can handle size response, state management, and multi-form layouts in shared Kotlin code, reusing core logic across multiple platforms.

Challenge: Foldable Adaptation Is More Than Layout

Foldable adaptation is not just about screen size changes; it pulls the entire page system:

Large refactoring effort: Home pages, main tabs, channel pages, and other entry pages generally need to reorganize navigation, content partitions, and information density; existing pages must rework layout breakpoints and test scenarios.

Complex interaction chains: When single-column becomes multi-column, routing, state restoration, animation, back navigation, and gestures all need synchronized adjustment.

Amplified multi-platform cost: If the same adaptation is implemented separately on each platform and must cover multiple window forms, development and maintenance costs grow rapidly.

Therefore, foldable adaptation must ensure tasks are not interrupted during form switches and that added space truly improves information display and operation efficiency. Achieving both goals at lower cost across multiple platforms is exactly what Kuikly aims to solve.

Kuikly's Approach: Layered Reusable Capabilities

The adaptation complexity can be expressed as:

Adaptation Complexity = Platform Count × Window Forms × Interaction Modes

Platforms form the first layer of difference; folded, unfolded, split-screen, and windowed forms form the second; touch, back gestures, and other interaction modes form the third. Any business adjustment may require re-implementation and verification across these combinations.

In traditional solutions, each added platform, form, or interaction mode creates new development and verification combinations. Kuikly does not simply flatten these differences but incrementally precipitates reusable capabilities: from per-platform adaptation to multi-platform reuse, from single-page reuse to complete experience rules covering layout, state, and interaction, and further into multi-form capabilities covering more device shapes.

2.1 From Per-Platform Adaptation to Multi-Platform Reuse

Completing foldable adaptation on a single platform is not difficult: listen to window changes, add layout breakpoints, and adjust page structure for large screens. But when the same business must cover multiple platforms, the real expense is ongoing maintenance.

The same column-splitting rules must be reimplemented in different tech stacks; the same selected state must separately handle restoration after folding/unfolding; the same navigation behavior must adapt to small-screen full-page jumps and large-screen region switches; the same transition and back strategies must be developed, tested, and aligned per platform.

As tablets, desktop windows, AI super-terminals, and more forms join, per-platform solutions often precipitate multiple similar but hard-to-share implementations. More platforms and forms mean higher costs for experience consistency and long-term evolution.

Kuikly unifies window changes from all platforms into the shared Kotlin layer. Business defines one set of responsive adaptation rules, reusable across platforms. The platform side mainly handles necessary containers and system capabilities, reducing duplicate development and subsequent alignment and maintenance costs.

2.2 Complete and Consistent Experience Rules

Whether a page adapts to foldable screens depends not only on how it is drawn but also on whether size, state, layout, and interaction can change collaboratively. The cross-platform value in foldable scenarios is not just "one codebase draws the same page" but unifying the rules that tend to repeat in foldable adaptation into the shared layer:

Unified size model: All platforms use the same container sizes and layout breakpoint semantics.

Unified state model: Selected items, input content, and page hierarchy do not depend on specific platform containers.

Unified layout strategy: Single-column, dual-column, multi-column follow the same switching rules.

Unified navigation semantics: Business only expresses enter, back, and select; different forms decide full-page jump or region switch.

Unified interaction principles: Animation rhythm, back priority, and gesture scope can be collaboratively designed in the shared layer.

Kuikly reuses not only UI code but a complete, consistent set of experience rules. Business completes adaptation once, and core logic can be reused across multiple platforms; each platform still retains native experience conforming to its own system characteristics.

2.3 From "Page Reuse" to "Multi-Form Capability Reuse"

A sustainable cross-platform large/small screen solution needs a complete chain: first perceive window changes, then let shared state make page form decisions, finally let layout, routing, and interaction respond together.

Layout breakpoints, strategies, and state management built for fold/unfold scenarios can equally serve tablets, split-screen, windowed, and future large-screen scenes. When new device forms appear, business only adjusts breakpoints and strategies on existing capabilities, without rebuilding an adaptation system.

While achieving foldable compatibility via Kuikly, teams also precipitate shareable multi-form capabilities: core experience continuously reused in the shared Kotlin layer, platform side retains necessary native enhancement space.

Kuikly's Adaptation Practice

Kuikly incorporated window size changes and multi-form adaptation into framework capabilities from the start, rather than treating foldable screens as a new platform to adapt separately. The framework passes native container size changes to the shared layer, driving responsive page refresh so the same page naturally handles folded, unfolded, split-screen, and windowed forms.

On this basis, Kuikly further solves routing, animation, and gesture issues caused by page structure changes, making multi-form switching not only display correctly but also maintain complete, continuous interaction experience.

3.1 Routing: Unifying Full-Page Jumps and Region Switches

Small-screen pages typically use Android Activity, iOS ViewController, and other system carriers for full-page jumps; on large screens, list and detail often coexist, so the original "open new page" becomes content switching within a specified region, unable to fully rely on system routing.

This brings three problems:

Small and large screens use different page carriers but must keep consistent navigation semantics.

During fold/unfold, the routing stack must migrate and restore current selection and page state.

Regions must support parameter passing while avoiding over-coupling with specific pages.

Kuikly's adaptation idea is to establish a unified navigation state inside adaptive pages or components: business still expresses "enter detail", "go back", etc.; the component maps these to small-screen page jumps or large-screen region switches based on current window form. Routing state is driven by reactive data and uniformly manages content hierarchy, lifecycle, and state restoration.

3.2 Animation: Extending from System Transitions to Local Transitions

Small-screen page switches can reuse system transition animations; large-screen content switches mostly occur in local page regions where system transitions no longer apply. Without unified handling, the same navigation operation would show completely different rhythms in two forms, even causing content flicker or instant jumps.

Therefore, Kuikly combines animation with adaptive navigation state: small screens keep platform-habitual enter/exit relations; large screens execute corresponding content transitions in target regions; when switching from single-column to dual-column, list width, detail position, and navigation elements can be synchronously orchestrated, keeping content relationships continuous during window changes.

3.3 Gestures: Unified Back Strategy and Event Handling

On small screens, each page is usually carried by an independent system container, so system back gestures directly act on the current page; on large screens, the right region may have multiple content layers, so one back must decide whether to close the whole page or only go back one level in the right region — decided by adaptive navigation.

Kuikly's handling focuses on:

Small-screen second-level pages respond to system back and allow custom back strategies.

Large screens prioritize rolling back the current region's internal hierarchy; after region stack empties, hand off to outer page.

Content regions at different levels actively consume corresponding gestures to avoid click, drag, and scroll penetrating to underlying pages.

By linking back stack with gesture scope, large and small screens share the same navigation semantics while maintaining interaction behavior fitting the current page structure.

3.4 Platform Adaptation: Unified Development Experience, Preserved Native Feel

Cross-platform development needs unified usage across platforms, but "unified" does not mean all platforms must present identical effects. If a framework only provides common capabilities all systems have, business gains code reuse but may miss the most distinctive experiences of new systems.

Kuikly relies on a native rendering architecture, converging platform differences inside the framework so developers don't have to choose between cross-platform reuse and platform experience. The same foldable page can share layout, routing, and interaction logic while naturally integrating iOS Liquid Glass and other platform features, and maintaining visual expressions conforming to each system's characteristics on other platforms.

The same difference appears in status bars: iPhone Duo's status bar uses asymmetric and side-integrated design; other vendors have notches, Dynamic Island-like solutions, and varying system bar heights — no unified standard yet. Kuikly abstracts each platform's status bar, navigation bar, notch, punch-hole, rounded corners, and other physical constraints into a unified safe distance set, updated synchronously with size changes. Developers layout once, and it correctly avoids obstacles on all platforms.

With the native rendering architecture, Kuikly will continue tracking OS, hardware form, and interaction evolution, letting businesses follow new systems, devices, and experiences at lower cost.

Sample Code and Resources

The adaptive settings page and multi-form app adaptation sample code mentioned above can be viewed at: GitHub - Tencent-TDS/KuiklyUI at feat/kuikly_fold Sample components will be organized and released as components for direct use; welcome to star the Kuikly repository for latest updates.

Conclusion and Outlook

Device form evolution poses a new proposition for cross-platform development.

Previously, cross-platform frameworks mainly solved "how to run the same page on multiple systems"; as foldable screens, tablets, and desktop windows keep evolving, they must also solve "how the same app continuously adapts to changing space and input methods".

Single-platform adaptation solves one platform's current problem, while cross-platform solutions focus on how to precipitate one adaptation into reusable, evolvable foundational capabilities. A cross-platform framework's value no longer depends only on how many platform differences it flattens, but more on whether it helps businesses release the experience value of new devices and systems in time while controlling engineering costs.

Kuikly's foldable adaptation practice validates this idea: the same business state presents as a single page on small screens and expands to multi-column on large screens; the same page logic reorganizes in response to window changes; core code can be continuously reused across multiple platforms.

In the future, as device forms and interaction methods continue evolving, cross-platform may become not just an engineering choice for R&D efficiency but also critical infrastructure for apps to quickly follow hardware innovation. Kuikly will keep improving foldable, large-screen, and multi-window capabilities, helping developers create more efficient, more natural app experiences in the ever-changing device ecosystem.

The screen folds, the experience doesn't.