Skip to main content
skill CX Codex

swift-ui-architect — Claude Code skill: what it does, how to install

swift-ui-architect enforces modular MVVM-C architecture for SwiftUI and Swift 6.2 across local SPM packages. Keeps Domain, Data, and Feature boundaries strict during code generation.

MIT 283 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill swift-ui-architect -a claude-code
Open on GitHub

What swift-ui-architect does

This skill enforces strict modular MVVM-C architecture in SwiftUI projects targeting Swift 6.2 and iOS 26. Code lives inside local SPM packages with strict boundaries. Feature modules import only Domain and DesignSystem. Direct access to Data or neighboring features is disallowed. The main App target acts as the convergence hub: it instantiates DependencyContainer, holds concrete coordinators with NavigationPath, and configures Route Shells.

State management relies on @Observable classes. The skill blocks ObservableObject and @Published. There is no dedicated use-case or interactor tier: ViewModels call Domain repository protocols directly. All persistence, SwiftData queries, URLSession tasks, and retry queues belong inside the Data package. Reads follow a stale-while-revalidate pattern, while writes go to an optimistic background queue.

In codebases still using ObservableObject or monolithic targets, applying these constraints will cause immediate compilation breakage.

What it helps with

  • isolate module boundaries between Feature, Domain, and Data packages
  • migrate ViewModel state from ObservableObject to @Observable
  • route navigation and NavigationPath through App-target coordinators
  • set up stale-while-revalidate reads with queued optimistic sync

Example prompts for the agent

  • Review the ProfileFeature module to ensure no Data package imports leaked into views.
  • Refactor CartViewModel to Swift 6.2 using @Observable and direct Domain repository calls.
  • Wire a coordinator and route shell for checkout navigation using NavigationPath.

How to install swift-ui-architect

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill swift-ui-architect -a claude-code

2Manually: put the files in place

~/.claude/skills/swift-ui-architect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/swift-ui-architect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about swift-ui-architect

How do I install swift-ui-architect in Claude Code?

Run npx skills add pproenca/dot-skills --skill swift-ui-architect -a claude-code in your terminal. The configuration file will be placed in ~/.claude/skills/swift-ui-architect/SKILL.md.

What dependencies are feature modules allowed to import?

Feature packages can only import Domain and DesignSystem. Importing Data or sibling feature targets violates the architectural contract.

Why is there no dedicated Use Case layer?

Under these guidelines, ViewModels communicate directly with repository protocols defined in Domain. Omitting an extra interactor layer keeps the Swift 6.2 modular setup lightweight.

Source text

SKILL.md · MIT
---
name: swift-ui-architect
description: Opinionated SwiftUI architecture enforcement for iOS 26 / Swift 6.2 clinic modular MVVM-C apps using local SPM package boundaries. Enforces App-target `DependencyContainer` + route shells, @Observable ViewModels/coordinators, Domain repository/coordinator/error-routing protocols, Data-owned I/O, stale-while-revalidate reads, and optimistic queued sync. Use when writing, reviewing, or refactoring SwiftUI architecture, navigation, dependency wiring, or repository boundaries.
---

# SwiftUI Modular MVVM-C Architecture

Opinionated architecture enforcement for SwiftUI clinic-style apps. This skill aligns to the iOS 26 / Swift 6.2 clinic architecture: modular MVVM-C in local SPM packages, concrete coordinators and route shells in the App target, pure Domain protocols, and Data as the only I/O layer.

## Mandated Architecture Stack

```
┌───────────────────────────────────────────────────────────────┐
│ App target: DependencyContainer, Coordinators, Route Shells   │
├───────────────┬───────────────┬───────────────┬──────────────┤
│ Feature* SPM  │ Feature* SPM  │ Feature* SPM  │ Feature* SPM │
│ View + VM     │ View + VM     │ View + VM     │ View + VM    │
├───────────────────────────────────────────────────────────────┤
│ Data SPM: repository impls, remote/local, retry, sync queue   │
├───────────────────────────────────────────────────────────────┤
│ Domain SPM: models, repository protocols, coordinator protocols│
│ and ErrorRouting/AppError                                      │
├───────────────────────────────────────────────────────────────┤
│ Shared SPMs: DesignSystem, SharedKit                           │
└───────────────────────────────────────────────────────────────┘
```

**Dependency Rule**: Feature modules import `Domain` + `DesignSystem` only. Features never import `Data` or other features. App target is the only convergence point.


## Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

- Feature modules import `Domain` + `DesignSystem` only (never `Data`, never sibling features)
- App target is the convergence point and owns `DependencyContainer`, concrete coordinators, and Route Shell wiring
- `Domain` stays pure Swift and defines models plus repository, `*Coordinating`, `ErrorRouting`, and `AppError` contracts
- `Data` owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
- Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
- ViewModels call repository protocols directly (no default use-case/interactor layer)

## When to Apply

Reference these guidelines when:
- Building or refactoring feature modules under local SPM packages
- Wiring coordinators, route shells, and dependency container factories
- Defining Domain protocols for repositories, coordinators, and error routing
- Enforcing Data-only ownership of networking, persistence, and sync
- Reviewing stale-while-revalidate reads and optimistic queued writes

## Non-Negotiable Constraints (iOS 26 / Swift 6.2)

- `@Observable` for ViewModels/coordinators, `ObservableObject` / `@Published` never
- No dedicated use-case/interactor layer: ViewModels call Domain repository protocols directly
- Coordinator protocols live in Domain; concrete coordinators own `NavigationPath` in App target
- Route shells live in App target and own `.navigationDestination` mapping
- `AppError` + `ErrorRouting` drive presentation policy; ViewModels do not hardcode global error UI
- SwiftData / URLSession / retry / sync queue logic stays in Data package only

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | View Identity & Diffing | CRITICAL | `diff-` | 6 |
| 2 | State Architecture | CRITICAL | `state-` | 7 |
| 3 | View Composition | HIGH | `view-` | 6 |
| 4 | Navigation & Coordination | HIGH | `nav-` | 5 |
| 5 | Layer Architecture | HIGH | `layer-` | 6 |
| 6 | Dependency Injection | MEDIUM-HIGH | `di-` | 4 |
| 7 | List & Collection Performance | MEDIUM | `list-` | 4 |
| 8 | Async & Data Flow | MEDIUM | `data-` | 5 |

## Quick Reference

### 1. View Identity & Diffing (CRITICAL)

- [`diff-equatable-views`](references/diff-equatable-views.md) - Apply @Equatable macro to every SwiftUI view
- [`diff-closure-skip`](references/diff-closure-skip.md) - Use @SkipEquatable for closure/handler properties
- [`diff-reference-types`](references/diff-reference-types.md) - Never store reference types without Equatable conformance
- [`diff-identity-stability`](references/diff-identity-stability.md) - Use stable O(1) identifiers in ForEach
- [`diff-avoid-anyview`](references/diff-avoid-anyview.md) - Never use AnyView — use @ViewBuilder or generics
- [`diff-printchanges-debug`](references/diff-printchanges-debug.md) - Use _printChanges() to diagnose unnecessary re-renders

### 2. State Architecture (CRITICAL)

- [`state-observable-class`](references/state-observable-class.md) - Use @Observable classes for all ViewModels
- [`state-ownership`](references/state-ownership.md) - @State for owned data, plain property for injected data
- [`state-single-source`](references/state-single-source.md) - One source of truth per piece of state
- [`state-scoped-observation`](references/state-scoped-observation.md) - Leverage @Observable property-level tracking
- [`state-binding-minimal`](references/state-binding-minimal.md) - Pass @Binding only for two-way data flow
- [`state-environment-global`](references/state-environment-global.md) - Use @Environment for app-wide shared dependencies
- [`state-no-published`](references/state-no-published.md) - Never use @Published or ObservableObject

### 3. View Composition (HIGH)

- [`view-body-complexity`](references/view-body-complexity.md) - Maximum 10 nodes in view body
- [`view-extract-subviews`](references/view-extract-subviews.md) - Extract computed properties/helpers into separate View structs
- [`view-no-logic-in-body`](references/view-no-logic-in-body.md) - Zero business logic in body
- [`view-minimal-dependencies`](references/view-minimal-dependencies.md) - Pass only needed properties, not entire models
- [`view-viewbuilder-composition`](references/view-viewbuilder-composition.md) - Use @ViewBuilder for conditional composition
- [`view-no-init-sideeffects`](references/view-no-init-sideeffects.md) - Never perform work in View init

### 4. Navigation & Coordination (HIGH)

