swiftui-ui-patterns

Name: swiftui-ui-patterns
Author: Thomas Ricouard

SwiftUIiOSUI/UXMobile DevelopmentSwiftUI PatternsApp ArchitectureFront-end

⭐ 3.7k📄 MIT🕒 2026-03-29Source ↗

Install this skill

npx skills add dimillian/skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

The swiftui-ui-patterns skill serves as a structural guide for building consistent, performant interfaces within the codebase. It emphasizes a modern approach to declarative UI, prioritizing native state management—specifically @Observable and @State—over older View Model patterns. By standardizing view composition, navigation flows, and sheet management, the skill ensures that new features align with the established architectural constraints. The framework discourages redundant logic, favoring small, reusable subviews and dependency injection via @Environment. Whether scaffolding a navigation stack or implementing item-driven modals, this skill enforces a strict separation between UI declaration and business logic. It streamlines development by providing clear rules for data flow, error handling, and component lifecycle, ensuring that the resulting views remain predictable and maintainable throughout the project's life cycle.

When to Use This Skill

•Scaffolding a new navigation-heavy screen structure
•Implementing modal interaction flows for editing data models
•Standardizing state injection for shared dependency access
•Refactoring legacy views into modern SwiftUI components

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“set up a new SwiftUI screen based on project patterns
“how do I wire a sheet that edits an item?
“show me the standard way to inject environment dependencies
“what is the preferred pattern for a navigation stack?
“create a new view following the repository guidelines

Pro Tips

💡Always start by identifying your primary interaction model (list, detail, editor, tabbed) to quickly pinpoint relevant examples and patterns within the skill's content.
💡Leverage the 'existing project' quick start section when improving legacy SwiftUI code, focusing on applying local conventions and environment injection for shared dependencies.
💡Combine this skill with a general 'iOS App Architecture' skill to ensure your UI patterns fit seamlessly into a larger, well-structured application.

What this skill does

•Standardizes sheet presentation using item-driven syntax
•Enforces native state management via @Observable and @Environment
•Provides templates for TabView and NavigationStack wiring
•Facilitates consistent async data loading using .task
•Organizes view hierarchy into modular subviews

When not to use it

✕Projects requiring legacy UIKit integration or older iOS version support
✕Complex animation systems that fall outside standard SwiftUI component patterns

Example workflow

Select the appropriate component from the reference index
Define necessary state variables using @State or @Observable
Wire the NavigationStack or TabView using the standard scaffold
Implement the UI hierarchy with extracted subviews
Connect async operations using the .task modifier
Attach sheet modals using the item-driven approach

Prerequisites

–Basic knowledge of SwiftUI declarative syntax
–Familiarity with the project's folder structure

Pitfalls & limitations

!Over-reliance on external view models instead of native state
!Using .sheet(isPresented:) instead of the preferred item-based approach
!Passing large amounts of data through initializers instead of environment injection

FAQ

Why should I avoid view models?

The project standardizes on native SwiftUI state management like @Observable to simplify data flow and reduce unnecessary object bloat.

Should my sheet handle its own actions?

Yes, sheets are expected to own their internal state and call dismiss() independently once their specific action is completed.

Where do I look for component examples?

Consult the references/components-index.md file for a mapped list of patterns and their corresponding file locations in the repository.

How it compares

Unlike manual coding which often leads to architectural drift, this skill enforces a repo-wide standard that ensures every developer produces code following the same structural conventions.

Source & trust

⭐ 3.7k stars📄 MIT🕒 Updated 2026-03-29

View original skill on GitHub →

📄 Full skill instructions — original source: dimillian/skills

# SwiftUI UI Patterns

## Quick start

Choose a track based on your goal:

### Existing project

- Identify the feature or screen and the primary interaction model (list, detail, editor, settings, tabbed).
- Find a nearby example in the repo with rg "TabView\(" or similar, then read the closest SwiftUI view.
- Apply local conventions: prefer SwiftUI-native state, keep state local when possible, and use environment injection for shared dependencies.
- Choose the relevant component reference from references/components-index.md and follow its guidance.
- Build the view with small, focused subviews and SwiftUI-native data flow.

### New project scaffolding

- Start with references/app-scaffolding-wiring.md to wire TabView + NavigationStack + sheets.
- Add a minimal AppTab and RouterPath based on the provided skeletons.
- Choose the next component reference based on the UI you need first (TabView, NavigationStack, Sheets).
- Expand the route and sheet enums as new screens are added.

## General rules to follow

- Use modern SwiftUI state (@State, @Binding, @Observable, @Environment) and avoid unnecessary view models.
- Prefer composition; keep views small and focused.
- Use async/await with .task and explicit loading/error states.
- Maintain existing legacy patterns only when editing legacy files.
- Follow the project's formatter and style guide.
- **Sheets**: Prefer .sheet(item:) over .sheet(isPresented:) when state represents a selected model. Avoid if let inside a sheet body. Sheets should own their actions and call dismiss() internally instead of forwarding onCancel/onConfirm closures.

## Workflow for a new SwiftUI view

1. Define the view's state and its ownership location.
2. Identify dependencies to inject via @Environment.
3. Sketch the view hierarchy and extract repeated parts into subviews.
4. Implement async loading with .task and explicit state enum if needed.
5. Add accessibility labels or identifiers when the UI is interactive.
6. Validate with a build and update usage callsites if needed.

## Component references

Use references/components-index.md as the entry point. Each component reference should include:
- Intent and best-fit scenarios.
- Minimal usage pattern with local conventions.
- Pitfalls and performance notes.
- Paths to existing examples in the current repo.

## Sheet patterns

### Item-driven sheet (preferred)

@State private var selectedItem: Item?

.sheet(item: $selectedItem) { item in
    EditItemSheet(item: item)
}

### Sheet owns its actions

struct EditItemSheet: View {
    @Environment(\.dismiss) private var dismiss
    @Environment(Store.self) private var store

    let item: Item
    @State private var isSaving = false

    var body: some View {
        VStack {
            Button(isSaving ? "Saving…" : "Save") {
                Task { await save() }
            }
        }
    }

    private func save() async {
        isSaving = true
        await store.save(item)
        dismiss()
    }
}

## Adding a new component reference

- Create references/<component>.md.
- Keep it short and actionable; link to concrete files in the current repo.
- Update references/components-index.md with the new entry.

By Thomas Ricouard

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/swiftui-ui-patterns/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/dimillian/skills/swiftui-ui-patterns/SKILL.md
Cursor: ~/.cursor/skills/dimillian/skills/swiftui-ui-patterns/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/dimillian/skills/swiftui-ui-patterns/SKILL.md