Claude Skill

compose-multiplatform

Compose Multiplatform / KMP patterns - expect/actual composables, platform-specific code, density and font handling cross-target, iOS/Android/Desktop interop.

LLM Mart · 0 points · 5 views 0 listing impressions 0 install-command copies
Download athevon-genjutsu-skills__jutsu_compose-multiplatform-a22540b.zip · 15 KB

Install

skills CLI npx skills add https://github.com/AThevon/genjutsu/tree/main/skills/_jutsu/compose-multiplatform
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install athevon-genjutsu@llmmart
Git git clone https://github.com/AThevon/genjutsu.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole athevon/genjutsu collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Version-sensitive. Every API name, SDK gate and browser-support claim below was verified on 2026-09-08 against primary sources. What against, and when, is in _jutsu/VERSIONS.md. If that date is old, re-verify before acting on a version number.

Compose Multiplatform

Compose Multiplatform (CMP) and Kotlin Multiplatform (KMP) patterns for cross-platform UI. Loaded for projects with org.jetbrains.compose plugin. Foundation: ../compose-motion/SKILL.md for animation API; this file covers what's specific to writing one Compose codebase for Android + iOS + Desktop + Web.


KMP vs CMP - quick clarification

KMP (Kotlin Multiplatform) is the language and build infrastructure: shared Kotlin code compiled to JVM, Native (iOS, macOS, Linux, Windows), and Wasm. CMP (Compose Multiplatform) is the UI framework on top of KMP, built by JetBrains as a port of Jetpack Compose. You write a single Compose codebase in commonMain that runs on Android, iOS, Desktop (JVM), and Web (Wasm). Platform-specific code lives in androidMain, iosMain, desktopMain, wasmJsMain and is wired in via expect/actual declarations.


Project structure

composeApp/
├── src/
│   ├── commonMain/        ← shared Compose code (most of the app)
│   │   └── kotlin/
│   ├── androidMain/       ← Android-specific (uses Activity, Context)
│   ├── iosMain/           ← iOS-specific (uses UIKit/UIView interop)
│   ├── desktopMain/       ← JVM desktop (uses java.awt/swing if needed)
│   └── wasmJsMain/        ← Wasm web target
├── build.gradle.kts
iosApp/                    ← Xcode project consuming the generated framework
androidApp/                ← Android Application module (often merged into composeApp)

The commonMain folder should hold 80-95% of your code in a well-architected CMP project. If iosMain or androidMain start growing past a few hundred lines, you're probably leaking platform concerns into UI logic that could stay shared.


expect/actual pattern

The KMP escape hatch when you genuinely need different implementations per target. Declare the contract once in commonMain, implement it once per target.

// commonMain
expect fun openShareSheet(text: String)

// androidMain
actual fun openShareSheet(text: String) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        type = "text/plain"
        putExtra(Intent.EXTRA_TEXT, text)
    }
    context.startActivity(Intent.createChooser(intent, null))
}

// iosMain
actual fun openShareSheet(text: String) {
    val activityVC = UIActivityViewController(
        activityItems = listOf(text),
        applicationActivities = null
    )
    UIApplication.sharedApplication.keyWindow
        ?.rootViewController
        ?.presentViewController(activityVC, true, null)
}

expect/actual works for top-level functions, classes, type aliases, and properties. The signature in actual must match exactly, including modifiers and default values.


expect/actual for composables

Composables follow the same rules. Useful when a feature needs a platform-specific Compose API (Android RuntimeShader, iOS UIKitView, Desktop SwingPanel).

// commonMain
@Composable
expect fun PlatformBlur(modifier: Modifier = Modifier, content: @Composable () -> Unit)

// androidMain (uses RuntimeShader on Android 13+)
@Composable
actual fun PlatformBlur(modifier: Modifier, content: @Composable () -> Unit) {
    Box(modifier.graphicsLayer { renderEffect = blurEffect }) { content() }
}

// iosMain (uses UIVisualEffectView via UIKitView)
@Composable
actual fun PlatformBlur(modifier: Modifier, content: @Composable () -> Unit) {
    Box(modifier) {
        UIKitView(
            factory = {
                UIVisualEffectView(
                    effect = UIBlurEffect.effectWithStyle(
                        UIBlurEffectStyle.UIBlurEffectStyleSystemMaterial
                    )
                )
            },
            modifier = Modifier.matchParentSize()
        )
        content()
    }
}

