Skip to main content
Agent skill

Swiftui Patterns

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices. Use when building or reviewing SwiftUI views, @Observable state, navigation, or render performance.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Swiftui Patterns when an AI agent needs a reusable SKILL.md workflow for this job: SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices. Use when building or reviewing SwiftUI views, @Observable state, navigation, or render performance.

When not to use it

Skip Swiftui Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/swiftui-patterns
# Save SKILL.md to ~/.claude/skills/swiftui-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/swiftui-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/swiftui-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Swiftui Patterns skill for this task: Use Swiftui Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# SwiftUI Patterns

Modern SwiftUI patterns for building declarative, performant user interfaces on Apple platforms. Covers the Observation framework, view composition, type-safe navigation, and performance optimization.

## When to Activate

- Building SwiftUI views and managing state (`@State`, `@Observable`, `@Binding`) - Designing navigation flows with `NavigationStack` - Structuring view models and data flow - Optimizing rendering performance for lists and complex layouts - Working with environment values and dependency injection in SwiftUI

## State Management

### Property Wrapper Selection

Choose the simplest wrapper that fits:

| Wrapper | Use Case | |---------|----------| | `@State` | View-local value types (toggles, form fields, sheet presentation) | | `@Binding` | Two-way reference to parent's `@State` | | `@Observable` class + `@State` | Owned model with multiple properties | | `@Observable` class (no wrapper) | Read-only reference passed from parent | | `@Bindable` | Two-way binding to an `@Observable` property | | `@Environment` | Shared dependencies injected via `.environment()` |

### @Observable ViewModel

Use `@Observable` (not `ObservableObject`) — it tracks property-level changes so SwiftUI only re-renders views that read the changed property:

```swift @Observable final class ItemListViewModel { private(set) var items: [Item] = [] private(set) var isLoading = false var searchText = ""

private let repository: any ItemRepository

init(repository: any ItemRepository = DefaultItemRepository()) { self.repository = repository }

func load() async { isLoading = true defer { isLoading = false } items = (try? await repository.fetchAll()) ?? [] } } ```

### View Consuming the ViewModel

```swift struct ItemListView: View { @State private var viewModel: ItemListViewModel

init(viewModel: ItemListViewModel = ItemListViewModel()) { _viewModel = State(initialValue: viewModel) }

var body: some View { List(viewModel.items) { item in ItemRow(item: item) } .searchable(text: $viewModel.searchText) .overlay { if viewModel.isLoading { ProgressView() } } .task { await viewModel.load() } } } ```

### Environment Injection

Replace `@EnvironmentObject` with `@Environment`:

```swift // Inject ContentView() .environment(authManager)

// Consume struct ProfileView: View { @Environment(AuthManager.self) private var auth

var body: some View { Text(auth.currentUser?.name ?? "Guest") } } ```

## View Composition

### Extract Subviews to Limit Invalidation

Break views into small, focused structs. When state changes, only the subview reading that state re-renders:

```swift struct OrderView: View { @State private var viewModel = OrderViewModel()

var body: some View { VStack { OrderHeader(title: viewModel.title) OrderItemList(items: viewModel.items) OrderTotal(total: viewModel.total) } } } ```

### ViewModifier for Reusable Styling

```swift struct CardModifier: ViewModifier { func body(content: Content) -> some View { content .padding() .background(.regularMaterial) .clipShape(RoundedRectangle(cornerRadius: 12)) } }

extension View { func cardStyle() -> some View { modifier(CardModifier()) } } ```

## Navigation

### Type-Safe NavigationStack

Use `NavigationStack` with `NavigationPath` for programmatic, type-safe routing:

```swift @Observable final class Router { var path = NavigationPath()

func navigate(to destination: Destination) { path.append(destination) }

func popToRoot() { path = NavigationPath() } }

enum Destination: Hashable { case detail(Item.ID) case settings case profile(User.ID) }

struct RootView: View { @State private var router = Router()

var body: some View { NavigationStack(path: $router.path) { HomeView() .navigationDestination(for: Destination.self) { dest in switch dest { case .detail(let id): ItemDetailView(itemID: id) case .settings: SettingsView() case .profile(let id): ProfileView(userID: id) } } } .environment(router) } } ```

## Performance

### Use Lazy Containers for Large Collections

`LazyVStack` and `LazyHStack` create views only when visible:

```swift ScrollView { LazyVStack(spacing: 8) { ForEach(items) { item in ItemRow(item: item) } } } ```

### Stable Identifiers

Always use stable, unique IDs in `ForEach` — avoid using array indices:

```swift // Use Identifiable conformance or explicit id ForEach(items, id: \.stableID) { item in ItemRow(item: item) } ```

### Avoid Expensive Work in body

- Never perform I/O, network calls, or heavy computation inside `body` - Use `.task {}` for async work — it cancels automatically when the view disappears - Use `.sensoryFeedback()` and `.geometryGroup()` sparingly in scroll views - Minimize `.shadow()`, `.blur()`, and `.mask()` in lists — they trigger offscreen rendering

### Equatable Conformance

For views with expensive bodies, conform to `Equatable` to skip unnecessary re-renders:

```swift struct ExpensiveChartView: View, Equatable { let dataPoints: [DataPoint] // DataPoint must conform to Equatable

static func == (lhs: Self, rhs: Self) -> Bool { lhs.dataPoints == rhs.dataPoints }

var body: some View { // Complex chart rendering } } ```

## Previews

Use `#Preview` macro with inline mock data for fast iteration:

```swift #Preview("Empty state") { ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository())) }

#Preview("Loaded") { ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository())) } ```

## Anti-Patterns to Avoid

- Using `ObservableObject` / `@Published` / `@StateObject` / `@EnvironmentObject` in new code — migrate to `@Observable` - Putting async work directly in `body` or `init` — use `.task {}` or explicit load methods - Creating view models as `@State` inside child views that don't own the data — pass from parent instead - Using `AnyView` type erasure — prefer `@ViewBuilder` or `Group` for conditional views - Ignoring `Sendable` requirements when passing data to/from actors

## References

See skill: `swift-actor-persistence` for actor-based persistence patterns. See skill: `swift-protocol-di-testing` for protocol-based DI and testing with Swift Testing.

Intended uses

  • Use Swiftui Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.