- [`nav-coordinator-pattern`](references/nav-coordinator-pattern.md) - Every feature has a coordinator owning NavigationStack
- [`nav-routes-enum`](references/nav-routes-enum.md) - Define all routes as a Hashable enum
- [`nav-deeplink-support`](references/nav-deeplink-support.md) - Coordinators must support URL-based deep linking
- [`nav-modal-sheets`](references/nav-modal-sheets.md) - Present modals via coordinator, not inline
- [`nav-no-navigationlink`](references/nav-no-navigationlink.md) - Never use NavigationLink(destination:) — use navigationDestination(for:)

### 5. Layer Architecture (HIGH)

- [`layer-dependency-rule`](references/layer-dependency-rule.md) - Domain layer has zero framework imports
- [`layer-usecase-protocol`](references/layer-usecase-protocol.md) - Do not add a use-case layer; keep orchestration in ViewModel + repository protocols
- [`layer-repository-protocol`](references/layer-repository-protocol.md) - Repository protocols in Domain, implementations in Data
- [`layer-model-value-types`](references/layer-model-value-types.md) - Domain models are structs, never classes
- [`layer-no-view-repository`](references/layer-no-view-repository.md) - Views never access repositories directly; ViewModel calls repository protocols
- [`layer-viewmodel-boundary`](references/layer-viewmodel-boundary.md) - ViewModels expose display-ready state only

### 6. Dependency Injection (MEDIUM-HIGH)

- [`di-environment-injection`](references/di-environment-injection.md) - Inject container-managed protocol dependencies via @Environment
- [`di-protocol-abstraction`](references/di-protocol-abstraction.md) - All injected dependencies are protocol types
- [`di-container-composition`](references/di-container-composition.md) - Compose `DependencyContainer` in App target and expose VM factories
- [`di-mock-testing`](references/di-mock-testing.md) - Every protocol dependency has a mock for testing

### 7. List & Collection Performance (MEDIUM)

- [`list-constant-viewcount`](references/list-constant-viewcount.md) - ForEach must produce constant view count per element
- [`list-filter-in-model`](references/list-filter-in-model.md) - Filter/sort in ViewModel, never inside ForEach
- [`list-lazy-stacks`](references/list-lazy-stacks.md) - Use LazyVStack/LazyHStack for unbounded content
- [`list-id-keypath`](references/list-id-keypath.md) - Provide explicit id keyPath — never rely on implicit identity

### 8. Async & Data Flow (MEDIUM)

- [`data-task-modifier`](references/data-task-modifier.md) - Use `.task(id:)` as the primary feature data-loading trigger
- [`data-async-init`](references/data-async-init.md) - Never perform async work in init
- [`data-error-loadable`](references/data-error-loadable.md) - Model loading states as enum, not booleans
- [`data-combine-avoid`](references/data-combine-avoid.md) - Prefer async/await over Combine for new code
- [`data-cancellation`](references/data-cancellation.md) - Use .task automatic cancellation — never manage Tasks manually

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Mobile →

From the same set139

The whole set →
ruby-optimise The ruby-optimise skill guides Ruby code reviews and refactors around performance. Use it when working with allocations, collections, ActiveRecord queries, or runtime settings. CX Codex +1 292installs swift-refactor swift-refactor is a Claude Code skill for reshaping existing SwiftUI code around a modular MVVM-C architecture. It applies to work on navigation, state, and app layer boundaries. CX Codex +1 289installs ios-testing ios-testing is a Claude Code skill for testing modular apps on iOS 26 and Swift 6.2. It guides unit, UI, and snapshot tests with protocol mocks and actor isolation. CX Codex +1 288installs dev-rfc dev-rfc guides coding agents through writing technical proposals, system design docs, and architecture overviews with structured templates. CX Codex +1 286installs ios-taste ios-taste designs iOS 18+ SwiftUI views guided by user context and emotional intent instead of defaulting to generic lists. CX Codex +1 280installs ios-storyboard ios-storyboard — a 45-rule guide for maintaining legacy Xcode Storyboard scenes and resolving merge conflicts in Swift 6.2 codebases. Useful when preparing UIKit migrations to SwiftUI. CX Codex +1 277installs rails-design-system A skill with 51 rules for building a Rails design system. When to extract partials, components, helpers, Turbo Frames and Stimulus controllers. CX Codex +1 276installs ios-navigation ios-navigation enforces strict SwiftUI navigation rules for clinic modular MVVM-C apps in Swift 6.2. Helps structure coordinator flows, modal sheets, and deep links. CX Codex +1 275installs

Project sponsors

Companies that keep this analytics open