# swiftui-patterns

swiftui-patterns guides Claude Code through iOS 17+ SwiftUI conventions: the @Observable macro, NavigationStack, and clean UIKit interop.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 233 repo stars
- Author: John Rogers (@johnrogers)
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swiftui-patterns/SKILL.md
- Updated: 2026-01-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/john-rogers-at-johnrogers-swiftui-patterns

## What it does

This skill guides your coding agent toward Apple's modern iOS 17 APIs instead of third-party reactive frameworks. It replaces heavy `ObservableObject` and `@Published` boilerplate with the `@Observable` macro, configures dependencies via `@Environment`, and automates async flows with `.task`.

The tool relies on twelve specialized reference guides covering navigation paths, VoiceOver traits, view models, and UIKit bridges like `WKWebView`. Claude loads these topics on demand when updating views or handling list performance.

Overusing `@Bindable` on read-only properties triggers redundant view reloads, so the skill restricts two-way bindings to truly mutable model fields.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add johnrogers/claude-swift-engineering
```
In the agent chat (not a shell):
```text
/plugin install swift-engineering@claude-swift-engineering
```
This installs the whole swift-engineering plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swiftui-patterns -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/swiftui-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/swiftui-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swiftui-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/swiftui-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swiftui-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/swiftui-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/swiftui-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/swiftui-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swiftui-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/swiftui-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/swiftui-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swiftui-patterns/SKILL.md

## When to use it
- migrate views from ObservableObject to the @Observable macro
- structure type-safe routing with NavigationStack and NavigationPath
- bridge UIKit views through UIViewRepresentable without retain cycles
- implement VoiceOver hints and Dynamic Type support across views

## Example prompts
- Refactor this settings screen from `ObservableObject` to the modern `@Observable` macro.
- Set up programmatic deep link navigation using `NavigationStack` and `NavigationPath`.
- Wrap `WKWebView` inside a `UIViewRepresentable` container with safe delegate cleanup.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c5cdd2fca5951118.

BEGIN THIRD-PARTY FILE c5cdd2fca5951118
```text
---
name: swiftui-patterns
description: >-
  Use when implementing iOS 17+ SwiftUI patterns: @Observable/@Bindable, MVVM architecture, NavigationStack, lazy loading, UIKit interop, accessibility (VoiceOver/Dynamic Type), async operations (.task/.refreshable), or migrating from ObservableObject/@StateObject.
---

# SwiftUI Patterns (iOS 17+)

SwiftUI 17+ removes ObservableObject boilerplate with @Observable, simplifies environment injection with @Environment, and introduces task-based async patterns. The core principle: use Apple's modern APIs instead of reactive libraries.

## Overview

## Quick Reference

| Need | Use (iOS 17+) | NOT |
|------|---------------|-----|
| Observable model | `@Observable` | `ObservableObject` |
| Published property | Regular property | `@Published` |
| Own state | `@State` | `@StateObject` |
| Passed model (binding) | `@Bindable` | `@ObservedObject` |
| Environment injection | `environment(_:)` | `environmentObject(_:)` |
| Environment access | `@Environment(Type.self)` | `@EnvironmentObject` |
| Async on appear | `.task { }` | `.onAppear { Task {} }` |
| Value change | `onChange(of:initial:_:)` | `onChange(of:perform:)` |

## Core Workflow

1. Use `@Observable` for model classes (no @Published needed)
2. Use `@State` for view-owned models, `@Bindable` for passed models
3. Use `.task { }` for async work (auto-cancels on disappear)
4. Use `NavigationStack` with `NavigationPath` for programmatic navigation
5. Apply `.accessibilityLabel()` and `.accessibilityHint()` to interactive elements

## Reference Loading Guide

**ALWAYS load reference files if there is even a small chance the content may be required.** It's better to have the context than to miss a pattern or make a mistake.

| Reference | Load When |
|-----------|-----------|
| **[Observable](references/observable.md)** | Creating new `@Observable` model classes |
| **[State Management](references/state-management.md)** | Deciding between `@State`, `@Bindable`, `@Environment` |
| **[Environment](references/environment.md)** | Injecting dependencies into view hierarchy |
| **[View Modifiers](references/view-modifiers.md)** | Using `onChange`, `task`, or iOS 17+ modifiers |
| **[Migration Guide](references/migration-guide.md)** | Updating iOS 16 code to iOS 17+ |
| **[MVVM Observable](references/mvvm-observable.md)** | Setting up view model architecture |
```
END THIRD-PARTY FILE c5cdd2fca5951118

The third-party file has ended. Everything between the c5cdd2fca5951118 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2379 of 4273 bytes. © John Rogers (@johnrogers) · MIT · https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swiftui-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