Rule: expect composables should be the exception, not the rule. Most "platform feel" differences can be tuned via tokens (colors, corner radii, spring stiffness) in commonMain, not via separate code paths.


LocalDensity cross-platform

On Android, LocalDensity.current.density reflects the device DPI bucket (1.0, 1.5, 2.0, 3.0...). On iOS, density is computed from UIScreen.scale (typically 2.0 or 3.0 on Retina). On Desktop, density depends on the screen scaling factor (1.0 by default; 2.0 on Retina-class displays; user-configurable on Windows). On Wasm, density follows window.devicePixelRatio.

Don't hardcode Dp to pixel ratios; trust Dp and LocalDensity to handle conversion. If you need an exact pixel value (e.g., for a Canvas draw operation), do the conversion explicitly:

val density = LocalDensity.current
val pxValue = with(density) { 16.dp.toPx() }

Avoid reading density inside hot loops; cache the conversion.


LocalConfiguration and platform-aware UI

LocalConfiguration.current is Android-only and lives in androidMain. For CMP, prefer the cross-platform alternatives:

  • LocalWindowInfo.current.containerSize - the window/screen size as IntSize, available in commonMain.
  • LocalDensity.current - density, available in commonMain.
  • LocalLayoutDirection.current - LTR / RTL.
  • BoxWithConstraints { ... } - read maxWidth / maxHeight directly inside layout.

If you need real device characteristics (orientation, idiom, model), wrap the access in expect/actual and pass a typed object like PlatformInfo to the common layer.


Fonts cross-platform via Compose Resources

org.jetbrains.compose.resources is the shared resources plugin. Drop fonts in commonMain/composeResources/font/, and the Gradle plugin generates a typed Res accessor.

composeApp/src/commonMain/composeResources/
├── font/
│   ├── Inter-Regular.ttf
│   └── Inter-Bold.ttf
├── drawable/
│   └── logo.xml            ← Android XML vector. SVG works on every target EXCEPT Android
└── values/
    ├── strings.xml          ← default locale
└── values-fr/
    └── strings.xml          ← French overrides (qualifier goes on the DIRECTORY)

Usage in commonMain:

import myproject.composeapp.generated.resources.Inter_Regular
import myproject.composeapp.generated.resources.Inter_Bold
import myproject.composeapp.generated.resources.Res

val InterFamily = FontFamily(
    Font(Res.font.Inter_Regular, FontWeight.Normal),
    Font(Res.font.Inter_Bold, FontWeight.Bold),
)

Text("Hello", fontFamily = InterFamily)

Same pattern for Res.drawable.logo (image) and Res.string.app_name (localized string via stringResource(...)). Raw files are the exception: there is no generated Res.file.* accessor - you pass a path string to the suspend function Res.readBytes(path), e.g. val bytes = Res.readBytes("files/config.json"), for anything under composeResources/files/.


iOS interop with SwiftUI

CMP produces a UIViewController you can drop into a SwiftUI app. KMP generates a top-level Kotlin function (commonly named MainViewController() or ComposeUIViewController { ... }) that returns a UIViewController. Wrap it with UIViewControllerRepresentable.

// iosMain/kotlin/main.ios.kt
fun MainViewController(): UIViewController = ComposeUIViewController {
    AppContent()  // commonMain composable
}
// iOS app target
import SwiftUI
import ComposeApp  // KMP-generated framework

struct ComposeContent: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        Main_iosKt.MainViewController()
    }
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
}

struct ContentView: View {
    var body: some View { ComposeContent().ignoresSafeArea() }
}

The Kotlin function name gets mangled to Main_iosKt.MainViewController() because the file is main.ios.kt. Check the generated framework headers if the symbol name surprises you.


Android entry point

No interop ceremony on Android. The Activity hosts the common composable directly via setContent { ... }.

// androidApp/src/main/kotlin/MainActivity.kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            AppContent()  // commonMain composable
        }
    }
}

