remlostime/swiftui-expert-skill

SwiftUI Expert Skill

Operating Rules

• Consult references/latest-apis.md at the start of every task to avoid deprecated APIs
• Prefer native SwiftUI APIs over UIKit/AppKit bridging unless bridging is necessary
• Focus on correctness and performance; do not enforce specific architectures (MVVM, VIPER, etc.)
• Encourage separating business logic from views for testability without mandating how
• Follow Apple's Human Interface Guidelines and API design patterns
• Only adopt Liquid Glass when explicitly requested by the user (see references/liquid-glass.md)
• Present performance optimizations as suggestions, not requirements
• Use #available gating with sensible fallbacks for version-specific APIs

Task Workflow

Review existing SwiftUI code

• Read the code under review and identify which topics apply
• Flag deprecated APIs (compare against references/latest-apis.md)
• Run the Topic Router below for each relevant topic
• Validate #available gating and fallback paths for iOS 26+ features

Improve existing SwiftUI code

• Audit current implementation against the Topic Router topics
• Replace deprecated APIs with modern equivalents from references/latest-apis.md
• Refactor hot paths to reduce unnecessary state updates
• Extract complex view bodies into separate subviews
• Suggest image downsampling when UIImage(data:) is encountered (optional optimization, see references/image-optimization.md)

Implement new SwiftUI feature

• Design data flow first: identify owned vs injected state
• Structure views for optimal diffing (extract subviews early)
• Apply correct animation patterns (implicit vs explicit, transitions)
• Use Button for all tappable elements; add accessibility grouping and labels
• Gate version-specific APIs with #available and provide fallbacks

Topic Router

Consult the reference file for each topic relevant to the current task:

| Topic | Reference | |-------|-----------| | State management | references/state-management.md | | View composition | references/view-structure.md | | Performance | references/performance-patterns.md | | Lists and ForEach | references/list-patterns.md | | Layout | references/layout-best-practices.md | | Sheets and navigation | references/sheet-navigation-patterns.md | | ScrollView | references/scroll-patterns.md | | Focus management | references/focus-patterns.md | | Animations (basics) | references/animation-basics.md | | Animations (transitions) | references/animation-transitions.md | | Animations (advanced) | references/animation-advanced.md | | Accessibility | references/accessibility-patterns.md | | Swift Charts | references/charts.md | | Charts accessibility | references/charts-accessibility.md | | Image optimization | references/image-optimization.md | | Liquid Glass (iOS 26+) | references/liquid-glass.md | | macOS scenes | references/macos-scenes.md | | macOS window styling | references/macos-window-styling.md | | macOS views | references/macos-views.md | | Deprecated API lookup | references/latest-apis.md |

Correctness Checklist

These are hard rules -- violations are always bugs:

• [ ] @State properties are private
• [ ] @Binding only where a child modifies parent state
• [ ] Passed values never declared as @State or @StateObject (they ignore updates)
• [ ] @StateObject for view-owned objects; @ObservedObject for injected
• [ ] iOS 17+: @State with @Observable; @Bindable for injected observables needing bindings
• [ ] ForEach uses stable identity (never .indices for dynamic content)
• [ ] Constant number of views per ForEach element
• [ ] .animation(_:value:) always includes the value parameter
• [ ] @FocusState properties are private
• [ ] No redundant @FocusState writes inside tap gesture handlers on .focusable() views
• [ ] iOS 26+ APIs gated with #available and fallback provided
• [ ] import Charts present in files using chart types

References

• references/latest-apis.md -- Read first for every task. Deprecated-to-modern API transitions (iOS 15+ through iOS 26+)
• references/state-management.md -- Property wrappers, data flow, @Observable migration
• references/view-structure.md -- View extraction, container patterns, @ViewBuilder
• references/performance-patterns.md -- Hot-path optimization, update control, _logChanges()
• references/list-patterns.md -- ForEach identity, Table (iOS 16+), inline filtering pitfalls
• references/layout-best-practices.md -- Layout patterns, GeometryReader alternatives
• references/accessibility-patterns.md -- VoiceOver, Dynamic Type, grouping, traits
• references/animation-basics.md -- Implicit/explicit animations, timing, performance
• references/animation-transitions.md -- View transitions, matchedGeometryEffect, Animatable
• references/animation-advanced.md -- Phase/keyframe animations (iOS 17+), @Animatable macro (iOS 26+)
• references/charts.md -- Swift Charts marks, axes, selection, styling, Chart3D (iOS 26+)
• references/charts-accessibility.md -- Charts VoiceOver, Audio Graph, fallback strategies
• references/sheet-navigation-patterns.md -- Sheets, NavigationSplitView, Inspector
• references/scroll-patterns.md -- ScrollViewReader, programmatic scrolling
• references/focus-patterns.md -- Focus state, focusable views, focused values, default focus, common pitfalls
• references/image-optimization.md -- AsyncImage, downsampling, caching
• references/liquid-glass.md -- iOS 26+ Liquid Glass effects and fallback patterns
• references/macos-scenes.md -- Settings, MenuBarExtra, WindowGroup, multi-window
• references/macos-window-styling.md -- Toolbar styles, window sizing, Commands
• references/macos-views.md -- HSplitView, Table, PasteButton, AppKit interop

Maintenance Guidelines

This section governs how the skill itself should be updated and extended.

Scope

This is a SwiftUI skill. Content must be SwiftUI-specific. Do not add:

• Swift concurrency deep dives (actors, Sendable, etc.) unless directly tied to a SwiftUI API like .task
• General Swift language features unrelated to SwiftUI
• Backend or server-side Swift patterns
• UIKit patterns (except when bridging is necessary)
• Code formatting, linting, or property ordering rules
• Architectural mandates (MVVM, VIPER, coordinator patterns, etc.)
• IDE or tool-specific instructions (Instruments, debuggers, build systems)
• Testing frameworks or file structure requirements

Language and Tone

• Use "consider" or "suggest" for optional optimizations (e.g., "Consider downsampling images when using UIImage(data:)").
• Use "avoid" for anti-patterns (e.g., "Avoid X because Y").
• Use "always" or "never" only for correctness issues where violations are bugs.
• Do not apply optimizations automatically; let developers decide based on their performance needs.

Before Adding New Content

Ask these four questions:

1. Is this SwiftUI-specific?
2. Is this a fact or an opinion?
3. Can agents actually use this information?
4. Is this about correctness or style?

If unsure, err on the side of excluding content. A focused, factual skill is better than a comprehensive but opinionated one.

Related Maintenance Tools

• agent-skills/update-swiftui-apis/SKILL.md (if present) -- Scan Apple's SwiftUI documentation, identify deprecated APIs and their modern replacements, and update references/latest-apis.md. Use after new iOS/Xcode releases.