swiftui compose skill

An AI coding skill for bidirectional interop between
Compose Multiplatform and SwiftUI.

What it covers · Files · Core principle · Quick start · Key rules · Docs · Automated maintenance

---

What This Skill Covers

| | | |---|---| | Compose in SwiftUI | ComposeUIViewController + UIViewControllerRepresentable wiring | | State bridging | makeCoordinator(), push and bidirectional patterns, Kotlin mutableStateOf | | SwiftUI in Compose | UIKitView, UIKitViewController, UIHostingController | | UIKit embedding | Maps, text fields, camera, pickers via UIKitView | | Teardown | dismantleUIViewController, AsyncStream.onTermination | | Touch routing | UIKitInteropProperties cooperative vs non-cooperative gestures |

🔗 Bridging KMP data and logic into Swift? See the companion swift-kmp skill.

---

Core Principle

Create the Compose UIViewController once, then update state through methods —
never recreate it.

❌ Anti-pattern: .id(someState) on a Compose view
   → tears down and recreates UIViewController on every state change
   → visual glitches, wasted memory, Compose lifecycle restart

✅ Correct: makeCoordinator() holds the UIViewController reference (created once)
           updateUIViewController() calls context.coordinator.update*(newState)

Apple's documentation confirms the intended lifecycle:

"SwiftUI calls makeCoordinator() before calling makeUIViewController(context:). The system provides your coordinator either directly or as part of a context structure when calling the other methods of your representable instance."

---

Files

| File | Load when | Tokens | |------|-----------|--------| | SKILL.md | Always first — anti-patterns, quick reference, review checklist | ~1.5k | | references/compose-in-swiftui.md | Embedding Compose in SwiftUI; coordinator wiring; ComposeUIViewController Kotlin setup | ~2k | | references/swiftui-in-compose.md | Embedding SwiftUI/UIKit inside Compose; UIKitViewController; UIKitView | ~2k | | references/state-sharing.md | Bidirectional state; all 3 patterns; StateFlow → AsyncStream; dismantleUIViewController | ~2.5k |

Token budget: SKILL.md (~1.5k tokens) covers anti-patterns and routing. Load one reference only when you need the detailed API for that topic.

---

Quick Start

1. Install

# Clone into the canonical skill location:
git clone https://github.com/sorunokoe/swiftui-compose-skill.git \
  /path/to/your-project/.github/skills/swiftui-compose

# Optional: detach from upstream git history
rm -rf /path/to/your-project/.github/skills/swiftui-compose/.git

Why .github/skills/swiftui-compose/? This is the path GitHub Copilot, Cursor, and skills-evolution discover skills from.

2. Use with GitHub Copilot

@swiftui-compose Help me embed a Compose map screen in my SwiftUI app with filter state

3. Use with Claude / any AI agent

Load swiftui-compose/SKILL.md, then swiftui-compose/references/state-sharing.md.

I need to embed a Kotlin Compose map screen in SwiftUI. The SwiftUI side has
@State var filters: [MapFilter] that need to flow into Compose when they change.
Compose calls back via onMarkerClick. Implement the full coordinator pattern.

---

---

Key Rules (summary)

• ❌ .id(someState) on a Compose view — recreates the entire lifecycle
• ❌ Calling the build: closure inside updateUIViewController — creates a new Compose lifecycle on every update
• ❌ Storing a @State copy of the Kotlin holder — use makeCoordinator() for a stable reference
• ✅ CADisableMinimumFrameDurationOnPhone = YES in Info.plist — required for Compose on iOS
• ✅ context.coordinator.update*(…) in updateUIViewController — correct way to push SwiftUI state to Compose
• ✅ dismantleUIViewController implemented when coordinator owns subscriptions or tasks

Full rules and review checklist in SKILL.md.

---

The Three State Patterns

| When | Pattern | |------|---------| | Compose owns all state; SwiftUI just positions | Unidirectional — simple UIViewControllerRepresentable, empty updateUIViewController | | SwiftUI state needs to flow into Compose | Push — makeCoordinator() + context.coordinator.update*() in updateUIViewController | | State flows both ways + Compose fires Swift callbacks | Bidirectional — coordinator holds holder, callbacks provided at build time |

Full patterns with code in references/state-sharing.md.

---

Official Documentation

| Topic | Link | |-------|------| | Compose Multiplatform ↔ SwiftUI | kotlinlang.org → | | Compose Multiplatform ↔ UIKit | kotlinlang.org → | | Apple UIViewControllerRepresentable | developer.apple.com → | | Apple makeCoordinator() | developer.apple.com → | | Apple dismantleUIViewController | developer.apple.com → | | Apple UIHostingController | developer.apple.com → | | Compose Multiplatform interop examples | github.com/JetBrains → |

---

Requirements

| | Version | |---|---| | Compose Multiplatform | 1.8+ (iOS stable since 1.8.0, May 2025) | | Kotlin | 2.1+ | | Swift | 5.9+ | | iOS | 15.0+ |

Compose Multiplatform iOS is stable as of version 1.8.0 (May 2025). CMP 1.8+ requires Kotlin 2.1+.

---

Related Skills

🔗 Bridging Kotlin data and logic into your Swift feature modules?
Check out swift-kmp — the companion skill covering the bridge layer architecture, interactors, SkieSwiftFlow → AsyncStream wrapping, type mapping, and KotlinThrowable containment.

---

Automated Maintenance

This skill is governed by skills-evolution — AI skill governance that keeps guidance files accurate and up to date automatically.

gh-aw (recommended)

# PR review — AI feedback on every PR touching SKILL.md or references/**
gh aw add sorunokoe/skills-evolution/workflows/oss-skill-pr-check.md@latest

# Monthly update — version checks, AI content patches, opens PR
gh aw add sorunokoe/skills-evolution/workflows/oss-skill-update.md@latest

gh aw compile

GitHub Actions

.github/workflows/skill-health.yml — runs monthly and on demand:

• Structural audit — broken local links, missing frontmatter fields
• AI content update — checks SKILL.md + references/*.md against the latest compose-multiplatform release; proposes conservative patches via GitHub Models

# .github/workflows/skill-health.yml
name: Skill Health
on:
  schedule:
    - cron: "0 3 1 * *"
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
  models: read
jobs:
  health:
    uses: sorunokoe/skills-evolution/.github/workflows/oss-skill-health.yml@latest
    with:
      enable_ai_skill_update: true
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

---

Contributing

See CONTRIBUTING.md for how to improve patterns or add new reference files.

License

MIT