If you need to pass Context or Activity into commonMain, expose it via a DI graph or an expect class PlatformContext in commonMain with actual class PlatformContext(val context: Context) in androidMain.


Embedding SwiftUI/UIKit inside a Compose iOS view (the reverse direction)

Use UIKitView for a UIView factory or UIKitViewController for a UIViewController factory.

// iosMain
UIKitView(
    factory = {
        UISwitch().apply {
            addTarget(target, action = NSSelectorFromString("onToggle:"), forControlEvents = UIControlEventValueChanged)
        }
    },
    modifier = Modifier.size(48.dp, 32.dp)
)

For SwiftUI views: wrap them in a UIHostingController exposed via a Swift @objc bridge function, then call from Kotlin via the generated headers (cinterop). See references/cmp-interop.md for the full pattern.


Animation cross-platform

All animation APIs (animate*AsState, AnimatedVisibility, updateTransition, SharedTransitionLayout) work identically across targets in CMP 1.7+. Spring tuning written in commonMain produces the same physics on Android and iOS. Gestures (Modifier.draggable, Modifier.pointerInput) work cross-platform with the same API surface.

The animation primer lives in ../compose-motion/SKILL.md. Cross-platform deltas to keep in mind:

  • iOS first-frame is slower (Skia bootstrap); a 200ms enter animation feels tighter on Android, slightly delayed on iOS cold start.
  • Wasm motion can stutter on first frame (JIT warmup); pre-warm critical paths or hide motion until interactive.

What does NOT work (gotchas)

  • Drawer state on iOS: native ModalNavigationDrawer swipe-to-open from the leading edge conflicts with iOS's back-swipe gesture. Use a button trigger or move the swipe area inward 30dp+.
  • LayoutDirection.Rtl quirks: Android handles RTL natively, iOS Compose had bugs in 1.6 (text alignment, padding inversions). Improved in 1.7+ but verify with real Arabic/Hebrew strings.
  • Soft keyboard handling: imePadding() / WindowInsets.ime work on Android out of the box and are implemented on iOS too. There is no IOSKeyboardEventListener type in CMP - the real knob is ComposeUIViewControllerConfiguration.onFocusBehavior, which defaults to OnFocusBehavior.FocusableAboveKeyboard (CMP pans the whole Compose view up so the focused field clears the keyboard). If you want to drive the layout yourself with imePadding() / WindowInsets.ime, turn the automatic pan off:
    // iosMain - imports: androidx.compose.ui.window.ComposeUIViewController,
    //                    androidx.compose.ui.uikit.OnFocusBehavior
    fun MainViewController(): UIViewController = ComposeUIViewController(
        configure = { onFocusBehavior = OnFocusBehavior.DoNothing }
    ) {
        AppContent()
    }
    
    Leaving the default on and applying imePadding() is the classic double-adjustment bug; same if the SwiftUI parent hosting the controller also adjusts for the keyboard.
  • Color.parseHex(...) does not exist in Compose. Use Color(0xFFRRGGBB) or write a tiny extension.
  • System fonts on iOS via Compose: do not fallback to FontFamily.SansSerif and expect SF Pro. Compose on iOS ships its own font fallback chain. Either bundle SF Pro via Compose Resources (license-permitting) or use UIKitView to drop a native UILabel for system-font text.
  • Animations on Web (Wasm): heavier startup, occasional first-frame stutter; profile with browser devtools and lazy-load heavy animation graphs.
  • java.util.UUID, java.io.File and other JVM-only APIs are forbidden in commonMain if you ship to iOS or Wasm. Use kotlinx.uuid, kotlinx-io, or the okio multiplatform port.

