Kmp Development

Kotlin Multiplatform Development Standards

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Kotlin Multiplatform shared module development standards for sharing business logic across Android and iOS while keeping native UI. Covers project structure (shared/composeApp/iosApp), source sets, targets, expect/actual, DI (Koin)...

Evidence Produced

References

• Use the references/ directory for deep detail after reading the core workflow below.
• references/kmp-compose-multiplatform.md for shared Compose UI across Android, iOS, Desktop, and Web targets.
• references/kmp-tdd.md for shared-module Red-Green-Refactor, common tests, and expect/actual test strategy.
• For iOS targets in 2026+ Apple toolchains, load ../../ios/ios-development/references/apple-platform-compatibility-wwdc26.md and keep SwiftUI-native UI, Xcode 27, Swift 6.4, and availability gates in the iosApp/ module.

Strategy: Shared Logic, Native UI

KMP shares business logic (domain, data, networking) across platforms. Each platform keeps its native UI framework: Jetpack Compose for Android, SwiftUI for iOS. This preserves the best user experience on each platform while eliminating business logic duplication.

Module-to-Skill Mapping

Project Structure

Every KMP project has three modules:

project-root/
  shared/                    # Shared Kotlin module (this skill governs)
    src/
      commonMain/            # Shared code (domain, data, use cases)
        kotlin/
        resources/
      androidMain/           # Android-specific implementations
        kotlin/
        AndroidManifest.xml
      iosMain/               # iOS-specific implementations
        kotlin/
      commonTest/            # Shared tests
      androidUnitTest/       # Android-specific tests
      iosTest/               # iOS-specific tests
    build.gradle.kts         # KMP Gradle config
  composeApp/                # Android app (follow android-development skill)
    src/main/
    build.gradle.kts
  iosApp/                    # iOS Xcode project (follow ios-development skill)
    iosApp/
    iosApp.xcodeproj
  build.gradle.kts           # Root build file
  gradle/libs.versions.toml  # Version catalog

Additional Guidance

Decision Rules

Capability Contract And Degraded Mode

Read and search all target source sets before moving code. Edits and builds require authority. Without both Android and iOS toolchains, return the target-specific checks still outstanding and do not claim parity. If either target toolchain is unavailable, mark cross-platform parity unverified.

Domain Anti-Patterns

• Moving UI wholesale into shared code by default. Fix: share stable logic and keep native experiences intentional.
• Spreading expect/actual across domain types. Fix: inject one narrow platform service.
• Choosing dependencies from Android support alone. Fix: verify every declared target.
• Catching platform errors as generic strings. Fix: map them into a shared typed error model.
• Declaring parity after one target builds. Fix: run shared and platform tests on both targets.

Extended guidance for kmp-development was moved to references/skill-deep-dive.md to keep this entrypoint compact and fast to load.

Use that deep dive for:

• Technology Stack
• Source Sets and Targets
• Architecture: Clean Architecture in Shared Module
• Expect/Actual Pattern
• Dependency Injection with Koin
• Networking with Ktor
• Database with SQLDelight
• Modularization
• Native Library Integration
• Tooling
• Mandatory Rules
• Anti-Patterns

Inputs

Outputs

• Produce KMP architecture or code with shared/native separation, tests, and platform integration evidence.

Degraded mode

Fallback without both platform toolchains: validate shared code and mark native integration unverified.

Capability contract

Builds and tests follow task scope; signing, store release, backend mutation, and destructive device actions require explicit authority.