swiftui-compose-skill

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                     ┃
┃   ◆  swiftui · compose             AI Coding Skill  ┃
┃   ─────────────────────────────────────────────     ┃
┃                                                     ┃
┃   Compose  ◄────────────────────────────► SwiftUI   ┃
┃                                                     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

What This Skill Covers

🔗 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

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

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

Official Documentation

Requirements

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