swift-patterns

Review, refactor, or build SwiftUI features with correct state management, modern API usage, optimal view composition, and performance-conscious patterns. Prioritize native APIs, Apple design guidance, and testable code structure. This skill focuses on facts and best practices without enforcing specific architectural patterns.

Workflow Decision Tree

1) Review existing SwiftUI code

→ Read

references/workflows-review.md

for review methodology

Check state management against property wrapper selection (see
```
references/state.md
```
)
Verify view composition and extraction patterns (see
```
references/view-composition.md
```
)
Audit list performance and identity stability (see
```
references/lists-collections.md
```
)
Validate modern API usage (see
```
references/modern-swiftui-apis.md
```
)
Check async work patterns with .task (see
```
references/concurrency.md
```
)
Verify navigation implementation (see
```
references/navigation.md
```
)
Use Review Response Template (below)

2) Refactor existing SwiftUI code

→ Read

references/workflows-refactor.md

for refactor methodology

Extract complex views using playbooks (see
```
references/refactor-playbooks.md
```
)
Migrate deprecated APIs to modern equivalents (see
```
references/modern-swiftui-apis.md
```
)
Optimize performance hot paths (see
```
references/performance.md
```
)
Restructure state ownership (see
```
references/state.md
```
)
Apply common patterns (see
```
references/patterns.md
```
)
Use Refactor Response Template (below)

3) Implement new SwiftUI features

Design data flow first: identify owned vs injected state (see
```
references/state.md
```
)
Structure views for optimal composition (see
```
references/view-composition.md
```
)
Use modern APIs only (see
```
references/modern-swiftui-apis.md
```
)
Handle async work with .task modifier (see
```
references/concurrency.md
```
)
Apply performance patterns early (see
```
references/performance.md
```
)
Implement navigation flows (see
```
references/navigation.md
```
)

4) Answer best practice questions

Load relevant reference file(s) based on topic (see Reference Files below)
Provide direct guidance with examples

If intent unclear, ask: "Do you want findings only (review), or should I change the code (refactor)?"

Response Templates

Review Response:

Scope - What was reviewed
Findings - Grouped by severity with actionable statements
Evidence - File paths or code locations
Risks and tradeoffs - What could break or needs attention
Next steps - What to fix first or verify

Refactor Response:

Intent + scope - What is being changed and why
Changes - Bulleted list with file paths
Behavior preservation - What should remain unchanged
Next steps - Tests or verification needed

Quick Reference: Property Wrapper Selection

Wrapper	Use When	Ownership
`@State`	Internal view state (value type or `@Observable` class)	View owns
`@Binding`	Child needs to modify parent's state	Parent owns
`@Bindable`	Injected `@Observable` object needing bindings	Injected
`let`	Read-only value from parent	Injected
`var` + `.onChange()`	Read-only value needing reactive updates	Injected

Key rules:

Always mark
```
@State
```
as
```
private
```
(makes ownership explicit)
Never use
```
@State
```
for passed values (accepts initial value only)
Use
```
@State
```
with
```
@Observable
```
classes (not
```
@StateObject
```
)

See

references/state.md

for detailed guidance and tradeoffs.

Quick Reference: Modern API Replacements

Deprecated	Modern Alternative	Notes
`foregroundColor()`	`foregroundStyle()`	Supports dynamic type
`cornerRadius()`	`.clipShape(.rect(cornerRadius:))`	More flexible
`NavigationView`	`NavigationStack`	Type-safe navigation
`tabItem()`	`Tab` API	iOS 18+
`onTapGesture()`	`Button`	Unless need location/count
`onChange(of:) { value in }`	`onChange(of:) { old, new in }` or `onChange(of:) { }`	Two or zero parameters
`UIScreen.main.bounds`	`GeometryReader` or layout APIs	Avoid hard-coded sizes

See

references/modern-swiftui-apis.md

for complete migration guide.