CMP version notes

  • Current stable is Compose Multiplatform 1.12.2 (released 15 Oct 2026; 1.12.0 shipped 25 Aug 2026); the previous line was 1.11 (1.11.1, 2 Jun 2026) and 1.13 is in beta. Treat 1.7 as the historical floor for SharedTransitionLayout cross-platform, iOS keyboard handling and LocalLifecycleOwner on iOS, not as the version to target.
  • Since 1.7, iOS interop lives in androidx.compose.ui.viewinterop (UIKitView, UIKitViewController, UIKitInteropProperties); the old androidx.compose.ui.interop.UIKitView overloads with interactive: / accessibilityEnabled: parameters are @Deprecated.
  • 1.10 added UIKitInteropProperties(placedAsOverlay = true) so an interop view can be composited above Compose content, plus intrinsic-size (sizeThatFits) support for wrapping SwiftUI views in a UIHostingController.
  • Kotlin 2.x with the K2 compiler; pair the latest CMP with the latest Kotlin (2.2.20+ for iOS/web targets).
  • Some Material 3 components have platform-specific look (e.g., Switch on iOS auto-renders with iOS-style proportions; DatePicker stays Material across all targets).
  • compose-multiplatform-resources plugin is the standard for assets; the older moko-resources is no longer recommended for new projects.

Performance considerations

  • iOS first-frame is slower than Android (Skia bootstrapping ~150-300ms cold). Keep your splash visible until the first composition emits, or pre-warm with a transparent root composable.
  • Wasm bundle size: aim for <2MB compressed. Tree-shake heavy deps, lazy-load secondary screens via kotlinx.coroutines deferred composition, and inspect the .wasm output in wasmJsBrowserDistribution.
  • Desktop: cold start is fast on JVM; AOT compilation via Kotlin/Native is overkill for desktop unless you need a single-file binary.
  • Android: same baseline as Jetpack Compose - profile with the Compose compiler stability metrics and Layout Inspector recomposition counts.

Anti-Patterns

BAD GOOD Why
Reflection trick or System.getProperty("os.name") to detect platform inside commonMain expect/actual with a typed Platform object Reflection breaks on Wasm/Native; expect/actual is the contract the compiler enforces
Assuming Android Context is reachable in commonMain Inject a typed dependency via expect class PlatformContext or a DI scope Context does not exist on iOS/Desktop/Wasm; the code will not compile for those targets
Hardcoding Material colors that look great on Android but jarring on iOS Define a commonMain design system, then optionally adjust 2-3 tokens via actual Cross-platform consistency is good, but iOS users notice when a Material blue feels alien on iPhone
LaunchedEffect(Unit) { while(true) { delay(16); ... } } in commonMain rememberInfiniteTransition() or scope to lifecycle events Tight coroutine loops drain battery on iOS; infinite transitions pause when offscreen

Quick Reference: Loading Sub-skills

Need Load
iOS / Android interop deep-dive references/cmp-interop.md
Per-platform behavior catalog references/cmp-platform-quirks.md
Animation API ../compose-motion/SKILL.md
Advanced graphics (M3 Expressive, AGSL on Android only) ../compose-graphics/SKILL.md
iOS-side native interop with SwiftUI ../swiftui-motion/SKILL.md (when target is iOS and SwiftUI native blend wanted)
Mobile UX context ../mobile-principles/SKILL.md
Desktop UX context ../desktop-principles/SKILL.md
Foundation ../motion-principles/SKILL.md

Sources

