Swiftui Ui Patterns

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

Security Scan

This is an instruction-only guidance skill for SwiftUI patterns; its declared requirements and runtime instructions match its stated purpose and it does not request credentials, install code, or perform unexpected actions.

Purpose & Capability

The name and description (SwiftUI best practices and examples) align with the provided files: SKILL.md plus multiple component reference docs. The skill declares no binaries, no env vars, and no install steps — all proportional for a documentation-style guidance skill.

Instruction Scope

Runtime instructions are documentation-driven: advice for scaffolding, state management, sheet patterns, and searching the current repo for examples (e.g., 'rg "TabView("'). The instructions ask the agent to inspect repository files for relevant examples, which is coherent with a coding-assistant use case and does not direct reading or exfiltration of unrelated system data or external endpoints.

Install Mechanism

No install specification or external downloads are present. This is the lowest-risk class (instruction-only) and nothing is written to disk or fetched as part of an install step.

Credentials

The skill requests no environment variables, credentials, or config paths. All environment-like concepts in the docs are SwiftUI design constructs (e.g., @Environment, Environment objects) and not runtime platform secrets — proportional to the stated purpose.

Persistence & Privilege

Flags show always:false and user-invocable:true (defaults). The skill does not request persistent presence or elevated privileges and contains no instructions to modify other skill or system configurations.

Assessment

This skill is documentation-only and appears safe: it contains best-practice guidance and repo-file references for SwiftUI. Before installing, consider: (1) the agent may read files in your project (the docs explicitly advise searching the repo for examples), so only enable it if you’re comfortable with that level of file access; (2) it does not install or request credentials, so there is no network or secret access implied by the package itself; (3) as with any automated assistant, review its suggested code changes before applying them to ensure they match your project conventions and security requirements.

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.