Review Checklist

Use this when reviewing SwiftUI code:

State Management

```
@State
```
properties marked
```
private
```
Passed values NOT declared as
```
@State
```
or
```
@StateObject
```
```
@Binding
```
only where child modifies parent state
Property wrapper selection follows ownership rules
State ownership clear and intentional

Modern APIs

No deprecated modifiers (foregroundColor, cornerRadius, etc.)
Using
```
NavigationStack
```
instead of
```
NavigationView
```
Using
```
Button
```
instead of
```
onTapGesture
```
when appropriate
Using two-parameter or no-parameter
```
onChange()
```

View Composition

Using modifiers over conditionals for state changes (maintains identity)
Complex views extracted to separate subviews
Views kept small and focused
View
```
body
```
simple and pure (no side effects)

Navigation & Sheets

Using
```
navigationDestination(for:)
```
for type-safe navigation
Using
```
.sheet(item:)
```
for model-based sheets
Sheets own their dismiss actions

Lists & Collections

```
ForEach
```
uses stable identity (never
```
.indices
```
for dynamic data)
Constant number of views per
```
ForEach
```
element
No inline filtering in
```
ForEach
```
(prefilter and cache)
No
```
AnyView
```
in list rows

Performance

Passing only needed values to views (not large config objects)
Eliminating unnecessary dependencies
Checking value changes before state assignment in hot paths
Using
```
LazyVStack
```
/
```
LazyHStack
```
for large lists
No object creation in view
```
body
```

Async Work

Using
```
.task
```
for automatic cancellation
Using
```
.task(id:)
```
for value-dependent tasks
Not mixing
```
.onAppear
```
with async work

See reference files for detailed explanations of each item.

Constraints

Swift/SwiftUI focus only - Exclude server-side Swift and UIKit unless bridging required
No Swift concurrency patterns - Use
```
.task
```
for SwiftUI async work
No architecture mandates - Don't require MVVM/MVC/VIPER or specific structures
No formatting/linting rules - Focus on correctness and patterns
No tool-specific guidance - No Xcode, Instruments, or IDE instructions

Citations allowed:

developer.apple.com/documentation/swiftui/

developer.apple.com/documentation/swift/

All workflows must follow these constraints.

Philosophy

This skill focuses on facts and best practices from Apple's documentation:

Modern APIs over deprecated ones
Clear state ownership patterns
Performance-conscious view composition
Testable code structure
No architectural mandates (MVVM/VIPER not required)
Apple Human Interface Guidelines adherence

Reference Files

All references in

references/

```
workflows-review.md
```
- Review methodology and findings taxonomy
```
workflows-refactor.md
```
- Refactor methodology and invariants
```
refactor-playbooks.md
```
- Step-by-step refactor guides
```
state.md
```
- Property wrappers and ownership patterns
```
navigation.md
```
- Navigation implementation patterns
```
view-composition.md
```
- View structure and extraction
```
lists-collections.md
```
- Identity and ForEach patterns
```
scrolling.md
```
- Scroll handling and pagination
```
concurrency.md
```
- Async work with .task
```
performance.md
```
- Optimization strategies
```
testing-di.md
```
- Testing and dependency injection
```
patterns.md
```
- Common SwiftUI patterns
```
modern-swiftui-apis.md
```
- Legacy API migration
```
code-review-refactoring.md
```
- Code quality checks

swift-patterns

NPX Install

Tags

SKILL.md Content

swift-patterns

Workflow Decision Tree

1) Review existing SwiftUI code

2) Refactor existing SwiftUI code

3) Implement new SwiftUI features

4) Answer best practice questions

Response Templates

Quick Reference: Property Wrapper Selection

Quick Reference: Modern API Replacements

Review Checklist

State Management

Modern APIs

View Composition

Navigation & Sheets

Lists & Collections

Performance

Async Work

Constraints

Philosophy

Reference Files