SwiftUI Components

Lifecycle Position

Phase 3 (Implement). After design from macos-app-design. Use templates and patterns during implementation. Next: swiftui-view-refactor for Phase 5 review.

Quick Start

For standard patterns, see PATTERNS.md. For API reference, see REFERENCE.md.

Instructions

When creating or refactoring SwiftUI components:

1. Analyze the required component functionality

   • What data does the component display?
   • What interactions does it support?
   • Does it need Liquid Glass effects?

2. Check existing components for reuse

   • Grep the project for similar views before creating new ones
   • Check if a custom ViewModifier already covers the styling need
   • Look for shared PreferenceKey definitions

3. Apply templates from templates/ directory

   • view-template.swift — Standard view with @Observable ViewModel, .task lifecycle, accessibility
   • viewmodel-template.swift — @Observable @MainActor ViewModel with repository DI pattern
   • modifier-template.swift — Custom ViewModifier with View extension and conditional application
   • glass-component-template.swift — Liquid Glass component with GlassEffectContainer, glassEffectID, morph transitions, backgroundExtensionEffect, and toolbar grouping
   • templates/onboarding/ — Complete paged onboarding flow with persistence and view modifier
   • templates/settings/ — Cross-platform settings screen (iOS + macOS) with @Observable model

4. Follow project styling conventions

   • Use semantic colors (.primary, .secondary, .tertiary) over hardcoded colors
   • Prefer .font(.body) system text styles over fixed font sizes
   • Use RoundedRectangle(cornerRadius:) and ConcentricRectangle for shapes
   • Apply .accessibilityLabel to all icon-only buttons
   • Use .task {} instead of .onAppear { Task { } } for async work

Component Checklist

Before submitting a new component, verify:

• View is under 100 lines (extract subviews if larger)
• @Observable used for view models (not ObservableObject)
• @MainActor on view model class
• Repository/service dependencies injected via init (not hardcoded)
• .task {} used for async loading (auto-cancels on disappear)
• accessibilityLabel on icon-only buttons and decorative images
• Dynamic Type supported (no hardcoded font sizes)
• Dark mode tested (use semantic colors)
• Reduce Transparency and Reduce Motion tested for glass effects
• [weak self] in stored closures and Timer callbacks
• Sendable conformance verified for types crossing isolation boundaries
• Preview provided with #Preview { } macro

Liquid Glass Guidelines

When applying Liquid Glass to custom components:

1. Use sparingly — only on the most important functional elements
2. Always wrap in GlassEffectContainer — required for performance and morph animations
3. Assign glassEffectID when glass views should morph during transitions
4. Apply .backgroundExtensionEffect() to hero images in split views
5. Group toolbar items with ToolbarSpacer(.fixed) for separate glass backgrounds
6. Remove custom backgrounds on toolbars, tab bars, and navigation bars — they block glass
7. Use .buttonStyle(.glass) instead of custom glass effects on buttons
8. Test with accessibility — Reduce Transparency removes glass; ensure fallback looks good

Templates

Base Templates (templates/)

• view-template.swift — Standard view with @Observable ViewModel, .task lifecycle, accessibility
• viewmodel-template.swift — @Observable @MainActor ViewModel with repository DI pattern
• modifier-template.swift — Custom ViewModifier with View extension and conditional application
• glass-component-template.swift — Liquid Glass component with GlassEffectContainer, glassEffectID, morph transitions, backgroundExtensionEffect, and toolbar grouping

Onboarding Flow (templates/onboarding/)

Complete paged onboarding with persistence and view modifier:

• OnboardingView.swift — TabView-based paged flow with page indicators
• OnboardingPage.swift — Data model for onboarding page content
• OnboardingPageView.swift — Individual page layout (icon, title, description)
• OnboardingStorage.swift — @AppStorage-backed completion tracking
• OnboardingModifier.swift — .onboarding() view modifier for one-time display

Settings Screen (templates/settings/)

Cross-platform settings with iOS + macOS support:

• SettingsView.swift — Root settings view with platform-adaptive layout
• AppSettings.swift — @Observable settings model with persistence
• SettingsRow.swift — Reusable row component for settings sections
• AboutSettingsView.swift — App info, version, credits
• AccountSettingsView.swift — Account management section

File Structure

skills/swiftui-components/
├── SKILL.md              ← You are here (entry point)
├── references/           ← Deep documentation by category (scraped from Apple docs)
│   ├── PATTERNS.md       ← ViewModifier, ViewBuilder, PreferenceKey, Layout, composition patterns
│   ├── REFERENCE.md      ← API quick-reference tables for SwiftUI protocols, wrappers, and modifiers
│   ├── views_builtin.md
│   ├── modifiers_styling.md
│   ├── modifiers_interaction.md
│   ├── layout_system.md
│   ├── shapes_and_drawing.md
│   ├── animation_and_transitions.md
│   ├── data_flow.md
│   ├── presentations.md
│   └── index.md
└── templates/            ← Copy-paste-ready Swift templates
    ├── view-template.swift
    ├── viewmodel-template.swift
    ├── modifier-template.swift
    ├── glass-component-template.swift
    ├── onboarding/       ← Complete onboarding flow (5 files)
    │   ├── OnboardingView.swift
    │   ├── OnboardingPage.swift
    │   ├── OnboardingPageView.swift
    │   ├── OnboardingStorage.swift
    │   └── OnboardingModifier.swift
    └── settings/         ← Cross-platform settings screen (5 files)
        ├── SettingsView.swift
        ├── AppSettings.swift
        ├── SettingsRow.swift
        ├── AboutSettingsView.swift
        └── AccountSettingsView.swift

Companion Skills & Agents

• macos-architect — Consult for architectural decisions (navigation patterns, multi-window, state management hierarchy)
• swift-reviewer — Run code reviews against Swift 6 concurrency, memory, Liquid Glass, and accessibility standards
• apple-liquid-glass-design — Deep reference for all Liquid Glass APIs and the Landmarks sample app

Data Source

This skill was generated from 170+ Apple documentation pages via:

skill-seekers scrape --config configs/swiftui-components.json

To refresh with updated documentation, re-run the scrape.