Files (genjutsu)
  • references
    • cmp-interop.md 9.1 KB
      Loading…
    • cmp-platform-quirks.md 10.3 KB
      Loading…
  • SKILL.md 16.4 KB
    ---
    name: compose-multiplatform
    description: "Compose Multiplatform / KMP patterns - expect/actual composables, platform-specific code, density and font handling cross-target, iOS/Android/Desktop interop."
    metadata:
      internal: true
    ---
    
    > **Version-sensitive.** Every API name, SDK gate and browser-support claim below was
    > verified on **2026-09-08** against primary sources. What against, and when, is in
    > `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number.
    
    # Compose Multiplatform
    
    > Compose Multiplatform (CMP) and Kotlin Multiplatform (KMP) patterns for cross-platform UI.
    > Loaded for projects with `org.jetbrains.compose` plugin.
    > Foundation: `../compose-motion/SKILL.md` for animation API; this file covers what's specific to writing one Compose codebase for Android + iOS + Desktop + Web.
    
    ---
    
    ## KMP vs CMP - quick clarification
    
    **KMP** (Kotlin Multiplatform) is the language and build infrastructure: shared Kotlin code compiled to JVM, Native (iOS, macOS, Linux, Windows), and Wasm. **CMP** (Compose Multiplatform) is the UI framework on top of KMP, built by JetBrains as a port of Jetpack Compose. You write a single Compose codebase in `commonMain` that runs on Android, iOS, Desktop (JVM), and Web (Wasm). Platform-specific code lives in `androidMain`, `iosMain`, `desktopMain`, `wasmJsMain` and is wired in via `expect`/`actual` declarations.
    
    ---
    
    ## Project structure
    
    ```
    composeApp/
    ├── src/
    │   ├── commonMain/        ← shared Compose code (most of the app)
    │   │   └── kotlin/
    │   ├── androidMain/       ← Android-specific (uses Activity, Context)
    │   ├── iosMain/           ← iOS-specific (uses UIKit/UIView interop)
    │   ├── desktopMain/       ← JVM desktop (uses java.awt/swing if needed)
    │   └── wasmJsMain/        ← Wasm web target
    ├── build.gradle.kts
    iosApp/                    ← Xcode project consuming the generated framework
    androidApp/                ← Android Application module (often merged into composeApp)
    ```
    
    The `commonMain` folder should hold 80-95% of your code in a well-architected CMP project. If `iosMain` or `androidMain` start growing past a few hundred lines, you're probably leaking platform concerns into UI logic that could stay shared.
    
    ---
    
    ## `expect`/`actual` pattern
    
    The KMP escape hatch when you genuinely need different implementations per target. Declare the contract once in `commonMain`, implement it once per target.
    
    ```kotlin
    // commonMain
    expect fun openShareSheet(text: String)
    
    // androidMain
    actual fun openShareSheet(text: String) {
        val intent = Intent(Intent.ACTION_SEND).apply {
            type = "text/plain"
            putExtra(Intent.EXTRA_TEXT, text)
        }
        context.startActivity(Intent.createChooser(intent, null))
    }
    
    // iosMain
    actual fun openShareSheet(text: String) {
        val activityVC = UIActivityViewController(
            activityItems = listOf(text),
            applicationActivities = null
        )
        UIApplication.sharedApplication.keyWindow
            ?.rootViewController
            ?.presentViewController(activityVC, true, null)
    }
    ```
    
    `expect`/`actual` works for top-level functions, classes, type aliases, and properties. The signature in `actual` must match exactly, including modifiers and default values.
    
    ---
    
    ## `expect`/`actual` for composables
    
    Composables follow the same rules. Useful when a feature needs a platform-specific Compose API (Android `RuntimeShader`, iOS `UIKitView`, Desktop `SwingPanel`).
    
    ```kotlin
    // commonMain
    @Composable
    expect fun PlatformBlur(modifier: Modifier = Modifier, content: @Composable () -> Unit)
    
    // androidMain (uses RuntimeShader on Android 13+)
    @Composable
    actual fun PlatformBlur(modifier: Modifier, content: @Composable () -> Unit) {
        Box(modifier.graphicsLayer { renderEffect = blurEffect }) { content() }
    }
    
    // iosMain (uses UIVisualEffectView via UIKitView)
    @Composable
    actual fun PlatformBlur(modifier: Modifier, content: @Composable () -> Unit) {
        Box(modifier) {
            UIKitView(
                factory = {
                    UIVisualEffectView(
                        effect = UIBlurEffect.effectWithStyle(
                            UIBlurEffectStyle.UIBlurEffectStyleSystemMaterial
                        )
                    )
                },
                modifier = Modifier.matchParentSize()
            )
            content()
        }
    }
    ```
    
    Rule: `expect` composables should be the exception, not the rule. Most "platform feel" differences can be tuned via tokens (colors, corner radii, spring stiffness) in `commonMain`, not via separate code paths.
    
    ---
    
    ## `LocalDensity` cross-platform
    
    On Android, `LocalDensity.current.density` reflects the device DPI bucket (1.0, 1.5, 2.0, 3.0...). On iOS, density is computed from `UIScreen.scale` (typically 2.0 or 3.0 on Retina). On Desktop, density depends on the screen scaling factor (1.0 by default; 2.0 on Retina-class displays; user-configurable on Windows). On Wasm, density follows `window.devicePixelRatio`.
    
    Don't hardcode `Dp` to pixel ratios; trust `Dp` and `LocalDensity` to handle conversion. If you need an exact pixel value (e.g., for a `Canvas` draw operation), do the conversion explicitly:
    
    ```kotlin
    val density = LocalDensity.current
    val pxValue = with(density) { 16.dp.toPx() }
    ```
    
    Avoid reading `density` inside hot loops; cache the conversion.
    
    ---
    
    ## `LocalConfiguration` and platform-aware UI
    
    `LocalConfiguration.current` is **Android-only** and lives in `androidMain`. For CMP, prefer the cross-platform alternatives:
    
    - `LocalWindowInfo.current.containerSize` - the window/screen size as `IntSize`, available in `commonMain`.
    - `LocalDensity.current` - density, available in `commonMain`.
    - `LocalLayoutDirection.current` - LTR / RTL.
    - `BoxWithConstraints { ... }` - read `maxWidth` / `maxHeight` directly inside layout.
    
    If you need real device characteristics (orientation, idiom, model), wrap the access in `expect`/`actual` and pass a typed object like `PlatformInfo` to the common layer.
    
    ---
    
    ## Fonts cross-platform via Compose Resources
    
    `org.jetbrains.compose.resources` is the shared resources plugin. Drop fonts in `commonMain/composeResources/font/`, and the Gradle plugin generates a typed `Res` accessor.
    
    ```
    composeApp/src/commonMain/composeResources/
    ├── font/
    │   ├── Inter-Regular.ttf
    │   └── Inter-Bold.ttf
    ├── drawable/
    │   └── logo.xml            ← Android XML vector. SVG works on every target EXCEPT Android
    └── values/
        ├── strings.xml          ← default locale
    └── values-fr/
        └── strings.xml          ← French overrides (qualifier goes on the DIRECTORY)
    ```
    
    Usage in `commonMain`:
    
    ```kotlin
    import myproject.composeapp.generated.resources.Inter_Regular
    import myproject.composeapp.generated.resources.Inter_Bold
    import myproject.composeapp.generated.resources.Res
    
    val InterFamily = FontFamily(
        Font(Res.font.Inter_Regular, FontWeight.Normal),
        Font(Res.font.Inter_Bold, FontWeight.Bold),
    )
    
    Text("Hello", fontFamily = InterFamily)
    ```
    
    Same pattern for `Res.drawable.logo` (image) and `Res.string.app_name` (localized string via `stringResource(...)`). Raw files are the exception: there is no generated `Res.file.*` accessor - you pass a path string to the suspend function `Res.readBytes(path)`, e.g. `val bytes = Res.readBytes("files/config.json")`, for anything under `composeResources/files/`.
    
    ---
    
    ## iOS interop with SwiftUI
    
    CMP produces a `UIViewController` you can drop into a SwiftUI app. KMP generates a top-level Kotlin function (commonly named `MainViewController()` or `ComposeUIViewController { ... }`) that returns a `UIViewController`. Wrap it with `UIViewControllerRepresentable`.
    
    ```kotlin
    // iosMain/kotlin/main.ios.kt
    fun MainViewController(): UIViewController = ComposeUIViewController {
        AppContent()  // commonMain composable
    }
    ```
    
    ```swift
    // iOS app target
    import SwiftUI
    import ComposeApp  // KMP-generated framework
    
    struct ComposeContent: UIViewControllerRepresentable {
        func makeUIViewController(context: Context) -> UIViewController {
            Main_iosKt.MainViewController()
        }
        func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
    }
    
    struct ContentView: View {
        var body: some View { ComposeContent().ignoresSafeArea() }
    }
    ```
    
    The Kotlin function name gets mangled to `Main_iosKt.MainViewController()` because the file is `main.ios.kt`. Check the generated framework headers if the symbol name surprises you.
    
    ---
    
    ## Android entry point
    
    No interop ceremony on Android. The Activity hosts the common composable directly via `setContent { ... }`.
    
    ```kotlin
    // androidApp/src/main/kotlin/MainActivity.kt
    class MainActivity : ComponentActivity() {
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContent {
                AppContent()  // commonMain composable
            }
        }
    }
    ```
    
    If you need to pass `Context` or `Activity` into `commonMain`, expose it via a DI graph or an `expect class PlatformContext` in `commonMain` with `actual class PlatformContext(val context: Context)` in `androidMain`.
    
    ---
    
    ## Embedding SwiftUI/UIKit inside a Compose iOS view (the reverse direction)
    
    Use `UIKitView` for a `UIView` factory or `UIKitViewController` for a `UIViewController` factory.
    
    ```kotlin
    // iosMain
    UIKitView(
        factory = {
            UISwitch().apply {
                addTarget(target, action = NSSelectorFromString("onToggle:"), forControlEvents = UIControlEventValueChanged)
            }
        },
        modifier = Modifier.size(48.dp, 32.dp)
    )
    ```
    
    For SwiftUI views: wrap them in a `UIHostingController` exposed via a Swift `@objc` bridge function, then call from Kotlin via the generated headers (cinterop). See `references/cmp-interop.md` for the full pattern.
    
    ---
    
    ## Animation cross-platform
    
    All animation APIs (`animate*AsState`, `AnimatedVisibility`, `updateTransition`, `SharedTransitionLayout`) work identically across targets in CMP 1.7+. Spring tuning written in `commonMain` produces the same physics on Android and iOS. Gestures (`Modifier.draggable`, `Modifier.pointerInput`) work cross-platform with the same API surface.
    
    The animation primer lives in `../compose-motion/SKILL.md`. Cross-platform deltas to keep in mind:
    - iOS first-frame is slower (Skia bootstrap); a 200ms enter animation feels tighter on Android, slightly delayed on iOS cold start.
    - Wasm motion can stutter on first frame (JIT warmup); pre-warm critical paths or hide motion until interactive.
    
    ---
    
    ## What does NOT work (gotchas)
    
    - **Drawer state on iOS**: native `ModalNavigationDrawer` swipe-to-open from the leading edge conflicts with iOS's back-swipe gesture. Use a button trigger or move the swipe area inward 30dp+.
    - **`LayoutDirection.Rtl` quirks**: Android handles RTL natively, iOS Compose had bugs in 1.6 (text alignment, padding inversions). Improved in 1.7+ but verify with real Arabic/Hebrew strings.
    - **Soft keyboard handling**: `imePadding()` / `WindowInsets.ime` work on Android out of the box and are implemented on iOS too. There is **no** `IOSKeyboardEventListener` type in CMP - the real knob is `ComposeUIViewControllerConfiguration.onFocusBehavior`, which defaults to `OnFocusBehavior.FocusableAboveKeyboard` (CMP pans the *whole* Compose view up so the focused field clears the keyboard). If you want to drive the layout yourself with `imePadding()` / `WindowInsets.ime`, turn the automatic pan off:
      ```kotlin
      // iosMain - imports: androidx.compose.ui.window.ComposeUIViewController,
      //                    androidx.compose.ui.uikit.OnFocusBehavior
      fun MainViewController(): UIViewController = ComposeUIViewController(
          configure = { onFocusBehavior = OnFocusBehavior.DoNothing }
      ) {
          AppContent()
      }
      ```
      Leaving the default on *and* applying `imePadding()` is the classic double-adjustment bug; same if the SwiftUI parent hosting the controller also adjusts for the keyboard.
    - **`Color.parseHex(...)`** does not exist in Compose. Use `Color(0xFFRRGGBB)` or write a tiny extension.
    - **System fonts on iOS via Compose**: do not fallback to `FontFamily.SansSerif` and expect SF Pro. Compose on iOS ships its own font fallback chain. Either bundle SF Pro via Compose Resources (license-permitting) or use `UIKitView` to drop a native `UILabel` for system-font text.
    - **Animations on Web (Wasm)**: heavier startup, occasional first-frame stutter; profile with browser devtools and lazy-load heavy animation graphs.
    - **`java.util.UUID`, `java.io.File`** and other JVM-only APIs are forbidden in `commonMain` if you ship to iOS or Wasm. Use `kotlinx.uuid`, `kotlinx-io`, or the `okio` multiplatform port.
    
    ---
    
    ## CMP version notes
    
    - Current stable is **Compose Multiplatform 1.12.2** (released 15 Oct 2026; 1.12.0 shipped 25 Aug 2026); the previous line was 1.11 (1.11.1, 2 Jun 2026) and 1.13 is in beta. Treat 1.7 as the historical floor for `SharedTransitionLayout` cross-platform, iOS keyboard handling and `LocalLifecycleOwner` on iOS, not as the version to target.
    - Since 1.7, iOS interop lives in `androidx.compose.ui.viewinterop` (`UIKitView`, `UIKitViewController`, `UIKitInteropProperties`); the old `androidx.compose.ui.interop.UIKitView` overloads with `interactive:` / `accessibilityEnabled:` parameters are `@Deprecated`.
    - 1.10 added `UIKitInteropProperties(placedAsOverlay = true)` so an interop view can be composited *above* Compose content, plus intrinsic-size (`sizeThatFits`) support for wrapping SwiftUI views in a `UIHostingController`.
    - Kotlin 2.x with the K2 compiler; pair the latest CMP with the latest Kotlin (2.2.20+ for iOS/web targets).
    - Some Material 3 components have platform-specific look (e.g., `Switch` on iOS auto-renders with iOS-style proportions; `DatePicker` stays Material across all targets).
    - `compose-multiplatform-resources` plugin is the standard for assets; the older `moko-resources` is no longer recommended for new projects.
    
    ---
    
    ## Performance considerations
    
    - **iOS first-frame** is slower than Android (Skia bootstrapping ~150-300ms cold). Keep your splash visible until the first composition emits, or pre-warm with a transparent root composable.
    - **Wasm bundle size**: aim for <2MB compressed. Tree-shake heavy deps, lazy-load secondary screens via `kotlinx.coroutines` deferred composition, and inspect the `.wasm` output in `wasmJsBrowserDistribution`.
    - **Desktop**: cold start is fast on JVM; AOT compilation via Kotlin/Native is overkill for desktop unless you need a single-file binary.
    - **Android**: same baseline as Jetpack Compose - profile with the Compose compiler stability metrics and `Layout Inspector` recomposition counts.
    
    ---
    
    ## Anti-Patterns
    
    | BAD | GOOD | Why |
    |---|---|---|
    | Reflection trick or `System.getProperty("os.name")` to detect platform inside `commonMain` | `expect`/`actual` with a typed `Platform` object | Reflection breaks on Wasm/Native; `expect`/`actual` is the contract the compiler enforces |
    | Assuming Android `Context` is reachable in `commonMain` | Inject a typed dependency via `expect class PlatformContext` or a DI scope | `Context` does not exist on iOS/Desktop/Wasm; the code will not compile for those targets |
    | Hardcoding Material colors that look great on Android but jarring on iOS | Define a `commonMain` design system, then optionally adjust 2-3 tokens via `actual` | Cross-platform consistency is good, but iOS users notice when a Material blue feels alien on iPhone |
    | `LaunchedEffect(Unit) { while(true) { delay(16); ... } }` in `commonMain` | `rememberInfiniteTransition()` or scope to lifecycle events | Tight coroutine loops drain battery on iOS; infinite transitions pause when offscreen |
    
    ---
    
    ## Quick Reference: Loading Sub-skills
    
    | Need | Load |
    |---|---|
    | iOS / Android interop deep-dive | `references/cmp-interop.md` |
    | Per-platform behavior catalog | `references/cmp-platform-quirks.md` |
    | Animation API | `../compose-motion/SKILL.md` |
    | Advanced graphics (M3 Expressive, AGSL on Android only) | `../compose-graphics/SKILL.md` |
    | iOS-side native interop with SwiftUI | `../swiftui-motion/SKILL.md` (when target is iOS and SwiftUI native blend wanted) |
    | Mobile UX context | `../mobile-principles/SKILL.md` |
    | Desktop UX context | `../desktop-principles/SKILL.md` |
    | Foundation | `../motion-principles/SKILL.md` |
    
    ---
    
    ## Sources
    
    - [Meet-Miyani/compose-skill](https://github.com/Meet-Miyani/compose-skill) (KMP/CMP comprehensive)
    - [JetBrains Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/)
    - [Compose Multiplatform docs](https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform.html)
    - [skydoves/Orbital](https://github.com/skydoves/Orbital) (KMP-aware shared transitions)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.