Getting started

GearUI Kit is a Kotlin Multiplatform library. You add one dependency to commonMain, mount one root composable, and write screens against com.gearui.*.

Requirements

	Version
Kotlin	2.1.21 (must match KuiklyUI's)
Compose Multiplatform	1.7.3
KuiklyUI	2.25.0 (compose:2.25.0-2.1.21)
Android	minSdk 21, compileSdk 34
iOS	14.0+, arm64 / simulator arm64 / x64
JS	browser, IR

The Kotlin version is not negotiable: KuiklyUI artifacts are published per Kotlin version and a mismatch fails at resolution, not at runtime.

Add the dependency

// build.gradle.kts
repositories { mavenCentral() }

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.gearui:gearui-kit:1.0.0-beta1")
        }
    }
}

Declare only the root coordinate. Gradle reads the module metadata and resolves the per-target artifact (gearui-kit-android, -js, -iosarm64, …) for whatever you are compiling. Never depend on those directly.

Working against a local checkout instead

./gradlew :gearui-kit:publishToMavenLocal   # inside the gearui-kit repo

then add mavenLocal() before mavenCentral() in your repositories. Or use a composite build:

// settings.gradle.kts
includeBuild("../gearui-kit") {
    dependencySubstitution {
        substitute(module("com.gearui:gearui-kit")).using(project(":gearui-kit"))
    }
}

Mount the root

Everything in GearUI Kit assumes it is inside App. It provides the theme, the language environment, the overlay host (dialogs, sheets, toasts) and the stabilised safe-area pipeline.

The simplest way is to extend View, which wraps App for you:

import com.gearui.View
import com.tencent.kuikly.core.annotations.Page

@Page("MainPage")
class MainPage : View() {
    @Composable
    override fun Content() {
        MainPageContent()
    }
}

If you need to control the root yourself — for example to drive theme and language from your own settings — call App directly and set autoWrapApp = false on the View:

App(
    themeMode = ThemeMode.System,
    isSystemDark = isSystemDark,          // supplied by your platform layer
    languageTag = "zh-Hans",              // the ONLY place language is set
) {
    MainPageContent()
}

There must be exactly one App in the tree. Nesting a second one overrides runtime flags for everything beneath it.

Write a screen

@Composable
fun MainPageContent() {
    val colors = Theme.colors
    val strings = I18n.strings

    PageScaffold {
        NavBar(title = strings.buttonConfirm)
        Column(Modifier.padding(Spacing.lg)) {
            Button(
                text = strings.buttonConfirm,
                theme = ButtonTheme.PRIMARY,
                onClick = { /* … */ },
            )
        }
    }
}

Three habits that the library's own CI enforces on itself and that you should carry into your app:

1. val colors = Theme.colors first — colours are read from the theme, never written as Color(0x…).
2. Sizes come from scales — Spacing.lg, Theme.shapes.md, IconSizes.Default.md, Elevation.raised. Not 16.dp.
3. PageScaffold is the page root — it is what consumes safe area. Do not read safeAreaInsets by hand.

Run the sample

The repository ships a sample with a demo page for every component:

git clone https://github.com/gearui/gearui-kit
cd gearui-kit
./gradlew :sample:installDebug                    # Android
./gradlew :sample:jsApp:jsBrowserDevelopmentRun   # Web → http://localhost:8081/
open sample/iosApp/GearUISample.xcworkspace       # iOS (after ./gradlew :sample:syncFramework && pod install)